asyncio honestly: suspendable frames, await as the only switch point, and the blocking call that freezes everyone

Coroutines are suspendable frames, not threads

Before you can diagnose the Hook’s 26-second p99 spike — or write async code that doesn’t accidentally reproduce it — you need the mechanical picture of what async def actually creates and what await actually does.

async def does not define background work; it defines a function whose stack frame can be paused and resumed. Calling it executes nothing — it returns a coroutine object, a frozen frame holding the function’s locals and instruction pointer (forget to await it and nothing runs; you get RuntimeWarning: coroutine 'fetch' was never awaited at GC time, the classic silently-skipped step). await expr does two things: runs expr until it either completes or suspends, and — on suspension — propagates the suspension up the entire await chain to the event loop. Suspension bottoms out in a Future: an awaitable that is not done yet. The chain matters mechanically: when handler awaits fetch which awaits sock_recv, all three frames freeze as one linked unit, and when the socket delivers data, the loop resumes the bottom frame and the values flow back up. There is no preemption anywhere in this story — a coroutine runs until it chooses to await something that suspends. That single property is asyncio’s superpower (no locks needed between awaits: code between two await points is atomic with respect to other coroutines) and its loaded gun.

import asyncio

async def fetch(url: str) -> bytes:
    reader, writer = await asyncio.open_connection("example.com", 80)
    writer.write(f"GET {url} HTTP/1.0\r\nHost: example.com\r\n\r\n".encode())
    await writer.drain()
    body = await reader.read(-1)     # frame suspends here until data arrives
    writer.close()
    return body

coro = fetch("/")        # nothing has run yet — just a frozen frame
# asyncio.run(coro)      # the loop drives it to completion

The loop: a ready queue, a selector, and no mercy

The event loop is a small, honest piece of machinery: a queue of ready callbacks and an OS selector (epoll on Linux, kqueue on BSD/macOS). Each iteration it (1) runs every ready callback — and resuming a coroutine until its next await is just one callback, (2) asks the selector which sockets became ready, with a timeout equal to the nearest scheduled timer, (3) queues the wakeups. That is the whole engine, and it implies the rule that the Hook’s outage violated: step 1 must be fast. The loop cannot poll sockets or fire timers while a callback runs, so a coroutine that computes for 2 seconds — or calls requests.get, time.sleep, a synchronous DB driver, bcrypt.hashpw, or reads a large file with plain open().read() — stops the world: every timer late, every connection unaccepted, every other request’s p99 inflated by exactly that duration. The detection tools are built in: PYTHONASYNCIODEBUG=1 (or loop.set_debug(True)) logs any callback exceeding 100 ms via loop.slow_callback_duration. The cure for blocking calls is delegation, not heroics: await loop.run_in_executor(None, blocking_fn, arg) runs the function in the default ThreadPoolExecutor and suspends the coroutine until it finishes; asyncio.to_thread(blocking_fn, arg) (3.9+) is the same with less ceremony. One honest footnote from the GIL lesson: a thread executor only helps when the blocked call releases the GIL (I/O, most C calls) — for pure-Python CPU work, pass a ProcessPoolExecutor as the first argument instead.

import asyncio, hashlib
from concurrent.futures import ProcessPoolExecutor

async def handler(password: bytes, big_doc: bytes):
    loop = asyncio.get_running_loop()
    # blocking I/O or GIL-releasing C call → thread is enough
    rate = await asyncio.to_thread(fetch_rate_sync, "EUR")
    # pure-CPU work → process pool, or the GIL nullifies the thread
    digest = await loop.run_in_executor(cpu_pool, hashlib.pbkdf2_hmac,
                                        "sha256", password, b"salt", 600_000)
    return rate, digest

cpu_pool = ProcessPoolExecutor(max_workers=4)

Tasks vs coroutines: when concurrency actually starts

await some_coro() is sequential — sugar for a function call that may suspend. Concurrency begins only when you hand a coroutine to the loop as an independent unit: asyncio.create_task(coro) wraps the frame in a Task, schedules it to start on the next loop iteration, and returns immediately. A Task is a Future subclass that drives its coroutine and remembers the result or exception. This is the difference that bites in code review: three sequential awaits of three HTTP calls take the sum of their latencies; three tasks awaited after creation take the max. asyncio.gather(*coros) packages the pattern — it wraps each argument in a Task, runs them concurrently, and returns results in argument order; with default settings the first exception propagates immediately while the surviving tasks keep running unsupervised, and return_exceptions=True instead delivers exceptions as values so you can triage per-item. Two production rules follow. First, a bare create_task whose reference you drop can be garbage-collected mid-flight — the loop holds only a weak reference; keep a reference or use the structured tools from the next lesson. Second, gather’s keep-running-on-error behavior is a resource leak in disguise for fan-outs with side effects — also the next lesson’s subject.