In FastAPI, when a dependency and the endpoint both add tasks to BackgroundTasks, in what order and on which threads do they run?
answer
- one object per request
- dependencies resolve before the endpoint body
- awaited one at a time
- run_in_threadpool for def
basics
~20 sBoth get the same per-request BackgroundTasks, so the tasks run as one list in the order add_task was called, one at a time, after the response: def tasks on a thread-pool thread, async def tasks on the event loop.
solid answer
~40 sFastAPI creates one `BackgroundTasks` object per request and passes that same object to every endpoint, dependency and sub-dependency that declares the type, so all `add_task` calls append to one list. Dependencies are resolved before the endpoint body runs, so a task a dependency adds normally comes before the endpoint's. After the response has been sent, the list is walked in order and each task is awaited before the next starts; no two tasks of one request run at the same time. A `def` task goes through Starlette's `run_in_threadpool`, using one of anyio's worker threads, while an `async def` task is awaited on the event loop, where a blocking call such as `time.sleep` stalls every request that worker is serving.
code
python · 25 linesfrom typing import Annotated
from fastapi import BackgroundTasks, Depends, FastAPI
app = FastAPI()
async def write_audit_line(event: str) -> None:
print(f"1. audit: {event}") # async def: awaited on the event loop
def send_welcome_email(email: str) -> None:
print(f"2. email: {email}") # def: run in a thread-pool worker thread
def audit_signup(background_tasks: BackgroundTasks) -> None:
# resolved before the endpoint body runs, so this task is queued first
background_tasks.add_task(write_audit_line, "signup")
@app.post("/signup", status_code=201, dependencies=[Depends(audit_signup)])
async def signup(email: str, background_tasks: BackgroundTasks):
# the same BackgroundTasks object the dependency received
background_tasks.add_task(send_welcome_email, email)
return {"email": email}go deeper
Remember that the endpoint and its dependencies share one BackgroundTasks object and the tasks run after the response, in the order they were added.
Explain the sequential loop, why dependencies queue first, and the split between run_in_threadpool for def tasks and the event loop for async def tasks.
Show how one slow or blocking task hurts others: it delays the rest of the list, holds a thread-pool slot shared with def endpoints, or freezes the loop if written as async def.
Decide whether a team relies on implicit ordering between dependencies and endpoints, or requires order-sensitive follow-ups to be queued from a single place.
## One list per request `BackgroundTasks` is a **request-scoped object**. When FastAPI resolves a request, it creates at most one instance and hands that **same instance** to every place that declares a parameter of that type: - the path operation function; - a dependency or sub-dependency declared with `Depends`; - a dependency listed in the decorator's `dependencies=[...]`, a router's or the app's. Each `add_task` call appends a recorded call to the instance's internal `tasks` list. The FastAPI documentation describes this as all the background tasks being *merged together* and run afterwards. There is no per-dependency list and no priority: the list order is simply the order in which `add_task` was executed. ## Why the dependency's task usually comes first FastAPI resolves the whole dependency graph **before** it calls the endpoint. A dependency that queues an audit line therefore calls `add_task` before the endpoint body gets a chance to queue the welcome email: ```python from fastapi import BackgroundTasks, Depends, FastAPI app = FastAPI() async def write_audit_line(event: str) -> None: ... def send_welcome_email(email: str) -> None: ... def audit_signup(background_tasks: BackgroundTasks) -> None: background_tasks.add_task(write_audit_line, "signup") @app.post("/signup", status_code=201, dependencies=[Depends(audit_signup)]) async def signup(email: str, background_tasks: BackgroundTasks): background_tasks.add_task(send_welcome_email, email) return {"email": email} ``` After the response, `write_audit_line` runs first and `send_welcome_email` second. If the order matters for correctness, make it explicit by queuing both from one place rather than relying on how the graph happens to resolve. ## How the list is executed Once the status line, headers and body have been sent, the response object awaits its background list: 1. Take the next recorded call. 2. If the function is a coroutine function (`async def`), await it on the event loop. 3. Otherwise, call it through `run_in_threadpool`, which hands it to `anyio.to_thread.run_sync` and waits for the worker thread to finish. 4. Move to the next call only when this one has returned. So the tasks of **one request are strictly sequential**. Tasks belonging to different requests are independent of each other: each request awaits its own list, so they interleave on the event loop like any other request handling. | Task written as | Where it runs | What a blocking call does | |---|---|---| | `def` | an anyio worker thread, via `run_in_threadpool` | holds one thread-pool slot until it returns | | `async def` | the event loop of that worker process | freezes every request on that worker | ## Consequences worth stating in an interview - **A slow first task delays the second.** A mail-server call that takes ten seconds pushes the audit line ten seconds back. - **A failing task ends the list.** An exception propagates out of the loop, so later tasks of that request are skipped. - **`def` tasks compete with `def` endpoints.** They draw on the same anyio default thread limiter as `def` path operations and dependencies, so a burst of slow `def` tasks can starve ordinary requests of threads. - **`async def` is not a free upgrade.** An `async def` task must only await non-blocking calls; a synchronous client library inside it blocks the loop exactly as it would inside an `async def` endpoint. - **Choose the function style by what it calls**, not by habit: blocking I/O in a `def` task, awaitable I/O in an `async def` task. ## Picking `def` or `async def` for a task The rule is the same one FastAPI applies to endpoints, and it is decided by what the task calls, not by what the endpoint is: - a task that uses a **synchronous** mail or HTTP client library should be a plain `def`, so it lands on a worker thread; - a task that only awaits **asynchronous** clients can be `async def` and avoids a thread hop; - a task that mixes both can be `async def` and push the blocking part to a thread with `anyio.to_thread.run_sync`. An `async def` endpoint may queue a `def` task and the reverse; each task is dispatched on its own definition. ## Checking it in a test `fastapi.testclient.TestClient` returns from `client.post(...)` only after the request's tasks have run, so a test can assert on their side effects directly after the call. That makes the order easy to pin down with a list the tasks append to.
- Do the background tasks of two different FastAPI requests wait for each other?No. Each request awaits its own `BackgroundTasks` list after its own response, so tasks from different requests interleave on the event loop like any other request work. They still share resources: `def` tasks draw threads from the same anyio limiter, and a blocking `async def` task stalls everything on that worker.
- How would you run two independent FastAPI background tasks concurrently instead of one after the other?`BackgroundTasks` itself always runs them in sequence. Queue a single `async def` task that starts both with an anyio task group and awaits them; if they are blocking, offload each with `anyio.to_thread.run_sync` inside that group.
- Each add_task call starts its own thread, so the tasks run in parallel
- The endpoint's tasks always run before tasks added by its dependencies
- An async def task can call blocking libraries safely because the response is already sent
- Every dependency receives its own BackgroundTasks list, run separately
- def background tasks use a separate thread pool from def endpoints