Background tasks

If you have a task to perform where the outcome or result isn’t required you can utilise a background task to run it. Background tasks run concurrently with the route handlers etc, i.e. in the background. Background tasks are very useful when they contain actions that take a lot of time to complete, as they allow a response to be sent to the client whilst the task itself is carried out. Equally some tasks just don’t need to be completed before the response is sent and instead can be done in the background.

Background tasks in Quart are created via the add_background_task method:

async def background_task():
    ...

@app.route('/jobs/', methods=['POST'])
async def create_job():
    app.add_background_task(background_task)
    return 'Success'

@app.before_serving
async def startup():
    app.add_background_task(background_task)

The background tasks will have access to the app context. The tasks will be awaited during shutdown to ensure they complete before the app shuts down. If your task does not complete within the config BACKGROUND_TASK_SHUTDOWN_TIMEOUT it will be cancelled.

Note BACKGROUND_TASK_SHUTDOWN_TIMEOUT should ideally be less than any server shutdown timeout.

Synchronous background tasks are supported and will run in a separate thread.

Warning

As Quart is based on asyncio it will run on a single execution and switch between tasks as they become blocked on waiting on IO, if a task does not need to wait on IO it will instead block the event loop and Quart could become unresponsive. Additionally the task will consume the same CPU resources as the server and hence could slow the server.

Testing background tasks

To ensure that background tasks complete in tests utilise the test_app context manager. This will wait for any background tasks to complete before allowing the test to continue:

async def test_tasks_complete():
    async with app.test_app():
        app.add_background_task(...)
    # Background task has completed here
    assert task_has_done_something

Note when testing an app the test_client usage should be within the test_app context block.

The background task coroutine function can be tested by creating an app context and await the function,

async def test_background_task():
    async with app.app_context():
        await background_task()
    assert something_to_test