Skip to content

gh-161170: Lazily materialize coroutine objects via END_AWAITED_CALL - #162267

Draft
asvetlov wants to merge 7 commits into
python:mainfrom
asvetlov:claude/lazy-coroutine-materialization-5e5705
Draft

asvetlov wants to merge 7 commits into
python:mainfrom
asvetlov:claude/lazy-coroutine-materialization-5e5705

Conversation

@asvetlov

@asvetlov asvetlov commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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

This is an alternative to #162238 / #162242. It keeps the awaited flag in the call oparg and the slot below the callable, but puts all the handling into one new instruction after the call. GET_AWAITABLE, SEND and END_SEND stay as on main.

Bytecode

PUSH_NULL                         # slot
LOAD_GLOBAL f + NULL ; args...
CALL 2*nargs+1                    # awaited bit (CALL_KW, CALL_FUNCTION_EX too)
END_AWAITED_CALL L_yield
GET_AWAITABLE 0 ; PUSH_NULL ; LOAD_COMMON_CONSTANT None
L_send:  SEND L_end
L_yield: YIELD_VALUE 1 ; RESUME 3 ; JUMP_BACKWARD_NO_INTERRUPT L_send
L_end:   END_SEND

END_AWAITED_CALL handles the slot as follows:

  • NULL: the call did not run lazily. The slot is popped and execution continues with GET_AWAITABLE.
  • Tagged int: the body returned. The SEND loop is skipped. The target is past the END_SEND that the SEND before YIELD_VALUE jumps to.
  • Frame: the body suspended. YIELD_VALUE left the frame and its exception state on the data stack. END_AWAITED_CALL creates the coroutine, moves both into it, and jumps to YIELD_VALUE with (coroutine, NULL, value), as SEND would have left them.
  • Raise: if the body raises, the exception is raised from END_AWAITED_CALL, which has the await's location, so tracebacks are unchanged.

The flowgraph gives the jump edge a stack effect of +1. The except-stack pass does not follow it, because the SEND fallthrough sets up the SETUP_FINALLY around YIELD_VALUE.

END_AWAITED_CALL is never instrumented (like RESUME/END_FOR), so nothing can run between the body's suspension and the coroutine's creation. When the END_SEND it skips is instrumented, it reports the STOP_ITERATION event.

Calls from C, instrumented calls, coroutine origin tracking, JIT trace recording and tier 2 keep creating the coroutine eagerly. frame.f_generator / PyFrame_GetGenerator() are None/NULL for such a coroutine until it first suspends.

Commits

  1. Encode the awaited flag in the oparg of CALL, CALL_KW and CALL_FUNCTION_EX (no behavior change).
  2. Add END_AWAITED_CALL after awaited calls (no behavior change).
  3. Lazily materialize coroutine objects.

Benchmark (release build, x86-64, best of 7)

main this PR
await noop() 52 ns 27 ns
chain of 10 nested awaits 617 ns 327 ns
await that suspends once 139 ns 144 ns

🤖 Generated with Claude Code

asvetlov and others added 3 commits November 19, 2026 13:05
… 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>
`await <call>` now pushes a NULL slot below the callable, sets the
awaited flag of the call and follows it with END_AWAITED_CALL, which
jumps to the YIELD_VALUE of the SEND loop that follows.

The slot is meant to tell how a coroutine body that the call ran
without creating the coroutine object ended. END_AWAITED_CALL pops a
NULL slot and goes on to GET_AWAITABLE; for a tagged int (the body
returned) it skips the SEND loop, finding the END_SEND through the
SEND right before YIELD_VALUE. Nothing writes to the slot yet, so there
is no behavior change.

The jump to YIELD_VALUE has a stack effect of +1 (coroutine, NULL and
value in place of slot and value), and lands inside the SETUP_FINALLY
of the SEND loop, which the fallthrough from SEND sets up.

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. The body reports how it ended through the slot below
the awaited call, and END_AWAITED_CALL acts on it:

- the body returned: clear_thread_frame() stores a tagged int, and
  END_AWAITED_CALL skips the SEND loop;
- the body suspended: YIELD_VALUE leaves the frame and its exception
  state on the data stack and stores the frame. END_AWAITED_CALL
  creates the coroutine, moves both into it and jumps to the
  YIELD_VALUE of the SEND loop with (coroutine, NULL, value), as SEND
  would have left them;
- the body raised: the exception is raised from END_AWAITED_CALL,
  which has the location of the await.

END_AWAITED_CALL is never instrumented, so nothing runs between the
body's suspension and the creation of its coroutine. It reports the
STOP_ITERATION event of the END_SEND it skips.

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 19, 2026
@read-the-docs-community

read-the-docs-community Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

asvetlov and others added 4 commits November 19, 2026 14:05
clear_thread_frame() runs on every return from a Python function. With
the lazy coroutine handling inline it was no longer inlined into
_PyEval_FrameClearAndPop() and kept a value across the frame pop, adding
about 9 instructions per return. Move that handling into a separate
non-inlined function.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Store the number of arguments of CALL and CALL_KW in the oparg as before
and mark awaited calls with bit 0x80 instead of shifting the count. The
compiler never emits these calls with that many arguments. Only the
generic forms mask the bit out; awaited call sites are not specialized,
so the specialized forms use the oparg as is and no longer check for an
awaited call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CALL_PY_EXACT_ARGS_AWAITED, CALL_BOUND_METHOD_EXACT_ARGS_AWAITED,
CALL_PY_GENERAL_AWAITED, CALL_BOUND_METHOD_GENERAL_AWAITED,
CALL_KW_PY_AWAITED and CALL_KW_BOUND_METHOD_AWAITED are the plain forms
with CALL_AWAITED cleared from oparg first (_CLEAR_CALL_AWAITED), so they
share all other uops, and with the coroutine body started lazily
(_START_LAZY_CORO). Tier two clears CALL_AWAITED when translating and
starts the coroutine eagerly.

The recording uops of the CALL and CALL_KW families mask CALL_AWAITED
too: they also run for awaited call sites.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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