Skip to content

gh-161170: Lazily materialize coroutine objects for awaited calls - #162238

Open
asvetlov wants to merge 3 commits into
python:mainfrom
asvetlov:claude/lazy-generator-materialization-d63ba7
Open

asvetlov wants to merge 3 commits into
python:mainfrom
asvetlov:claude/lazy-generator-materialization-d63ba7

Conversation

@asvetlov

@asvetlov asvetlov commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

await f() on an async def no longer allocates a coroutine object unless the body actually suspends.

This is an alternative to gh-161171. Instead of having RETURN_GENERATOR peek at the caller's bytecode, the compiler marks awaited calls explicitly, and each instruction does a small, local part of the work:

  • CALL / CALL_KW / CALL_FUNCTION_EX get an awaited flag in the low bit of the oparg (nargs << 1 | awaited for CALL and CALL_KW). The Python-function paths (CALL_PY_EXACT_ARGS, CALL_PY_GENERAL, the bound-method and KW variants, CALL_EX_PY and the generic inline paths) mark the new frame of a coroutine function as lazy (_MAYBE_LAZY_CORO). Non-Python callables and non-coroutines are untouched.
  • RETURN_GENERATOR keeps running a lazy body in the pushed frame, with its own exception-state item on the data stack.
  • For await <call>, the compiler pushes an extra NULL slot below the callable. A lazy body reports how it ended there: a tagged int if it returned, or the coroutine object if it suspended. In the second case, YIELD_VALUE creates the coroutine and moves the frame into it.
  • GET_AWAITABLE now always pushes the NULL/None that start the SEND loop. With the low bit of its oparg set, it also pops the extra slot and turns it into the SEND input. It never jumps.
  • SEND (every form, since an await site may have been specialized for another awaitable before) treats a NULL receiver as "done, v is the result" and jumps to END_SEND. It treats None in place of the NULL as "already yielded v", resets the slot and falls through to YIELD_VALUE.

An exception that leaves a lazy body is raised from the caller's SEND, so tracebacks are the same as before.

The coroutine is still created eagerly for calls from C, instrumented calls, PEP 523 hooks, coroutine origin tracking, JIT trace recording and in tier 2 (_MAYBE_LAZY_CORO becomes a _NOP there). A tier-2 YIELD_VALUE exits to tier 1 for a lazy frame.

Visible change: frame.f_generator and PyFrame_GetGenerator() are None/NULL for such a coroutine until it first suspends; asyncio.graph now classifies frames by co_flags.

The PR has three commits for review: the CALL oparg encoding, the GET_AWAITABLE/codegen change (no behavior change on their own), and the lazy execution.

Microbenchmark

Release build without PGO, x86-64, best of 6 runs:

main PR
await noop() 48.3 ns 27.2 ns (−44%)
await f(1, 2, c=3) 67.0 ns 42.8 ns (−36%)
await obj.meth(1) 52.6 ns 28.6 ns (−46%)
body that suspends once 190.0 ns 200.2 ns (+5%)

The suspending case copies the frame into the coroutine at the first yield instead of at creation.

🤖 Generated with Claude Code

asvetlov and others added 3 commits November 18, 2026 21:54
… and CALL_FUNCTION_EX

The oparg of CALL and CALL_KW is now the number of arguments shifted
left by one, and the low bit of all three calls is reserved for marking
a call whose result is awaited right away. The compiler doesn't set it
yet, so there is no behavior change.

_INIT_CALL_PY_EXACT_ARGS is replicated for the opargs 0..9 so that
calls with up to 4 arguments, awaited or not, still get a constant
argument count in tier 2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ITABLE

GET_AWAITABLE now also pushes the NULL and None that start the
following SEND loop, so the compiler no longer emits them.

`await <call>` sets the awaited flag of the call and pushes an extra
NULL below its callable. GET_AWAITABLE with the low bit of its oparg
set pops that slot as well. Nothing writes to it yet, so there is no
behavior change; it will report how a coroutine body that ran without
a coroutine object ended.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`await f()` on an `async def` no longer allocates a coroutine object
unless the body actually suspends.

Python-function CALL paths with the awaited flag mark the new frame of
a coroutine function (_MAYBE_LAZY_CORO). RETURN_GENERATOR then keeps
running the body in that frame, with its own exception state item on
the data stack. A body that returns or raises without suspending never
creates a coroutine object; YIELD_VALUE creates one when the body first
suspends and moves the frame into it.

The body reports how it ended through the slot that the compiler
pushes below the awaited call: a tagged int when it returned, or the
coroutine when it suspended. GET_AWAITABLE turns that into the SEND
loop's input: a NULL receiver makes SEND jump to END_SEND, and None in
place of the NULL makes it go on to YIELD_VALUE with the value that the
body has already yielded. All forms of SEND check for this, since an
await site may have been specialized for another awaitable. Exceptions
leaving the body are raised from the caller's SEND, as before.

Calls from C, instrumented calls, coroutine origin tracking, JIT trace
recording and tier 2 keep creating the coroutine eagerly.

frame.f_generator and PyFrame_GetGenerator() return None/NULL for such
a coroutine until it first suspends; asyncio.graph classifies frames
by co_flags instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35995996 | 📁 Comparing 9d2657d against main (ddd88c7)

  🔍 Preview build  

6 files changed · ± 6 modified

± Modified

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting core review type-feature A feature request or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant