How does asyncio.run() finalize async generators that are left suspended at shutdown?

## Why async generators need special handling A synchronous generator abandoned mid-iteration is cleaned up by the garbage collector: CPython throws `GeneratorExit` in at the suspended `yield`, the `finally` runs, done. An **async** generator cannot be handled that way, because its cleanup may contain `await` — closing a stream, releasing a connection, flushing a buffer. There is no way to await anything from a `__del__`; awaiting requires a running event loop and a task to run in. CPython's answer is a pair of hooks. `sys.set_asyncgen_hooks(firstiter=..., finalizer=...)` installs, per thread, two callbacks: `firstiter` fires the very first time an async generator is iterated, and `finalizer` fires when a still-suspended generator is about to be collected. The asyncio event loop installs its own pair when it starts running. Its `firstiter` records the generator in a weak set owned by the loop; its `finalizer` schedules `agen.aclose()` as a task, so the cleanup gets a live loop to run on. The hooks are per-thread, and registration happens on **first iteration**, not at creation. An async generator object created but never iterated is not registered anywhere and has nothing to clean up; one first iterated inside a loop belongs to that loop for finalization purposes. ## What `shutdown_asyncgens()` does `loop.shutdown_asyncgens()` is a coroutine. It takes everything still in that weak set and awaits `aclose()` on each one, gathering results so a failure in one does not abort the rest; a generator whose cleanup raises is reported through the loop's exception handler. `aclose()` throws `GeneratorExit` in at the suspended `yield`, which unwinds the generator body and runs any `finally`. In `asyncio.Runner.close()` this is step two of four: cancel and await the tasks, **finalize the async generators**, join the default executor, close the loop. The ordering is deliberate — generators are finalized after your tasks are gone but while the loop is still alive and able to run awaits. ## The failure it prevents, and when it does not Consider a webhook receiver that decodes inbound events and hands them out in batches: ```python async def batches(stream): buf = [] try: async for event in stream: buf.append(event) if len(buf) == 500: yield buf buf = [] finally: if buf: await archive(buf) # flush the partial batch ``` A consumer that `break`s out on the first malformed payload leaves this generator suspended at the `yield`. Under `asyncio.run()` the flush still happens, at shutdown. Under a hand-rolled `loop.run_until_complete(main()); loop.close()` it never happens: no cancellation is involved, no exception is raised, nothing is logged. The archive is simply short by up to 499 events — a silent truncation that nobody notices until someone reconciles counts weeks later. That is the whole argument for using `asyncio.run()` or `asyncio.Runner` rather than driving a loop yourself. ## Why shutdown finalization is still a weak plan Even when it runs, finalization at shutdown happens *after every task has been cancelled*. Anything the cleanup depends on may already be gone: the connection was owned by a task that just died, the session's `__aexit__` already ran, the destination is closed. The cleanup then raises inside `shutdown_asyncgens()`, gets logged through the exception handler, and you are back to losing the flush — with one more log line. The deterministic fix is to close where you use it: ```python from contextlib import aclosing async with aclosing(batches(stream)) as stream_of_batches: async for batch in stream_of_batches: if bad(batch): break # aclose() runs here, not at shutdown ``` `contextlib.aclosing()` (3.10+) awaits `aclose()` on the way out of the block, so the `finally` runs at a moment when everything it needs is still alive. Treat `shutdown_asyncgens()` as the backstop that catches what you forgot. ## The neighbouring step The step immediately after generator finalization is `loop.shutdown_default_executor()`, which joins the thread pool behind `asyncio.to_thread()`. On 3.14 `asyncio.run()` gives that join a five-minute budget; if the worker threads have not finished by then, a `RuntimeWarning` is emitted and shutdown proceeds without waiting. Both steps share a theme: the loop is finalizing resources that outlived your tasks, and both are skipped entirely if you close a loop by hand. ## What to say in an interview Name the mechanism (`sys.set_asyncgen_hooks()` and the loop's weak set), name the step (`loop.shutdown_asyncgens()`), and say what breaks without it — a suspended generator's `finally` never running, which loses exactly the buffered data that a `finally` exists to flush. Then say you would not rely on it, and reach for `contextlib.aclosing()`. ## A quick way to see it Run a program that breaks out of an `async for` over a generator whose `finally` prints. The print appears *after* the line that follows the loop in `main()` — proof that the cleanup was deferred to the runner's finalization step rather than performed at the `break`. Wrap the same generator in `contextlib.aclosing()` and the two lines swap order. That five-line experiment is worth more than any amount of reasoning about when cleanup "should" happen.