skip to content

Thread Pool & Loop

FastAPI runs async def endpoints on the event loop and plain def ones in a thread pool, and runs background tasks after the response. Interviewers ask what a blocking call does inside async def.

on this pageshow

explore

questions

12

In FastAPI, how do you make a sign-up endpoint send a welcome email only after the client has received its response?

level: juniorimportance: must knowfreq 55%

answer

  1. a parameter FastAPI fills in
  2. a class imported from fastapi
  3. pass the function, not its result
  4. add_task with args and kwargs

basics

~10 s

Declare a parameter typed BackgroundTasks, call background_tasks.add_task(send_welcome_email, email) and return normally; FastAPI sends the response first, then calls the function with those arguments in the same process.

solid answer

~40 s

Add a parameter annotated `BackgroundTasks`, imported from `fastapi`, to the path operation; FastAPI creates one per request and injects it, the way it injects `Request`. Call `background_tasks.add_task(send_welcome_email, email, subject="Welcome")`: the first argument is the function itself, the rest are the positional and keyword arguments it will later be called with. Return your response as usual. Once the response has been sent, FastAPI calls each queued function in the order it was added, inside the same worker process: a `def` function through the thread pool, an `async def` function awaited on the event loop. Two slips to avoid: writing `add_task(send_welcome_email(email))`, which sends the email before the response and queues its return value, and reaching for Starlette's singular `BackgroundTask`, which FastAPI does not inject.

code

python · 21 lines
python
from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


def send_welcome_email(email: str, subject: str = "Welcome") -> None:
    # blocking mail-server call; a def task runs in the thread pool
    print(f"sending {subject!r} to {email}")


async def write_audit_line(event: str, email: str) -> None:
    # an async def task is awaited on the event loop
    print(f"audit: {event} {email}")


@app.post("/signup", status_code=201)
async def signup(email: str, background_tasks: BackgroundTasks):
    # ... create the account ...
    background_tasks.add_task(send_welcome_email, email, subject="Welcome aboard")
    background_tasks.add_task(write_audit_line, "signup", email)
    return {"email": email, "status": "created"}

go deeper

for a junior

Recall the three pieces: a parameter typed BackgroundTasks, add_task with the function and its arguments, and a normal return. Say that the task runs after the response.

for a middle

Explain the order of events after the return, why a def task goes through the thread pool while an async def task is awaited, and why passing a called function to add_task is a bug.

for a senior

Point out that the tasks still belong to the request in the same worker: a restart, a failure or a slow task stays your problem, and nobody sees its outcome except the logs.

for a principal

Treat BackgroundTasks as a convention to scope: which follow-ups a team may run in the web process, and which must be handed to a durable queue with retries.

## What the feature is for Some work triggered by a request does not have to finish before the client hears back. A sign-up endpoint has to create the account before it answers, but the welcome email can follow a moment later: the client should not sit waiting several seconds while a mail server is contacted. FastAPI's answer is **`BackgroundTasks`**, a small per-request list of function calls that it runs **after the response has been sent**, in the **same process** that served the request. `BackgroundTasks` is imported from `fastapi`. It is FastAPI's thin subclass of Starlette's class of the same name, offered from `fastapi` so you are not tempted to import Starlette's singular `BackgroundTask` by mistake. ## Declaring it and queuing work You never construct the object yourself. You declare a parameter whose type annotation is `BackgroundTasks`, and FastAPI recognises the type and passes in the request's instance, the same way it recognises `Request`: ```python from fastapi import BackgroundTasks, FastAPI app = FastAPI() def send_welcome_email(email: str, subject: str = "Welcome") -> None: ... # talk to the mail server @app.post("/signup", status_code=201) async def signup(email: str, background_tasks: BackgroundTasks): # ... create the account ... background_tasks.add_task(send_welcome_email, email, subject="Welcome aboard") return {"email": email, "status": "created"} ``` `add_task` takes: - **the function to call later**, passed as an object (`send_welcome_email`), not called; - **any positional arguments** for it, in order (`email`); - **any keyword arguments** for it (`subject="Welcome aboard"`). It returns `None` immediately. Nothing runs at that point; the call is only recorded. ## What happens after you return 1. Your path operation returns its value, and FastAPI builds the response from it. 2. The response's status line, headers and body are sent to the client. 3. FastAPI then calls each recorded function **one after another, in the order they were added**, awaiting each before starting the next. 4. A plain `def` task is run through Starlette's `run_in_threadpool`, on a worker thread, so a blocking mail-server call does not freeze the event loop. An `async def` task is awaited directly on the event loop. The client already has its full response by step 3. The tasks still belong to the request, though: the server's handling of that request is not finished until they are. ## Mistakes that show up in review - **Calling the function inside `add_task`.** `background_tasks.add_task(send_welcome_email(email))` runs the email send immediately, before the response, and queues its return value, usually `None`; after the response, FastAPI tries to call that value and the request fails with a `TypeError` that only the server log shows. - **Importing the wrong class.** `starlette.background.BackgroundTask` (no `s`) is a single task you attach yourself to a `Response` you return through its `background` argument. Used as a parameter type, FastAPI does not inject it; it rejects the route with a `FastAPIError` when the route is declared. - **Creating `BackgroundTasks()` yourself and dropping it.** An instance you build inside the endpoint runs nothing unless you attach it to a response you return. - **Expecting a result.** `add_task` gives you no handle, status or return value. If the client needs to know the outcome, the work does not belong after the response. ## Testing it `fastapi.testclient.TestClient` drives the app in process and returns from `client.post(...)` only after the request's background tasks have run. A test can therefore: - replace the mail sender with a fake, by patching the name the endpoint passes to `add_task` or by making the sender a dependency and swapping it in `app.dependency_overrides`, then assert it was called with the right address; - assert on any side effect directly after the call, without sleeping or polling. That convenience hides one production fact: in a real server the client has its answer long before the task finishes, so a test passing says nothing about how long the task holds the worker. ## Choosing the status code An endpoint that finishes its real work in the request and only sends a notification afterwards still answers `201` or `200`. When the request merely **accepts** work that will be done afterwards, such as processing an uploaded file, the FastAPI documentation suggests answering `202 Accepted`, set with `status_code=202` on the decorator. ## Where it stops being the right tool | Fits `BackgroundTasks` | Better elsewhere | |---|---| | a short call such as a notification email | long or CPU-heavy processing | | work that can use objects from the same app | work that must survive a restart or be retried | | best-effort follow-ups | work another machine should pick up | The FastAPI documentation itself points heavier, multi-process work at a separate task queue such as Celery; `BackgroundTasks` lives and dies with the worker process that served the request.

  • Can a FastAPI dependency add tasks to the same BackgroundTasks object as the endpoint?
    Yes. Declare a `BackgroundTasks` parameter in the dependency, a sub-dependency or the endpoint, and FastAPI passes the same per-request object to all of them. Every `add_task` call lands on one list, and the whole list runs after the response, in the order the calls were made.
  • In FastAPI, how do you attach work to a response you build and return yourself?
    Pass it through the response's `background` argument, for example `JSONResponse(content, background=background_tasks)`; `BackgroundTasks` is a subclass of Starlette's `BackgroundTask`, so the whole list fits there. If the returned response's `background` is left as `None`, FastAPI attaches the injected `BackgroundTasks` to it for you.
  • Does the client wait for the background tasks to finish?
    No. The status, headers and body are sent before the first task starts, so the client has the complete response. The server is still busy with that request until the tasks end, which matters for shutdown and for tests: `TestClient` returns only after the tasks have run.

A waiter brings your bill first and clears your table afterwards: the clearing happens on the same shift, by the same staff, in the order the jobs were noted, and nobody comes back for it if the restaurant shuts suddenly.

  • add_task starts a separate worker process for every queued function
  • Pass send_welcome_email(email) to add_task so the argument is bound
  • Only async def functions can be used as background tasks
  • Background tasks run alongside sending the response, in no fixed order
  • Creating BackgroundTasks() inside the endpoint is enough for its tasks to run
open as a page

In FastAPI, when should a path operation function be declared with plain def, and when with async def?

level: juniorimportance: must knowfreq 80%

basics

~20 s

Use async def when the function awaits an async library or does no blocking I/O; use plain def when it calls a blocking library, because FastAPI runs def functions on a worker thread. When unsure, def is the safer choice.

open as a page

In FastAPI, when a dependency and the endpoint both add tasks to BackgroundTasks, in what order and on which threads do they run?

level: middleimportance: must knowfreq 50%

basics

~20 s

Both 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.

open as a page

A FastAPI async def endpoint calls a synchronous SDK, and latency rises on every endpoint served by that worker; why, and how do you fix it?

level: seniorimportance: must knowfreq 60%

basics

~20 s

FastAPI awaits an async def endpoint on the worker's single event loop, so a blocking SDK call there freezes every request on that worker. Declare the endpoint def, wrap the call in run_in_threadpool, or switch to an async client.

open as a page

In FastAPI, why does a CPU-bound image-thumbnail endpoint slow other requests whether it is declared def or async def?

level: middleimportance: should knowfreq 45%

basics

~20 s

CPU work holds CPython's GIL. Inside async def it runs on FastAPI's event loop and freezes every request on that worker; inside def it runs on a worker thread but shares the GIL with the loop, so other requests still slow.

open as a page

How does FastAPI decide whether a path operation function or a dependency runs on the event loop or in its thread pool?

level: middleimportance: should knowfreq 40%

basics

~20 s

FastAPI 0.143 awaits a callable on the event loop when it is an async def function or an object whose call is async def, after looking through functools.partial and @functools.wraps; anything else goes through run_in_threadpool to an anyio worker thread.

open as a page

Inside a FastAPI async def endpoint, how do run_in_threadpool, anyio.to_thread.run_sync and iterate_in_threadpool differ for running blocking code?

level: middleimportance: should knowfreq 30%

basics

~10 s

run_in_threadpool from fastapi.concurrency wraps anyio.to_thread.run_sync and also forwards keyword arguments; run_sync takes positional arguments plus limiter and abandon_on_cancel; iterate_in_threadpool turns a blocking iterator into an async one, running each next() on a worker thread.

open as a page

In FastAPI, what happens when a function queued with BackgroundTasks.add_task raises an exception after the response was sent?

level: seniorimportance: should knowfreq 35%

basics

~20 s

The client keeps the response it already received. The exception stops the remaining tasks of that request, reaches open yield dependencies and the server error middleware, and ends up as an error in the server log.

open as a page

A FastAPI endpoint queues a welcome email with background_tasks.add_task, then returns JSONResponse(..., background=BackgroundTask(write_audit_line)); why is the email never sent?

level: seniorimportance: should knowfreq 25%

basics

~10 s

FastAPI attaches the injected BackgroundTasks to a returned Response only when that response's background is None. Passing your own BackgroundTask fills the slot, so the queued email is silently discarded.

open as a page

In FastAPI 0.143, can a background task use a database session yielded by a dependency, and what decides whether it is still open?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Yes with the default Depends(scope="request"): FastAPI 0.143 runs that teardown after the response and its background tasks. With scope="function" the session is closed before the response, so the task gets a closed one.

open as a page

A FastAPI service whose def endpoints call a slow blocking database driver stalls near 40 concurrent requests while CPU stays low; what caps it, and how do you raise the cap?

level: seniorimportance: should knowfreq 45%

basics

~20 s

Every def endpoint and dependency borrows a token from anyio's default thread limiter, 40 per event loop, and later calls wait for one. Raise it in the lifespan with anyio.to_thread.current_default_thread_limiter().total_tokens, sized against the database pool and memory.

open as a page

Given what happens to pending BackgroundTasks when a Uvicorn worker shuts down, how would you decide which FastAPI jobs move to a task queue such as Celery?

level: principalimportance: should knowfreq 40%

basics

~20 s

BackgroundTasks lives in one worker's memory: Uvicorn waits for it on SIGTERM, but a kill, crash or shutdown timeout loses it unretried. Keep short, loss-tolerant follow-ups there; queue work that must happen or runs long.

open as a page