[asvetlov]

What

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

• GET_AWAITABLE now also pushes the NULL and None that start the SEND loop, so the compiler emits one instruction between an awaited expression and SEND. This is the static marker RETURN_GENERATOR keys on, in the spirit of the super-instruction idea from Enable informing callee it's awaited via vector call flag #91121.
• RETURN_GENERATOR (tier 1 only): if the caller's next instruction is GET_AWAITABLE , the body keeps running in the already-pushed thread frame, marked lazy_coro. The caller's frame is set up exactly as SEND_GEN would leave it, so RETURN_VALUE or an exception lands in the right place with no object created.
• _YIELD_VALUE: a thread-owned frame reaching a yield is a lazy coroutine, the coroutine is materialized. Nested await chains materialize innermost-first, once each.
• Eager path kept for: callers from C (asyncio task steps, coro.send, functools.partial, ...), an instrumented SEND or END_SEND, coroutine origin tracking, while the JIT is recording a trace, and in tier 2 (_RETURN_GENERATOR stays a frame pop).

Why

A coroutine body that returns before its first await (fast paths, cache hits, bookkeeping-only __aenter__/__aexit__) pays for allocation, _PyFrame_Copy, GC tracking and deallocation for nothing.

Release build (no PGO/LTO), x86-64, per await:

	main	PR	callgrind Ir main → PR
await noop() (raw send)	70 ns	44 ns	1326 → 769
await noop() (asyncio.run)	71 ns	43 ns
async with no-op CM	187 ns	124 ns
await that suspends once (raw send)	228 ns	227 ns	4172 → 4166

Reviewer notes

• Observable difference: frame.f_generator / PyFrame_GetGenerator() return None/NULL for a lazy coroutine until it first suspends. asyncio.graph now classifies frames by co_flags; documented in datamodel.rst, inspect.rst, frame.rst and the whatsnew porting section.
• sys.exc_info() across a suspension inside a handler, tracebacks, __import__ locals, sys.settrace and sys.monitoring event sequences (including STOP_ITERATION) are unchanged versus eager; covered by LazyCoroutineTest in test_coroutines.py.
• Under LINE instrumentation SEND is rewritten (backward-jump target), so the optimization is off everywhere there; events match eager.
• test_opcache.test_send_with: its __aenter__ now suspends once, since the SEND it checks is otherwise never executed.
• JIT-compiled loops do not benefit yet (tier 2 stays eager); a follow-up.

🤖 Generated with Claude Code

• Issue: Speed up calling an async function that doesn't suspend #161170

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35578073 | 📁 Comparing e3e43cb against main (86be79a)

  🔍 Preview build  

6 files changed · ± 6 modified

± Modified

• c-api/frame.html
• library/dis.html
• library/inspect.html
• reference/datamodel.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[asvetlov]

I considered converting CALL+GET_AWAITABLE into a single CALL_AWAITABLE superinstruction, but it requires the duplication of all 25 CALL specializations, which could be a huge maintenance burden.
If we decide to go this way, CALL_AWAITABLE could be accompanied by a new C API for efficiently calling/awaiting async functions from C Extensions.
I could see benefits from this approach, but I prefer to make this step in a separate PR(s) if we decide.

Also, the initial source kept the byte code unchanged (CALL; GET_AWAITABLE; PUSH_NULL; LOAD_COMMON_CONSTANT None; SEND), the checker picked ahead 4 opcodes to analyze if the optimization is applicable.

GET_AWAITABLE on the 'main' is always followed by PUSH_NULL; LOAD_COMMON_CONSTANT None; SEND, the code generation change merges these into the single GET_AWAITABLE opcode and simplifies the look ahead. Also, it makes the code more robust; otherwise subtle changes in generated code could silently disable the optimization without notifying a user.

[asvetlov]

If we support the idea, I could prepare a PR for GET_AWAITABLE change first, and the follow-up PR for lazy coroutine initialization as the second part.