Skip to content

17 · Two Event Loops, asyncio, and What await Really Does

In the previous lesson, Alice and Max shared a live WebSocket review room.

The critical server code was:

while True:
raw_message = await websocket.receive_json()
command = AddNoteCommand.model_validate(
raw_message
)
event = await asyncio.to_thread(
create_review_note,
user_id=context.user_id,
document_id=context.document_id,
body=command.body,
)
await review_room_manager.broadcast(
context.document_id,
event.model_dump(mode="json"),
)

Today we will look underneath those three await expressions.

There are actually two independent event loops involved:

Location Event loop coordinates
Browser Clicks, timers, Promise continuations, WebSocket messages and DOM work
FastAPI server HTTP requests, WebSocket connections, coroutines and network I/O

Between them sits the network.

Our synchronous SQLAlchemy service does not naturally belong to either event loop, so FastAPI runs that work in a thread-pool worker:

Browser event loop
↓ WebSocket message
FastAPI asyncio event loop
↓ asyncio.to_thread()
Worker thread
↓
SQLAlchemy Session
↓
SQLite

The central idea is simple:

An event loop works well when tasks regularly stop and yield control while waiting. It works badly when one task occupies the thread doing blocking or CPU-heavy work.


Consider the browser code that sends a review note:

form.addEventListener("submit", sendNote);
function sendNote(event) {
event.preventDefault();
const body = input.value.trim();
socket.send(JSON.stringify({
type: "add_note",
body: body,
}));
input.value = "";
roomMessage.textContent = "Sending note…";
}

When Alice submits the form, the browser places the form event’s handler into its queue.

The JavaScript engine then runs:

sendNote(event)

from beginning to end.

This is called run-to-completion. While that particular JavaScript job is running, another click handler or WebSocket message handler does not interrupt it halfway through. Once it returns and the JavaScript call stack is empty, the browser may process another eligible job. MDN

For this handler, the sequence is:

  1. Prevent the ordinary form navigation.
  2. Read the input.
  3. create a JavaScript object.
  4. Convert that object into JSON text.
  5. Queue the WebSocket message for transmission.
  6. Empty the input.
  7. Change the DOM message.
  8. Return.

The browser may then repaint the page so Alice sees:

Sending note…

The browser does not wait inside sendNote() for FastAPI to commit the note.


socket.send() does not contact SQLite directly

Section titled “socket.send() does not contact SQLite directly”

This line:

socket.send(JSON.stringify({
type: "add_note",
body: body,
}));

asks the browser’s WebSocket implementation to transmit data.

JavaScript does not personally:

  • Open a TCP packet
  • Authenticate the user
  • Call Python
  • Execute SQL
  • Wait for a commit

Those activities happen in other browser, operating-system, network and server components.

The JavaScript handler finishes quickly and gives control back to the browser.

Later, when FastAPI broadcasts:

{
"type": "note_created",
"note_id": 84,
"author_name": "Alice Morgan",
"body": "Check the introduction for clarity."
}

the browser places a new WebSocket message event into its queue.

The registered handler then runs:

socket.addEventListener("message", (event) => {
const message = JSON.parse(event.data);
handleMessage(message);
});

The send handler and message handler are two separate browser jobs.


Earlier lessons used:

const response = await fetch(url);

The browser begins the network operation and obtains a Promise.

Then await pauses the surrounding async function:

async function refreshStatus() {
const response = await fetch(url);
// This part runs later.
const data = await response.json();
}

It does not pause the entire browser.

While refreshStatus() is suspended, the browser can:

  • Handle clicks
  • Render loading text
  • Run timers
  • Receive WebSocket messages
  • Scroll the page
  • Process other completed network operations

When the Promise settles, the continuation after await is scheduled to run as a later microtask. MDN

Conceptually:

Run refreshStatus()
↓
Begin fetch()
↓
Pause this function at await
↓
Browser handles other work
↓
Network response arrives
↓
Schedule function continuation
↓
Resume after await

The paused function retains its local state. Variables such as url still exist when it resumes.


Suppose we write:

async function calculateReport() {
let total = 0;
for (let index = 0; index < 5_000_000_000; index++) {
total += index;
}
return total;
}

Despite the async keyword, the loop is ordinary synchronous CPU work.

Until it finishes, the browser’s main JavaScript thread cannot comfortably process:

  • Clicks
  • DOM rendering
  • WebSocket message handlers
  • Timers

An async function does not automatically run on another thread.

It can cooperate with the event loop when it reaches a genuine asynchronous boundary such as:

await fetch(...)

The same principle applies in Python.


A Uvicorn worker running our FastAPI application has an event loop coordinating many server-side tasks.

When Alice connects to the review room, FastAPI starts the WebSocket endpoint as a task:

async def document_review_socket(
websocket: WebSocket,
context: ReviewSocketContextDep,
):

When Max connects, FastAPI starts another task using the same endpoint function but different local state:

Alice’s task
→ Alice’s WebSocket
→ Alice’s context
Max’s task
→ Max’s WebSocket
→ Max’s context

These tasks may share one event-loop thread.

They are concurrent because their lifetimes overlap:

Alice connected ────────────────────────────
Max connected ───────────────────────

They are not necessarily executing Python instructions at precisely the same instant.

The event loop generally runs one ready piece of Python code, then another. Tasks cooperate by pausing at suitable await points.


In ordinary Python:

def add(left, right):
return left + right

Calling:

result = add(2, 3)

immediately executes the function and returns:

5

An asynchronous function behaves differently:

async def receive_note():
...

Calling:

result = receive_note()

creates a coroutine object. The function body does not run merely because that object was created.

Python’s documentation explicitly notes that merely calling a coroutine does not schedule it to execute. It must be awaited, turned into a task, or otherwise run by an asyncio mechanism. Python 3.14.8 documentation

FastAPI handles this for our endpoint by awaiting it within the server’s connection-handling task. The endpoint does not need to create its own task just to begin executing.


Inside each connection task, execution reaches:

raw_message = await websocket.receive_json()

If no message is available, the task cannot make useful progress.

Rather than keeping the server thread occupied, it yields control to the event loop:

Alice’s task
→ Waiting for a message
Max’s task
→ Waiting for a message
Event loop
→ Free to handle HTTP requests, timers and other sockets

The operating system and ASGI server continue monitoring network connections.

When Alice’s message arrives, Alice’s task becomes ready.

The event loop resumes it after:

await websocket.receive_json()

with a Python value:

{
"type": "add_note",
"body": "Check the introduction for clarity.",
}

The awaitable did not run continuously while waiting. It arranged for the task to resume once data became available.


The next line is:

command = AddNoteCommand.model_validate(
raw_message
)

There is no await.

Pydantic examines the Python dictionary, validates a few fields and constructs an AddNoteCommand.

For this small message, that work should finish extremely quickly.

Not every statement inside an asynchronous endpoint must be asynchronous.

These operations are normally fine directly on the event-loop thread:

message_type = raw_message.get("type")
normalized_body = command.body.casefold()
outgoing = event.model_dump(mode="json")

The concern is not whether a line has await.

The concern is:

How long will this code keep the event-loop thread occupied before another task gets a chance to run?

A few string operations are negligible. A two-second blocking database call is not.


Imagine that we call our synchronous service directly:

event = create_review_note(
user_id=context.user_id,
document_id=context.document_id,
body=command.body,
)

Inside that service:

with SessionLocal.begin() as db:
user = db.get(User, user_id)
document = db.scalar(statement)
db.add(note)
db.flush()

These SQLAlchemy and SQLite operations are synchronous.

While Python waits for the database operation, the event-loop thread remains occupied inside this function.

The result could be:

Alice’s task
→ Calls synchronous database service
→ Event loop becomes blocked
Max’s WebSocket message
→ Has arrived
→ Cannot yet run its Python handler
Status request
→ Has arrived
→ Cannot yet run its async endpoint
SSE stream
→ Ready to send an event
→ Must wait

The database operation may usually take only milliseconds. But under lock contention, disk pressure or an unexpectedly slow query, the delay can become visible across many connections.


The obvious-looking fix that does not work

Section titled “The obvious-looking fix that does not work”

Changing the service wrapper to async def is insufficient:

async def create_review_note_async(
*,
user_id: int,
document_id: int,
body: str,
):
return create_review_note(
user_id=user_id,
document_id=document_id,
body=body,
)

Then writing:

event = await create_review_note_async(...)

still runs the synchronous service on the event-loop thread.

The wrapper contains no operation that actually moves the blocking work elsewhere.

It is asynchronous in syntax but synchronous in behavior:

async wrapper
→ calls blocking function directly
→ event loop still blocked

This is sometimes called “fake async.”

The async keyword does not transform a synchronous library into an asynchronous one.


Our WebSocket endpoint instead uses:

event = await asyncio.to_thread(
create_review_note,
user_id=context.user_id,
document_id=context.document_id,
body=command.body,
)

This has two important parts.

First:

asyncio.to_thread(
create_review_note,
...
)

arranges for the normal function to run in a worker thread from a thread pool.

Second:

await

suspends this WebSocket task until the worker returns its result.

The sequence becomes:

FastAPI event-loop thread
→ Submit create_review_note() to thread pool
→ Suspend Alice’s task
→ Continue handling other ready tasks
Worker thread
→ Open SQLAlchemy Session
→ Query SQLite
→ INSERT review note
→ Commit
→ Close Session
→ Return NoteCreatedEvent
FastAPI event-loop thread
→ Resume Alice’s task with returned event

Python documents asyncio.to_thread() as a way to run blocking I/O without blocking the event loop. It is mainly intended for I/O-bound work rather than general CPU-heavy computation. Python 3.14.8 documentation


Why the SQLAlchemy session is created inside the thread

Section titled “Why the SQLAlchemy session is created inside the thread”

The service contains:

with SessionLocal.begin() as db:

The session is created, used, committed and closed inside the same synchronous service call.

That is preferable to:

db = SessionLocal()
event = await asyncio.to_thread(
use_existing_session,
db,
)

A SQLAlchemy Session represents mutable database-unit-of-work state. It should not be casually shared across concurrent tasks or moved among threads.

Our boundary is clean:

Event-loop task passes scalar values
→ user_id
→ document_id
→ body
Worker thread owns database work
→ creates Session
→ uses Session
→ closes Session
Worker returns detached result
→ NoteCreatedEvent

The worker does not return an active transaction or a session-dependent ORM object.


Suppose Alice and Max submit notes almost simultaneously.

At first:

Alice’s WebSocket task
→ waiting at receive_json()
Max’s WebSocket task
→ waiting at receive_json()

Alice’s message arrives:

Alice’s task resumes
→ validates message
→ submits database service to worker thread
→ pauses at await asyncio.to_thread()

The event loop is now free.

Max’s message arrives:

Max’s task resumes
→ validates message
→ submits its service call
→ pauses

Two worker threads may now be attempting database work.

SQLite permits many readers but coordinates writes more restrictively, effectively allowing one writer at a time. Keeping transactions short matters:

Alice’s transaction
→ INSERT
→ COMMIT
→ release write access
Max’s transaction
→ INSERT
→ COMMIT

Once Alice’s worker finishes, her task resumes:

await review_room_manager.broadcast(...)

Then Max’s task resumes when his database operation completes.

The database records the committed notes, but worker-thread completion and network delivery can interleave. Our simple broadcaster does not guarantee that every browser displays notes in database commit order or click order.

If exact application ordering matters, the database should record an authoritative ID or timestamp. Arrival timing in two browsers is not a reliable business ordering rule.


Our broadcast method contains:

await websocket.send_json(message)

Sending may need to wait until the ASGI server and network transport can accept more data.

Therefore, this too is an asynchronous boundary.

For a small room, sending sequentially is understandable:

for websocket in connections:
await websocket.send_json(message)

But it has a production tradeoff.

A slow or overloaded client may delay later clients in that loop.

Larger systems commonly give each connection a bounded outgoing queue:

Broadcast publisher
→ places event into Alice’s queue
→ places event into Max’s queue
→ returns
Alice’s sender task
→ drains Alice’s queue
Max’s sender task
→ drains Max’s queue

That isolates slow clients and creates an explicit place to enforce backpressure or disconnect clients whose queues grow too large.

For our small document review room, the sequential implementation remains reasonable and easier to understand.


Python does not normally interrupt a coroutine at an arbitrary line.

A task continues until it:

  • Returns
  • Raises an exception
  • Reaches an awaitable that suspends
  • Explicitly yields through another asyncio mechanism

Consider:

async def bad_handler():
total = 0
for number in range(5_000_000_000):
total += number
await websocket.send_json({
"total": total,
})

The first await comes after the enormous loop.

Until that loop finishes, the task never gives the event loop an opportunity to run other tasks.

The fact that the function is declared with:

async def

does not make the loop concurrent or parallel.

This mirrors the browser:

async function badHandler() {
let total = 0;
for (let number = 0; number < 5_000_000_000; number++) {
total += number;
}
await sendResult(total);
}

Both event loops depend on code yielding control at sensible points.


This difference makes the model especially visible.

Inside an asynchronous endpoint, this is dangerous:

import time
async def wait_badly():
time.sleep(5)

time.sleep(5) blocks the current thread for five seconds.

If that thread is running the event loop, other tasks assigned to that loop cannot progress normally.

This version cooperates:

import asyncio
async def wait_cooperatively():
await asyncio.sleep(5)

asyncio.sleep(5) tells the event loop:

This task cannot continue for five seconds. Run other tasks and make this one ready later.

The task retains its state, but the event-loop thread is available.

The browser has a similar distinction:

window.setTimeout(callback, 5000);

schedules later work and returns.

A synchronous five-second JavaScript loop occupies the browser thread and prevents responsive rendering.


FastAPI’s special handling of normal def routes

Section titled “FastAPI’s special handling of normal def routes”

Earlier, our ordinary SQLAlchemy-backed HTTP routes used:

@router.post("/documents")
def create_document_route(
payload: DocumentCreate,
db: DbSession,
):
...

FastAPI sees that the path-operation function is a normal def.

It runs the route in an external thread pool and awaits the result, preventing the synchronous route from directly blocking the event loop. FastAPI applies similar handling to normal def dependencies. FastAPI

Therefore, this is coherent:

@router.post("/documents")
def create_document_route(...):
return create_document(...)

The complete route already runs in a worker thread.

Our WebSocket endpoint must be:

async def

because it directly awaits repeated WebSocket receives and sends.

Inside that asynchronous function, FastAPI does not automatically move every normal helper function to a thread pool.

FastAPI’s documentation makes this distinction explicit:

Normal def route or dependency
→ FastAPI calls it in a thread pool
Normal helper called by your own async code
→ Called directly unless you explicitly offload it

That is why the WebSocket endpoint contains:

await asyncio.to_thread(
create_review_note,
...
)

A practical application can mix these patterns deliberately:

Work Reasonable pattern
Synchronous SQLAlchemy HTTP route Normal def route
WebSocket or SSE connection async def endpoint
Synchronous DB call inside async endpoint await asyncio.to_thread(...)
Async HTTP client await client.get(...)
Async SQLAlchemy stack async def plus AsyncSession
Small validation or data transformation Run directly
Heavy CPU processing Process pool or durable worker
Important long-running job Durable job queue

The goal is not to make every function asynchronous.

The goal is to keep blocking work away from the event-loop thread.


We could replace the synchronous database stack with:

  • SQLAlchemy AsyncSession
  • An async engine
  • An async-compatible SQLite driver such as aiosqlite

The service could then resemble:

async def create_review_note(
*,
db: AsyncSession,
user_id: int,
document_id: int,
body: str,
) -> NoteCreatedEvent:
user = await db.get(User, user_id)
result = await db.execute(statement)
document = result.scalar_one_or_none()
db.add(note)
await db.commit()
await db.refresh(note)
return event

Now the database driver exposes awaitable operations.

That can be appropriate when the application is strongly async and database concurrency justifies it.

But asynchronous SQLAlchemy introduces additional concepts, drivers and failure modes. For a small SQLite modular monolith, this remains entirely reasonable:

Synchronous SQLAlchemy
+
short-lived sessions
+
normal def HTTP routes
+
explicit to_thread() inside long-lived async endpoints

It is boring, visible and understandable.


Our SQLAlchemy operation is primarily I/O-bound:

Python sends database operation
→ waits for SQLite and disk work
→ receives result

A worker thread is a reasonable place for it.

Now imagine that the review service performs a large CPU-heavy operation:

def calculate_similarity_for_500_000_documents():
...

Moving that to asyncio.to_thread() does not automatically provide efficient CPU parallelism.

The normal GIL-enabled CPython build used for these examples has a Global Interpreter Lock that limits parallel execution of ordinary Python bytecode across threads. Optional free-threaded builds have different tradeoffs; we are not assuming one here.

For CPU-heavy work, better choices include:

  • A separate worker process
  • A process pool
  • A durable job system
  • An external computation service
  • Native libraries that release the GIL

A thread protects the event loop from blocking I/O. It is not a universal performance button.


asyncio.create_task() is not a durable job queue

Section titled “asyncio.create_task() is not a durable job queue”

Suppose we write:

asyncio.create_task(
run_document_review(document_id)
)

This schedules another coroutine on the current process’s event loop.

It can be useful for supervised, process-local concurrent work.

But it does not mean:

The job is durable
The job survives deployment
The job retries after a crash
Another server can find it
Its result is automatically stored

If the FastAPI process restarts, that in-memory task disappears.

If the coroutine performs blocking work without offloading it, the new task can still block the same event loop.

This connects back to our background-processing lesson:

asyncio Task
→ concurrent process-local execution
FastAPI BackgroundTask
→ in-process work after a response
Durable job queue
→ persisted work handled independently of one web process

These mechanisms solve different problems.


Suppose Alice closes the page while this line is waiting:

event = await asyncio.to_thread(
create_review_note,
...
)

The WebSocket task may be canceled or disconnected.

That does not guarantee that the synchronous worker function stops halfway through.

The thread may already be:

Executing INSERT
→ Committing transaction

The event-loop task can stop waiting, but Python cannot safely reach into arbitrary synchronous code and undo completed database work.

This matches the browser cancellation principle from earlier lessons:

Stop waiting for an operation
≠
Prove the operation never happened

The database remains the authority.

After reconnecting, the browser should reload or synchronize persisted notes rather than assuming its last in-memory state is complete.


Sequential waiting versus concurrent waiting

Section titled “Sequential waiting versus concurrent waiting”

await also controls ordering.

This code performs two operations sequentially:

user = await load_user()
document = await load_document()

The second operation begins only after the first finishes.

If the two operations are genuinely independent and safely concurrent, Python can start both:

user, document = await asyncio.gather(
load_user(),
load_document(),
)

But concurrency is not automatically faster.

For our SQLite operation, combining related queries within one short service transaction may be clearer and safer than launching several competing database operations.

Use concurrency when independent waiting dominates. Do not split a coherent transaction merely to add more await expressions.


It is useful to draw a firm boundary between browser JavaScript and server Python.

The browser contains:

socket
message
noteList
roomMessage

The server contains:

websocket
context
command
event

Those variables do not exist in one shared runtime.

The bridge is serialized data:

JavaScript object
→ JSON.stringify()
→ WebSocket text
→ network
→ JSON parsing
→ Python dictionary
→ Pydantic object

The response travels in reverse:

Pydantic event
→ JSON serialization
→ WebSocket text
→ network
→ event.data
→ JSON.parse()
→ JavaScript object
→ DOM update

The browser event loop knows nothing about Python Tasks.

The Python event loop knows nothing about DOM events.

They cooperate only through network messages.


Consider Alice and Max submitting notes close together.

  1. The browser receives a form-submit event.
  2. JavaScript runs sendNote() to completion.
  3. JSON.stringify() creates text.
  4. socket.send() queues the text for transmission.
  5. JavaScript changes the DOM to “Sending note…”.
  6. The handler returns.
  7. Alice’s browser can render and handle other events.
  1. Alice’s network data becomes available.
  2. Her WebSocket task resumes from receive_json().
  3. Pydantic validates her message.
  4. asyncio.to_thread() submits the service operation.
  5. Alice’s task suspends.
  1. Max’s message reaches the server.
  2. Max’s WebSocket task resumes.
  3. Pydantic validates his message.
  4. His service operation is submitted to the thread pool.
  5. Max’s task suspends.
  6. The event loop remains available for other connections.
  1. Alice’s service creates its own SQLAlchemy session.
  2. Max’s service creates a different session.
  3. SQLite coordinates the write transactions.
  4. Alice’s transaction commits.
  5. Her session closes.
  6. Her worker returns a NoteCreatedEvent.
  1. Alice’s WebSocket task becomes ready.
  2. It resumes after await asyncio.to_thread().
  3. It broadcasts the committed event.
  4. Each send_json() may briefly yield while sending.
  5. Alice’s task returns to receive_json() and waits again.
  6. Max’s task follows when his transaction completes.
  1. Each browser receives a WebSocket message event.
  2. Its JavaScript event loop runs the registered handler.
  3. JSON.parse() creates a JavaScript object.
  4. Safe DOM operations append the note.
  5. The handler returns.
  6. The browser paints the updated review room.

Several operations overlapped in time, but each layer still had a clear responsibility.


Browser JavaScript and Python asyncio share the same broad cooperative model:

Start an operation
→ pause one function while waiting
→ let other work proceed
→ resume when the result is ready

But await only helps when the awaited operation can genuinely yield.

It does not transform:

  • CPU-heavy loops
  • time.sleep()
  • Synchronous SQLAlchemy calls
  • Ordinary blocking file operations
  • Synchronous network libraries

into non-blocking work.

Our architecture therefore uses:

Browser event loop
→ events, Promises and DOM updates
FastAPI asyncio event loop
→ HTTP and long-lived connection coordination
Thread pool
→ synchronous blocking I/O
Short SQLAlchemy Session
→ one database unit of work
SQLite
→ durable authoritative state
Durable job worker
→ important processing that must survive web-process failure

The event loop is not a machine that performs all the work simultaneously. It is a coordinator that remains effective because tasks avoid occupying its thread while they are merely waiting.

The next installment will integrate the complete document-review workflow and make the final architectural choices explicit: which actions use ordinary HTTP, which use polling or SSE, when a background worker is required, and when a WebSocket adds complexity without adding value.