How to schedule tasks to run in the background

[Resonanz]

There is official example code in Toga under /examples/handlers.

My questions:

• What is add_background_task(handler) for exactly?
• What does it do that a simple async function cannot do?
• Why not just call an async function containing a while True:

Docs say:

Schedule a task to run in the background
Schedules a coroutine or a generator to run in the background. Control will be returned to the event loop during await or yield statements, respectively. Use this to run background tasks without blocking the GUI. If a regular callable is passed, it will be called as is and will block the GUI until the call returns.

With the following code, I would expect the function bkgnd_task_handler to be called repeatedly, every time thru the event loop, but it only runs once.

def bkgnd_task_handler(self):
    print("Inside bkgnd task handler")

if __name__ == "__main__":
    app = main()
    app.add_background_task(bkgnd_task_handler)
    app.main_loop()

[freakboy3742]

add_background_task installs the function provided in the event loop - but only calls it once. If you've done GUI programming before, it's roughly the equivalent of a "call later" function - it's a guarantee that the function will be called, on the main GUI thread, at some point in the (near-ish) future.

If you want the background handler to be called repeatedly (e.g., a background update function), then it needs to start a loop. However - as soon as you do that, your handler becomes blocking, so you can't use a normal function here.

That's where async handlers come in. If you make the function async, you can make a background handler that doesn't exit - but does yield control to the event loop periodically; e.g.:

async def background_handler(self, app, **kwargs):
    while True:
        print("tick...")
        await asyncio.sleep(1)

will continue to run in the background, waking up every second to print another line of output.

You don't have to make the function fully async, though; If a function yields an integer, Toga will interpret that as a request to sleep; so, that async handler is functionally identical to:

def background_handler(self, app, **kwargs):
    while True:
        print("tick...")
        yield 1

The benefit of the async version over the non-async version is that you can also use any other asycnio function that could potentially block (e.g., an asyncio network request).