Mental model
Unlike WSGI (which handles requests synchronously using process/thread pools), ASGI (Asynchronous Server Gateway Interface) handles requests as asynchronous coroutines over event loops (uvloop).
HTTP Client TCP Socket
Master Gunicorn Process
Distribute to Uvicorn Worker Process
uvloop Event Loop Socket Polling
FastAPI ASGI Application Dispatch
Theory
An ASGI application is an async callable taking three arguments: scope (connection metadata dictionary), receive (coroutine to fetch incoming events), and send (coroutine to push outgoing response chunks).
python(16 lines)
1# Raw ASGI application specification
2async def app(scope, receive, send):
3 assert scope['type'] == 'http'
4 await send({
5 'type': 'http.response.start',
6 'status': 200,
7 'headers': [[b'content-type', b'text/plain']],
8 })
9 await send({
10 'type': 'http.response.body',
11 'body': b'Hello from raw ASGI!',
12 })
13
14# Production Uvicorn CLI worker scaling
15# uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 --loop uvloop
Alternatives and trade-offs
- WSGI (Gunicorn / uWSGI): Synchronous blocking per thread; fails under heavy WebSocket or SSE streaming concurrency.
- ASGI (Uvicorn / Hypercorn): Non-blocking event loop concurrency; requires non-blocking async drivers for all I/O dependencies.
Failure modes and misconceptions
- Blocking I/O in Async Routes: Executing blocking synchronous code (e.g.
time.sleep(5)orrequests.get()) insideasync defroutes freezes the entire Uvicorn worker process event loop for all concurrent users. Usedef(which FastAPI offloads to a threadpool) or async libraries (httpx,asyncio.sleep). - Over-scaling Workers: Spawning 64 Uvicorn worker processes on an 8-core CPU wastes RAM and increases CPU context-switching overhead. General rule:
(2 * CPU_Cores) + 1.
Reflect before revealing the guide
Decision scenario
Run Gunicorn as the master process supervisor managing Uvicorn worker processes (gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker) for production containerized FastAPI deployments.
Learning outcomes
- Explain the ASGI
scope,receive, andsendprotocol contract. - Distinguish WSGI synchronous thread execution from ASGI asynchronous event loops.
- Calculate optimal Uvicorn worker process scaling for web workloads.
Trade-offs
ASGI servers enable sub-millisecond async I/O multiplexing, but require strict prevention of blocking CPU/I/O calls on the main event loop thread.