Skip to content

gh-161170: Add ASYNC_CALL/ASYNC_CALL_KW families and create awaited coroutines lazily - #33

Closed
asvetlov wants to merge 2 commits into
mainfrom
claude/async-call-instruction-families-83d0c4
Closed

asvetlov wants to merge 2 commits into
mainfrom
claude/async-call-instruction-families-83d0c4

Conversation

@asvetlov

Copy link
Copy Markdown
Owner

What

Two commits, each reviewable on its own.

1. ASYNC_CALL and ASYNC_CALL_KW instruction families

The compiler emits ASYNC_CALL (or ASYNC_CALL_KW) instead of CALL (or CALL_KW) for a call whose result is awaited at once: await f(...), the __aenter__/__aexit__ calls of async with, and the call of a non-inlined async comprehension. The instruction is always followed by GET_AWAITABLE; PUSH_NULL; LOAD_COMMON_CONSTANT None; SEND. Unspecialized, it does the same as CALL.

When the callee is a coroutine function the specializer rewrites it to one of ASYNC_CALL_PY_EXACT_ARGS, ASYNC_CALL_BOUND_METHOD_EXACT_ARGS, ASYNC_CALL_PY_GENERAL, ASYNC_CALL_BOUND_METHOD_GENERAL, ASYNC_CALL_KW_PY, ASYNC_CALL_KW_BOUND_METHOD. These reuse the uops of the matching CALL_* specialization and merge the call with the first execution of the instructions that follow it, so the coroutine is started in place instead of being returned to the caller first. The families are coroutine-only: any other callee stays on the unspecialized ASYNC_CALL.

Costs: 2 base, 6 specialized and 2 instrumented opcodes (INSTRUMENTED_ASYNC_CALL[_KW]), and a magic number bump.

2. Lazy coroutine creation

The specializations no longer create the coroutine object when they start the body. The body runs in the frame of the call, marked lazy_coro, with its own exception state pushed on the data stack right after the frame, while the caller is left as if SEND_GEN had pushed the frame of a coroutine. A body that returns or raises before it suspends never gets a coroutine object. The first YIELD_VALUE in such a frame creates the coroutine, moves the frame into it and replaces the None that stood in for it on the caller's stack.

This is the approach of python#161171 with the RETURN_GENERATOR look-ahead replaced by the opcode: RETURN_GENERATOR only checks frame->lazy_coro, and the conditions that look-ahead had to check at every call now live in the specializer and in _GUARD_ASYNC_CALL_TAIL (instrumented tail, coroutine origin tracking). Because the decision is a uop, tier 2 takes the lazy path too; python#161171 had to stay eager there.

Why

An explicit opcode is a more robust signal than matching the instructions that follow a call, and it is the natural anchor for further work on awaited calls (frame materialization). Release build, x86-64, per await, main → this branch:

main branch
await noop() 51.4 ns 25.5 ns
async with no-op CM 175.9 ns 115.5 ns
await that suspends once 190.4 ns 189.2 ns

Reviewer notes

  • Observable difference: frame.f_generator / PyFrame_GetGenerator() are None/NULL for a lazily started coroutine until it first suspends, once the call is specialized. asyncio.graph classifies frames by co_flags now; documented in datamodel.rst, inspect.rst, frame.rst and the whatsnew porting section.
  • Awaited calls to callables that are not coroutine functions (await asyncio.gather(...), await SomeClass()) lose their CALL_* specialization, and a tier-2 trace ends at such a call. A non-coroutine fallback member can be added later if benchmarks show it matters.
  • sys.settrace / sys.monitoring event sequences, sys.exc_info() across a suspension inside a handler, tracebacks and __import__ locals match the eager path; covered by LazyCoroutineTest in test_coroutines.py, which warms each site past the specialization threshold.
  • Verified: full test suite (debug build), -R 3:3 on the coroutine, opcache and monitoring tests, and a --enable-experimental-jit=interpreter build for test_capi.test_opt, test_coroutines, test_opcache, test_asyncio.
  • No NEWS entry yet.

🤖 Generated with Claude Code

asvetlov and others added 2 commits November 18, 2026 15:38
The compiler emits ASYNC_CALL (or ASYNC_CALL_KW) instead of CALL (or
CALL_KW) for a call whose result is awaited at once: `await f(...)`,
the __aenter__ and __aexit__ calls of `async with`, and the call of an
async comprehension. The instruction is always followed by GET_AWAITABLE,
PUSH_NULL, LOAD_COMMON_CONSTANT None and SEND. Unspecialized, it does the
same as CALL.

When the callee is a coroutine function, the specializer rewrites it to
ASYNC_CALL_PY_EXACT_ARGS, ASYNC_CALL_BOUND_METHOD_EXACT_ARGS,
ASYNC_CALL_PY_GENERAL, ASYNC_CALL_BOUND_METHOD_GENERAL, ASYNC_CALL_KW_PY
or ASYNC_CALL_KW_BOUND_METHOD. These merge the call with the first
execution of the instructions that follow it: the new coroutine is
started in place, without being returned to the caller first. They reuse
the uops of the matching CALL_* specialization, with the new
_ASYNC_CALL_GEN_FRAME uop in place of _SAVE_RETURN_OFFSET.

RETURN_GENERATOR does nothing in a frame that already belongs to a
generator, so that coroutine functions whose prologue has COPY_FREE_VARS
or MAKE_CELL use the fast path too.

Calls to callables that are not coroutine functions are not specialized:
the ASYNC_CALL families hold only the coroutine specializations.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The ASYNC_CALL_* specializations no longer create the coroutine object
when they start the body of the coroutine function. The body runs in
the frame of the call, marked lazy_coro, with its own exception state
pushed on the data stack right after the frame, while the caller is
left as if SEND_GEN had pushed the frame of a coroutine. A body that
returns or raises before it suspends never gets a coroutine object.

The first YIELD_VALUE in such a frame creates the coroutine, moves the
frame into it and replaces the None that stood in for it on the stack
of the caller; from then on it is an ordinary coroutine.

RETURN_GENERATOR in a lazy frame only pushes the None that the
following POP_TOP discards. While coroutine origin tracking is on, the
object has to exist at creation, so ASYNC_CALL is not specialized and
the guard of the specializations deoptimizes.

Until it first suspends, frame.f_generator is None for such a coroutine.
asyncio.graph classifies frames by their code flags instead.

This replaces the look-ahead at the caller's next instruction of
RETURN_GENERATOR proposed in pythongh-161171 with the ASYNC_CALL opcode.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@asvetlov asvetlov closed this Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant