Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 50 ยท Async and concurrency

async def vs def endpoints

Understand the event loop, when a FastAPI endpoint should be async def or plain def, how blocking calls freeze everything and how asyncio.gather helps.

FastAPI lets you write an endpoint as either async def or plain def, and both work. The difference is not style: it decides where your code runs and what else the server can do while it runs. Pick wrongly and a single slow call can make your whole API feel frozen.

This lesson explains the event loop in plain terms, gives you a simple rule for choosing, shows with live code what a blocking call does, and uses asyncio.gather to run several waits at once.

The event loop in one minute

An async server such as uvicorn runs one event loop per process. Think of it as a single waiter in a restaurant. When a customer is thinking about the menu, the waiter does not stand there; they go serve another table and come back later. In code, the moment where a function says "I am waiting for something" is an await. At that point the loop is free to run another request.

One loop, many requests

One waiter The loop runs one piece of code at a time.
await = a pause Waiting hands control back to the loop.
Others get served Other requests run during the pause.
1 / 2

Concurrency here is cooperative: tasks take turns, and they only take turns at await. That is why one long calculation without an await blocks every other request on that loop.

The rule for choosing

FastAPI treats the two kinds of function differently:

  • async def endpoints run directly on the event loop. Use them when everything slow inside is awaited: an async database driver, httpx.AsyncClient, asyncio.sleep.
  • def endpoints are sent by FastAPI to a thread pool, so a blocking call (a classic database driver, requests, reading a big file) only blocks that worker thread, not the loop.
Your code calls... Use
Async libraries, with await async def
Blocking libraries (requests, sync ORM, time.sleep) def
Only quick in-memory work, no I/O either; async def is slightly cheaper
Heavy CPU work (image processing, big loops) neither is great: use a process pool or a task queue

Never call a blocking function inside async def. time.sleep(5) or requests.get(...) inside an async def endpoint stops the whole event loop for five seconds, and every other request waits with it.

On this site the in-browser runner has no threads, so a plain def endpoint would fail with "can't start new thread". That is why every live example here uses async def. In a real project, plain def endpoints run in the pool of worker threads (about 40 by default), and everything in this lesson applies to them as described.

Python
# Real project, read-only here: runs in the thread pool
@app.get("/report")
def report():
    rows = blocking_database_call()     # fine: only a worker thread waits
    return {"rows": len(rows)}

Seeing a blocking call freeze the loop

To make the danger visible, the next example starts a "heartbeat" task that ticks every 50 ms. While it runs, an endpoint waits 300 ms. In the first version the endpoint uses await asyncio.sleep, which hands control back; in the second it spins in a loop without ever awaiting, which is how any blocking call behaves (the browser runner would not block on a real time.sleep, so we busy-wait instead). We count how many heartbeats happened during the request.

Python await versus blocking: counting heartbeats

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

During /polite the heartbeat keeps ticking about six times, because asyncio.sleep lets it run. During /rude it cannot tick at all while the request is sleeping, so the count stays at zero. The request took the same time in both cases; the difference is what everybody else experienced.

Waiting for several things at once

The real payoff of async def is overlapping waits. Suppose an endpoint needs data from three services that each take 200 ms. Awaiting them one after another costs 600 ms. asyncio.gather starts them all and waits for the slowest, so the total is about 200 ms.

fake_service below stands in for an HTTP call or database query: it just sleeps and returns a value.

Python Sequential awaits versus asyncio.gather

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Sequential takes about 0.6 s, gather about 0.2 s, and even five whole requests together still finish in about 0.2 s because all their waits overlap.

gather has two details worth knowing. Results come back in the order you passed the awaitables, not in the order they finished. And if one of them raises, gather propagates the first exception by default; pass return_exceptions=True to receive exceptions as values instead and handle each one yourself.

Common pitfalls

  • Forgotten await. Calling fake_service("a", 1) without await gives you a coroutine object, not the result. Python warns "coroutine was never awaited" and your endpoint returns nonsense.
  • Blocking libraries in async def. requests, synchronous database drivers and time.sleep all block the loop. Switch to an async client or move the endpoint to plain def.
  • CPU-bound work. Neither async def nor def makes a heavy loop faster. Threads share Python's GIL for pure Python code, so offload to a process pool or a background worker.
  • async def "just in case". An async def endpoint without any await is fine for trivial work, but if it later grows a blocking call, it becomes a trap. When in doubt about a library, check whether it offers an async API.
  • Mixing styles in dependencies. Dependencies follow the same rule: async def runs on the loop, def runs in the pool. See Dependencies.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does FastAPI run a plain def endpoint?

    Plain def endpoints are handed to a thread pool so that blocking calls do not stop the event loop.
  2. 2. What happens if you call time.sleep(5) inside an async def endpoint?

    time.sleep never hands control back to the loop, so nothing else on that loop can run until it returns.
  3. 3. Three awaited calls of 200 ms each run with asyncio.gather. About how long does the endpoint wait?

    gather starts all three and waits for the slowest, so the waits overlap.
  4. 4. Which task is a poor fit for either async def or def endpoints?

    Heavy CPU work competes for the same Python interpreter. Use a process pool or a task queue instead.

Summary

  • The event loop runs one piece of code at a time; tasks take turns at every await.
  • Use async def when you await async libraries, and plain def for blocking libraries: FastAPI runs those in a thread pool.
  • A blocking call inside async def freezes every request on that worker.
  • asyncio.gather overlaps independent waits, returns results in argument order, and can collect exceptions with return_exceptions=True.
  • CPU-heavy work belongs in a process pool or a worker queue.
  • This site runs only async def examples because the browser has no threads.

Next, see how to do work after the response has been sent in Background tasks.