Skip to content

Commit d3251e7

Browse files
asvetlovclaude
andcommitted
gh-161170: Lazily materialize coroutine objects for awaited calls
`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>
1 parent c5a6156 commit d3251e7

33 files changed

Lines changed: 1825 additions & 344 deletions

‎Doc/c-api/frame.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,10 @@ See also :ref:`Reflection <reflection>`.
8585
8686
.. versionadded:: 3.11
8787
88+
.. versionchanged:: 3.16
89+
May return ``NULL`` for a coroutine frame before its first suspension;
90+
see :attr:`frame.f_generator`.
91+
8892
8993
.. c:function:: PyObject* PyFrame_GetGlobals(PyFrameObject *frame)
9094

‎Doc/library/inspect.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,9 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
151151
| | | coroutine object that |
152152
| | | owns this frame, or |
153153
| | | ``None`` if the frame is |
154-
| | | of a regular function |
154+
| | | of a regular function or |
155+
| | | the generator is not |
156+
| | | materialized yet |
155157
+-----------------+-------------------+---------------------------+
156158
| | f_trace | tracing function for this |
157159
| | | frame, or ``None`` |

‎Doc/reference/datamodel.rst‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1736,10 +1736,22 @@ Special read-only attributes
17361736

17371737
* - .. attribute:: frame.f_generator
17381738
- The :term:`generator` or :term:`coroutine` object that owns this frame,
1739-
or ``None`` if the frame is a normal function.
1739+
or ``None`` if the frame is a normal function or if the generator
1740+
is not materialized yet.
1741+
1742+
.. impl-detail::
1743+
1744+
A coroutine that is awaited as soon as it is called
1745+
(``await coro_func()``) may run without a coroutine object until
1746+
it first suspends, so this attribute is ``None`` before that.
1747+
Use :attr:`~codeobject.co_flags` of :attr:`frame.f_code` to tell
1748+
coroutine frames apart from normal function frames.
17401749

17411750
.. versionadded:: 3.14
17421751

1752+
.. versionchanged:: 3.16
1753+
May be ``None`` for a coroutine frame before its first suspension.
1754+
17431755
.. index::
17441756
single: f_trace (frame attribute)
17451757
single: f_trace_lines (frame attribute)

‎Doc/whatsnew/3.16.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1147,6 +1147,19 @@ datetime and time
11471147
(Contributed by Paul Ganssle in :gh:`158252`, based on work by
11481148
Stan Ulbrych.)
11491149

1150+
Interpreter
1151+
-----------
1152+
1153+
* A coroutine that is awaited as soon as it is called
1154+
(``await coro_func()``) now runs without creating a coroutine object
1155+
unless it suspends, making awaits that complete immediately about twice
1156+
as fast in a micro-benchmark (``await noop()``: 52 ns to 27 ns on x86-64).
1157+
This does not apply while coroutine origin tracking is enabled or inside
1158+
code compiled by the experimental JIT.
1159+
Until it first suspends, :attr:`frame.f_generator` is ``None`` for such a
1160+
coroutine; see :ref:`whatsnew316-porting`.
1161+
(Contributed by Andrew Svetlov in :gh:`161170`.)
1162+
11501163
re
11511164
--
11521165

@@ -1405,12 +1418,23 @@ New deprecations
14051418
.. include:: ../deprecations/pending-removal-in-future.rst
14061419

14071420

1421+
.. _whatsnew316-porting:
1422+
14081423
Porting to Python 3.16
14091424
======================
14101425

14111426
This section lists previously described changes and other bugfixes
14121427
that may require changes to your code.
14131428

1429+
* :attr:`frame.f_generator` and :c:func:`PyFrame_GetGenerator` may now
1430+
return ``None``/``NULL`` for a coroutine frame before its first
1431+
suspension, because a coroutine that is awaited as soon as it is called
1432+
(``await coro_func()``) runs without a coroutine object until then.
1433+
Code that used ``frame.f_generator is None`` to detect frames of normal
1434+
functions should check ``frame.f_code.co_flags`` for
1435+
:data:`~inspect.CO_COROUTINE` instead.
1436+
(Contributed by Andrew Svetlov in :gh:`161170`.)
1437+
14141438
* In :mod:`tkinter`, the *name* parameter of the
14151439
:meth:`~tkinter.Misc.wait_variable`, :meth:`~tkinter.Misc.setvar` and
14161440
:meth:`~tkinter.Misc.getvar` methods and the *value* parameter of
@@ -1488,6 +1512,22 @@ that may require changes to your code.
14881512
(Contributed by An Long in :gh:`86768`.)
14891513

14901514

1515+
CPython bytecode changes
1516+
========================
1517+
1518+
* The oparg of :opcode:`CALL` and :opcode:`CALL_KW` is now the number of
1519+
arguments shifted left by one. The low bit of their oparg, and of the
1520+
oparg of :opcode:`CALL_FUNCTION_EX`, marks a call whose result is awaited
1521+
right away.
1522+
(Contributed by Andrew Svetlov in :gh:`161170`.)
1523+
1524+
* ``await <call>`` now pushes an extra ``NULL`` below the callable and
1525+
follows the call with the new :opcode:`END_AWAITED_CALL` instruction,
1526+
which either goes on to :opcode:`GET_AWAITABLE`, skips the
1527+
:opcode:`SEND` loop, or jumps to its :opcode:`YIELD_VALUE`.
1528+
(Contributed by Andrew Svetlov in :gh:`161170`.)
1529+
1530+
14911531
Build changes
14921532
=============
14931533

‎Include/internal/pycore_ceval.h‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,12 @@ extern int _PyEval_EnsureBuiltinsWithModule(
267267
PyObject **p_builtins);
268268

269269
PyAPI_FUNC(PyObject *)_Py_MakeCoro(PyFunctionObject *func);
270+
// Lazily created coroutines (see RETURN_GENERATOR in bytecodes.c).
271+
// Exported for _testinternalcapi and external JIT support.
272+
PyAPI_FUNC(PyObject *) _PyCoro_MaterializeLazy(_PyInterpreterFrame *frame,
273+
_PyInterpreterFrame *caller);
274+
PyAPI_FUNC(PyGenObject *) _PyEval_MaterializeLazyCoro(PyThreadState *tstate,
275+
_PyInterpreterFrame *frame);
270276

271277
/* Handle signals, pending calls, GIL drop request
272278
and asynchronous exception */

‎Include/internal/pycore_interpframe.h‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,8 @@ static inline void _PyFrame_Copy(_PyInterpreterFrame *src, _PyInterpreterFrame *
152152
dest->stackpointer = dest->localsplus + stacktop;
153153
// visited is GC bookkeeping for the current stack walk, not frame state.
154154
dest->visited = 0;
155+
// A lazily started coroutine stops being lazy once its frame is copied.
156+
dest->lazy_coro = 0;
155157
#ifdef Py_DEBUG
156158
dest->stackpointer_valid = src->stackpointer_valid;
157159
dest->lltrace = src->lltrace;
@@ -208,6 +210,7 @@ _PyFrame_Initialize(
208210
frame->return_offset = 0;
209211
frame->owner = FRAME_OWNED_BY_THREAD;
210212
frame->visited = 0;
213+
frame->lazy_coro = 0;
211214
#ifdef Py_DEBUG
212215
frame->stackpointer_valid = 1;
213216
frame->lltrace = 0;
@@ -441,6 +444,7 @@ _PyFrame_PushTrampolineUnchecked(PyThreadState *tstate, PyCodeObject *code, int
441444
#endif
442445
frame->owner = FRAME_OWNED_BY_THREAD;
443446
frame->visited = 0;
447+
frame->lazy_coro = 0;
444448
#ifdef Py_DEBUG
445449
frame->stackpointer_valid = 1;
446450
frame->lltrace = 0;

‎Include/internal/pycore_interpframe_structs.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,10 @@ struct _PyInterpreterFrame {
4444
char owner;
4545
uint8_t visited:1;
4646
uint8_t external:1; /* Set when the frame was pushed by something other than the VM */
47+
uint8_t lazy_coro:1;
4748
#ifdef Py_DEBUG
4849
uint8_t stackpointer_valid:1;
49-
uint8_t lltrace:5;
50+
uint8_t lltrace:4;
5051
#endif
5152
/* Locals and stack */
5253
_PyStackRef localsplus[1];

0 commit comments

Comments
 (0)