diff --git a/peps/pep-0852.rst b/peps/pep-0852.rst index e9bebc8d00d..9c741b85612 100644 --- a/peps/pep-0852.rst +++ b/peps/pep-0852.rst @@ -25,8 +25,7 @@ This PEP describes a new suite of functions in the C API to interact with static int return_result(PyObject *asyncobj, PyObject *result) { - PyAsync_SetResult(asyncobj, result); - return 1; + return PyAsync_SetResult(asyncobj, result) == 0; } /* Equivalent to: async def await_from_c(coro): return await coro */ @@ -204,6 +203,12 @@ argument must be a :c:type:`PyAsync` object; passing any other object is undefined behavior. Callbacks receive :term:`borrowed references ` to their arguments. +While the examples in this proposal heavily use the :mod:`asyncio` module, +nothing in this API depends on it, because :c:type:`PyAsync` object only +implements the coroutine *protocol* (:class:`collections.abc.Coroutine` +and not :class:`types.CoroutineType`). As such, a ``PyAsync`` object can +be driven by any event loop that can drive a non-native coroutine. + Async objects ------------- @@ -259,7 +264,11 @@ Async objects *result* must not be ``NULL``. This function stores a strong reference to *result*, releasing any - previously stored result. It cannot fail and returns ``0``. + previously stored result. + + Return ``0`` on success, or ``-1`` with an exception set on failure. + :exc:`TypeError` is raised if *asyncobj* is not a :c:type:`PyAsync` + object, and :exc:`SystemError` is raised if *result* is ``NULL``. Coroutine protocol @@ -357,12 +366,13 @@ returns success with an exception set, or failure without one, causes the Return ``0`` on success, or ``-1`` with an exception set on failure. -.. c:function:: int PyAsync_AddExpr(PyObject *asyncobj, PyObject *expr, PyAsync_Callback result_callback, PyAsync_Error error_callback) +.. c:function:: int PyAsync_AddAwaitSteal(PyObject *asyncobj, PyObject *awaitable, PyAsync_Callback result_callback, PyAsync_Error error_callback) - Like :c:func:`PyAsync_AddAwait`, but steals a reference to *expr* on - both success and failure. If *expr* is ``NULL``, return ``-1`` without - changing the current exception, which is assumed to have been set by - whatever produced *expr*. + Like :c:func:`PyAsync_AddAwait`, but steals a reference to *awaitable* + on both success and failure. If *awaitable* is ``NULL``, return ``-1`` + without changing the current exception, which is assumed to have been + set by whatever produced *awaitable*. This allows the result of a call + to be passed directly, without a separate error check. Otherwise, return ``0`` on success, or ``-1`` with an exception set on failure. @@ -392,7 +402,12 @@ returns success with an exception set, or failure without one, causes the The currently awaited operation, if any, is dropped without being closed. This function is unrelated to :mod:`asyncio` task cancellation, - which reaches the object through ``throw()``. It cannot fail. + which reaches the object through ``throw()``. + + This function cannot fail. Like a deallocator, it only releases + references; an exception raised by a destructor that runs as a result + is reported through :func:`sys.unraisablehook` and is not propagated to + the caller. .. c:function:: int PyAsync_AsyncWith(PyObject *asyncobj, PyObject *context_manager, PyAsync_Callback result_callback, PyAsync_Error error_callback) @@ -434,7 +449,7 @@ returns success with an exception set, or failure without one, causes the Value storage ------------- -Each :c:type:`PyAsync` object has one object slot and one arbitrary pointer +Each :c:type:`PyAsync` object has one object slot and one data pointer slot for storing state between callbacks. Both slots are initially ``NULL``. Code that needs more than one object stores a tuple or other container. @@ -443,7 +458,8 @@ Code that needs more than one object stores a tuple or other container. Store a strong reference to *value* in the object slot, releasing the previously stored reference. If *value* is ``NULL``, clear the slot. - This function cannot fail and returns ``0``. + Return ``0`` on success, or ``-1`` with :exc:`TypeError` set if + *asyncobj* is not a :c:type:`PyAsync` object. .. c:function:: PyObject *PyAsync_GetValue(PyObject *asyncobj) @@ -453,20 +469,31 @@ Code that needs more than one object stores a tuple or other container. does not set an exception when the slot is empty. -.. c:function:: int PyAsync_SetArbValue(PyObject *asyncobj, void *value) +.. c:function:: int PyAsync_SetData(PyObject *asyncobj, void *data, freefunc free_func) + + Store *data* in the data pointer slot, replacing the previous pointer. + *data* may be ``NULL``. - Store *value* in the arbitrary pointer slot, replacing the previous - pointer. *value* may be ``NULL``. The caller is responsible for the - lifetime of any memory referenced by the pointer. + *free_func* is a finalizer for *data*, and may be ``NULL``. If it is + not ``NULL``, it is called exactly once with *data* as its argument + when when it is replaced by another call to this function, or when *asyncobj* + is deallocated. - This function cannot fail and returns ``0``. + *free_func* is called with an :term:`attached thread state`. It must + not raise an exception and must not use *asyncobj*. If *free_func* is + ``NULL``, the caller is responsible for the lifetime of any memory + referenced by the pointer. + Return ``0`` on success, or ``-1`` with :exc:`TypeError` set if + *asyncobj* is not a :c:type:`PyAsync` object. On failure, *free_func* + is not called. -.. c:function:: void *PyAsync_GetArbValue(PyObject *asyncobj) - Return the pointer stored in the arbitrary pointer slot, or ``NULL`` - if the slot is empty. This function cannot fail and does not set an - exception when the slot is empty. +.. c:function:: void *PyAsync_GetData(PyObject *asyncobj) + + Return the pointer stored in the data pointer slot, or ``NULL`` if the + slot is empty. This function cannot fail and does not set an exception + when the slot is empty. Limited API @@ -488,6 +515,12 @@ an API for describing all capabilities of :mod:`asyncio`. While this PEP may be reason for adding an ``asyncio`` C API in the future, its only goal is to make :keyword:`async def` functions possible to implement in the C API. +As a result, :c:type:`PyAsync` objects are not specific to ``asyncio``. +They implement :class:`collections.abc.Coroutine` and nothing more, so they +work with any event loop that accepts coroutines, such as those provided by +Twisted, Tornado, or Trio. The specification and examples refer to +``asyncio`` only because it is the event loop in the standard library. + .. _pep-852-deviations: @@ -579,8 +612,7 @@ for the extension. static int return_result(PyObject *asyncobj, PyObject *result) { - PyAsync_SetResult(asyncobj, result); - return 1; + return PyAsync_SetResult(asyncobj, result) == 0; } /* Equivalent to: async def call_async(func): return await func() */ @@ -591,8 +623,8 @@ for the extension. if (asyncobj == NULL) { return NULL; } - if (PyAsync_AddExpr(asyncobj, PyObject_CallNoArgs(func), - return_result, NULL) < 0) { + if (PyAsync_AddAwaitSteal(asyncobj, PyObject_CallNoArgs(func), + return_result, NULL) < 0) { PyAsync_Cancel(asyncobj); Py_DECREF(asyncobj); return NULL; @@ -621,9 +653,9 @@ suspended. The callback releases the strong reference returned by if (result == NULL) { return 0; } - PyAsync_SetResult(asyncobj, result); + int res = PyAsync_SetResult(asyncobj, result); Py_DECREF(result); - return 1; + return res == 0; } @@ -631,7 +663,7 @@ Example: Handling a timeout *************************** In ``call_async`` above, replace the final ``NULL`` argument to -:c:func:`PyAsync_AddExpr` with ``timeout_to_none``. Awaiting the result +:c:func:`PyAsync_AddAwaitSteal` with ``timeout_to_none``. Awaiting the result then returns ``None`` on :exc:`TimeoutError`. Returning ``0`` from the callback lets other exceptions propagate. @@ -643,7 +675,9 @@ callback lets other exceptions propagate. if (!PyErr_GivenExceptionMatches(exception, PyExc_TimeoutError)) { return 0; } - PyAsync_SetResult(asyncobj, Py_None); + if (PyAsync_SetResult(asyncobj, Py_None) < 0) { + return -1; + } return 1; } @@ -677,7 +711,82 @@ which reuses ``return_result`` to return the completed packet. PyObject *reader = PyAsync_GetValue(asyncobj); PyObject *coro = PyObject_CallMethod(reader, "readexactly", "O", size); Py_DECREF(reader); - return PyAsync_AddExpr(asyncobj, coro, return_result, NULL) == 0; + return PyAsync_AddAwaitSteal(asyncobj, coro, return_result, NULL) == 0; + } + + +Example: Sharing a C structure between callbacks +************************************************ + +State that is not a Python object can be kept in a structure stored with +:c:func:`PyAsync_SetData`. Passing a free function ties the structure's +lifetime to the :c:type:`PyAsync` object, so it is released even if +``first`` or ``second`` raises and ``add_second`` never runs. + +.. code-block:: c + + typedef struct { + long long total; + } sum_state; + + static int + add_second(PyObject *asyncobj, PyObject *value) + { + sum_state *state = PyAsync_GetData(asyncobj); + long long number = PyLong_AsLongLong(value); + if (number == -1 && PyErr_Occurred()) { + return 0; + } + PyObject *result = PyLong_FromLongLong(state->total + number); + if (result == NULL) { + return 0; + } + int res = PyAsync_SetResult(asyncobj, result); + Py_DECREF(result); + return res == 0; + } + + static int + add_first(PyObject *asyncobj, PyObject *value) + { + sum_state *state = PyAsync_GetData(asyncobj); + state->total = PyLong_AsLongLong(value); + return !(state->total == -1 && PyErr_Occurred()); + } + + /* Equivalent to: async def add(first, second): + return (await first) + (await second) */ + static PyObject * + add(PyObject *self, PyObject *args) /* METH_VARARGS */ + { + PyObject *first, *second; + if (!PyArg_ParseTuple(args, "OO", &first, &second)) { + return NULL; + } + PyObject *asyncobj = PyAsync_New(); + if (asyncobj == NULL) { + return NULL; + } + sum_state *state = PyMem_Malloc(sizeof(sum_state)); + if (state == NULL) { + PyErr_NoMemory(); + goto error; + } + state->total = 0; + if (PyAsync_SetData(asyncobj, state, PyMem_Free) < 0) { + PyMem_Free(state); + goto error; + } + if (PyAsync_AddAwait(asyncobj, first, add_first, NULL) < 0 + || PyAsync_AddAwait(asyncobj, second, add_second, NULL) < 0) { + goto error; + } + return asyncobj; + + error: + PyAsync_Cancel(asyncobj); + Py_DECREF(asyncobj); + return NULL; } @@ -738,6 +847,115 @@ Python code passes the lock and dictionary through the context manager: lock, and releases the lock even if the dictionary update raises an exception. +.. _pep-852-cpp-wrapper: + +Example: Implementing a C++ wrapper +*********************************** + +Wrappers for other languages usually want each callback to be a closure +with its own captured state, such as a ``std::function`` in C++. A wrapper +that does this can be implemented on top of this API: + +.. code-block:: cpp + + #include + #include + #include + #include + #include + + using Callback = std::function; + using Queue = std::deque; + + static void + free_queue(void *ptr) + { + delete static_cast(ptr); + } + + static int + trampoline(PyObject *asyncobj, PyObject *result) + { + auto *queue = static_cast(PyAsync_GetData(asyncobj)); + Callback callback = std::move(queue->front()); + queue->pop_front(); + try { + return callback(asyncobj, result); + } + catch (const std::exception &exc) { + /* C++ exceptions must not unwind into the interpreter. */ + PyErr_SetString(PyExc_RuntimeError, exc.what()); + return 0; + } + } + + static int + add_await(PyObject *asyncobj, PyObject *awaitable, Callback callback) + { + auto *queue = static_cast(PyAsync_GetData(asyncobj)); + try { + if (queue == nullptr) { + auto owned = std::make_unique(); + if (PyAsync_SetData(asyncobj, owned.get(), free_queue) < 0) { + return -1; + } + /* The async object owns the queue from here on. */ + queue = owned.release(); + } + queue->push_back(std::move(callback)); + } + catch (const std::bad_alloc &) { + PyErr_NoMemory(); + return -1; + } + if (PyAsync_AddAwait(asyncobj, awaitable, trampoline, nullptr) < 0) { + queue->pop_back(); + return -1; + } + return 0; + } + +With this wrapper, a coroutine function can be written using lambdas that +capture their own state: + +.. code-block:: cpp + + /* Equivalent to: async def scale(awaitable, factor): + return (await awaitable) * factor */ + static PyObject * + scale(PyObject *self, PyObject *args) /* METH_VARARGS */ + { + PyObject *awaitable; + double factor; + if (!PyArg_ParseTuple(args, "Od", &awaitable, &factor)) { + return nullptr; + } + PyObject *asyncobj = PyAsync_New(); + if (asyncobj == nullptr) { + return nullptr; + } + auto multiply = [factor](PyObject *asyncobj, PyObject *value) -> int { + double number = PyFloat_AsDouble(value); + if (number == -1.0 && PyErr_Occurred()) { + return 0; + } + PyObject *result = PyFloat_FromDouble(number * factor); + if (result == nullptr) { + return 0; + } + int res = PyAsync_SetResult(asyncobj, result); + Py_DECREF(result); + return res == 0; + }; + if (add_await(asyncobj, awaitable, multiply) < 0) { + PyAsync_Cancel(asyncobj); + Py_DECREF(asyncobj); + return nullptr; + } + return asyncobj; + } + + Reference Implementation ======================== @@ -784,6 +1002,46 @@ around C code without emulating a frame. A new type is simpler and avoids exposing frame internals. +Per-callback data pointers +-------------------------- + +Antoine Pitrou `suggested `__ that +each callback should take its own user data argument, as most callback-based +C APIs do: + +.. code-block:: c + + typedef int (*PyAsync_Callback)(PyObject *asyncobj, + PyObject *result, uintptr_t data); + typedef int (*PyAsync_Error)(PyObject *asyncobj, + PyObject *exception, uintptr_t data); + int PyAsync_AddAwait( + PyObject *asyncobj, PyObject *awaitable, + PyAsync_Callback result_cb, uintptr_t result_cb_data, + PyAsync_Error error_cb, uintptr_t error_cb_data); + +This was rejected in favor of a single data pointer per :c:type:`PyAsync` +object, for the following reasons: + +1. The callbacks of a :c:type:`PyAsync` object are not independent + components. They are the pieces of one coroutine function, split up only + because C has no native ``await``, and they run in an order known to the + developer. The data pointer plays the role of the function's local + variables, which are naturally shared by the whole function. +2. Per-callback data makes every function that queues an operation take two + more arguments, and increases the size of each queue entry by two + pointers, even though most users would pass the same pointer (or ``NULL``) + every time. +3. Each per-callback pointer would need its own lifetime management, which + either means two more finalizer arguments per operation or a source of + leaks when an operation is cancelled before its callback runs. + +Wrappers that do want a closure per callback (for example, a C++ wrapper +that accepts ``std::function`` objects) can be built on the single data +pointer by storing a queue of closures in it and registering a trampoline as +the callback; see :ref:`the C++ wrapper example `. + + Keeping the API in a third-party library ---------------------------------------- @@ -806,7 +1064,17 @@ discussion, and to all users of PyAwaitable over the past few years. Change History ============== -TBD. +- 14-Nov-2026 + + - Renamed ``PyAsync_AddExpr`` to :c:func:`PyAsync_AddAwaitSteal`. + - Renamed ``PyAsync_SetArbValue`` and ``PyAsync_GetArbValue`` to + :c:func:`PyAsync_SetData` and :c:func:`PyAsync_GetData`. + - Added a *free_func* parameter to :c:func:`PyAsync_SetData`. + - :c:func:`PyAsync_SetResult`, :c:func:`PyAsync_SetValue`, and + :c:func:`PyAsync_SetData` can now fail instead of always returning ``0``. + - Clarified that :c:type:`PyAsync` objects are not tied to :mod:`asyncio`, + and that :c:func:`PyAsync_Cancel` reports errors as unraisable exceptions. + - Added "Per-callback data pointers" to the rejected ideas. Copyright