Graceful Shutdown with AnyIO TaskGroups in FastAPI

Scenario context

🚀 Use async with anyio.create_task_group() to ensure every spawned coroutine is cancelled when the request ends—avoiding orphaned tasks and leaking resources.

Why it matters? In high‑traffic APIs, a forgotten task can keep running after the HTTP response, consuming CPU, memory, and potentially violating data consistency. Structured concurrency guarantees that the lifecycle of background work is bound to…

This walkthrough focuses on The Gotcha.

Before making a design choice, clarify:

• FastAPI’s BackgroundTasks or plain asyncio.create task() spawn fire‑and‑forget coroutines.
• If the request handler returns early, those tasks keep running, sometimes forever, until the event loop shuts down.
• Worse, if a task hits an unhandled exception, the error propagates to the background thread, silently crashing the task without notifying the caller.

Concepts in play: python-concurrency-nogil, consistency-replication

Stage 1 — Structured Concurrency with AnyIO

• AnyIO’s TaskGroup is a context manager that automatically waits for all children and cancels them when the block exits.
• In FastAPI, wrap the request logic inside async with anyio.create task group() as tg: and use tg.start soon() to launch subtasks.
• When the handler returns—or if an exception bubbles up—the group cancels every child coroutine, propagating CancelledError cleanly.
• When the client disconnects or the endpoint returns, AnyIO cancels all heavy worker tasks.

from fastapi import FastAPI, HTTPException
import anyio

app = FastAPI()

async def heavy_worker(id: int, delay: float):
    try:
        await anyio.sleep(delay)
        print(f"Worker {id} finished")
    except anyio.Cancelled:
        print(f"Worker {id} cancelled")
        raise

@app.get("/process")
async def process(request_id: int):
    async with anyio.create_task_group() as tg:
        # Launch multiple workers
        for i in range(5):
            tg.start_soon(heavy_worker, i, delay=10.0)
        # Simulate early return
        if request_id == 0:
            raise HTTPException(status_code=400, detail="Bad request")
        return {"status": "started"}

Observable outcome: When the client disconnects or the endpoint returns, AnyIO cancels all heavy worker tasks.

End-to-end outcome

After working through the stages, you should be able to explain:

• • Always use a TaskGroup (or asyncio.TaskGroup in Python 3.11+) for request‑scoped async work.
• • Avoid asyncio.create task() for long‑running background jobs unless you manage their cancellation explicitly.

Alternatives considered

The source focuses on one primary design. A second architecture is not compared, so no alternative is invented here.

Failure and degraded modes

The source does not isolate a separate failure mode. Limits that matter for the scenario are called out in the stage decisions above.

• • Always use a TaskGroup (or asyncio.TaskGroup in Python 3.11+) for request‑scoped async work.
• • Avoid asyncio.create task() for long‑running background jobs unless you manage their cancellation explicitly.
• AnyIO’s TaskGroup is a context manager that automatically waits for all children and cancels them when the block exits.