Skip to content

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

Draft
asvetlov wants to merge 3 commits into
python:mainfrom
asvetlov:claude/lazy-coro-awaited-flag
Draft

asvetlov wants to merge 3 commits into
python:mainfrom
asvetlov:claude/lazy-coro-awaited-flag

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 a third take on the issue, after gh-161171 and gh-162238. The compiler marks awaited calls explicitly, and each instruction does a small, local part of the work:

  • CALL / CALL_KW / CALL_FUNCTION_EX carry 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. YIELD_VALUE creates the coroutine and moves the frame into it only when the body first suspends.
  • GET_AWAITABLE always pops two values and pushes the receiver, NULL and value that start the SEND loop. The compiler pushes a NULL right after an ordinary awaitable. For await <call>, it pushes the NULL below the callable and sets GET_AWAITABLE_AFTER_CALL (0b100) in the oparg; the low two bits keep the where value (0, 1, 2). A lazily run body reports how it ended through that slot: a tagged int if it returned, or the coroutine object if it suspended. GET_AWAITABLE turns this into the SEND input and 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. This is a single unlikely branch on the hot path.

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); 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.

Commits, for review: the CALL oparg encoding; the GET_AWAITABLE/codegen change (neither changes behavior on its own); and the lazy execution.

Performance

Release build without PGO, x86-64 (Golden Cove core, pinned), best of 6 runs:

main this PR
await noop() 50.7 ns 27.3 ns (−46%)
body that suspends once 197.1 ns 206.2 ns (+4.6%)
await Suspend() (not lazy) 140.5 ns 145.8 ns (+3.8%)

The remaining slowdown on suspending awaits is not extra work. A build of this PR with the lazy start and all its runtime checks compiled out executes the same number of instructions per await as main, and is just as slow. Top-down counters show that the difference is front-end bound: about 200 more uops per await come from the legacy decoders instead of the decoded uop cache, mostly in the SEND_GEN and GET_AWAITABLE handlers. This is a code-layout effect of the interpreter loop, so it still needs to be measured with PGO+LTO builds.

🤖 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.

GET_AWAITABLE also pops an extra slot. For `await <call>` the compiler
sets the awaited flag of the call, pushes a NULL below its callable and
sets GET_AWAITABLE_AFTER_CALL (4) in the oparg of GET_AWAITABLE; for
other awaitables it pushes the NULL right after the awaitable. The low
two bits of the oparg keep saying where the awaitable comes from.

Nothing writes to the slot 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>
@bedevere-app bedevere-app Bot added the type-feature A feature request or enhancement label Nov 18, 2026
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35997391 | 📁 Comparing b015d4f against main (f3c11aa)

  🔍 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

type-feature A feature request or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant