Breaking early out of `async for` over an async generator defers `finally:` cleanup silently to GC / loop teardown — close it explicitly with `await gen.aclose()` or `contextlib.aclosing`.
Verbatim Symptoms (Primary Search Key)
- resource still held after breaking out of an async for loop
- file handle or lock not released after early break from async generator
- async generator finally block ran during GC instead of at the break point
- cleanup executed after the caller continued, not when the loop exited
Problem Statement
Breaking out of an async-for loop early does not finalize the async generator at the break point. Unlike a synchronous generator (whose close is driven at GC), an async generator's finalization must be awaited, and Python cannot await during ordinary garbage collection — so the `finally:` block is deferred until the event loop's async-generator shutdown hook or GC runs it later. Crucially this is SILENT: Python raises no error and the process exits 0. The caller continues believing cleanup is done while the file handle, lock, or connection is still held. Note: this is a DIFFERENT bug from 'RuntimeError: async generator ignored GeneratorExit', which occurs when a generator swallows GeneratorExit during aclose(); that error is not produced by this deferral.
Correct Procedure
- Bind the generator to a variable and wrap the loop in `try/finally` with `await gen.aclose()` so cleanup runs deterministically at the break.
- Or use `async with contextlib.aclosing(my_gen()) as gen:` (Python 3.10+), which calls `aclose()` automatically on block exit.
- For long-lived loops, do not rely on GC or on `loop.shutdown_asyncgens()` — those run cleanup far later than the break, defeating deterministic resource release.
Anti-Patterns
- Assuming `break` in `async for` runs the generator's `finally:` immediately — it does not; cleanup is deferred to GC / async-gen shutdown.
- Relying on GC to finalize async generators inside a long-running event loop — finalization may be arbitrarily late.
- Confusing this silent deferral with 'async generator ignored GeneratorExit' — that is a separate bug caused by swallowing GeneratorExit.
Documented Dead Ends
- Relying on plain `break` in `async for item in gen():` to release the resource: The generator stays suspended at its yield; its finally block does not run at break time, so locks/handles remain held while the caller proceeds. No exception signals the leak. (~25 mins wasted)