mirror of
https://github.com/python/cpython.git
synced 2025-07-24 11:44:31 +00:00
2b05361bf7
The new API allows to efficiently send values into native generators and coroutines avoiding use of StopIteration exceptions to signal returns. ceval loop now uses this method instead of the old "private" _PyGen_Send C API. This translates to 1.6x increased performance of 'await' calls in micro-benchmarks. Aside from CPython core improvements, this new API will also allow Cython to generate more efficient code, benefiting high-performance IO libraries like uvloop.
59 lines
1.9 KiB
ReStructuredText
59 lines
1.9 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
.. _gen-objects:
|
|
|
|
Generator Objects
|
|
-----------------
|
|
|
|
Generator objects are what Python uses to implement generator iterators. They
|
|
are normally created by iterating over a function that yields values, rather
|
|
than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
|
|
|
|
|
|
.. c:type:: PyGenObject
|
|
|
|
The C structure used for generator objects.
|
|
|
|
|
|
.. c:type:: PySendResult
|
|
|
|
The enum value used to represent different results of :c:func:`PyGen_Send`.
|
|
|
|
|
|
.. c:var:: PyTypeObject PyGen_Type
|
|
|
|
The type object corresponding to generator objects.
|
|
|
|
|
|
.. c:function:: int PyGen_Check(PyObject *ob)
|
|
|
|
Return true if *ob* is a generator object; *ob* must not be ``NULL``.
|
|
|
|
|
|
.. c:function:: int PyGen_CheckExact(PyObject *ob)
|
|
|
|
Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be ``NULL``.
|
|
|
|
|
|
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
|
|
|
|
Create and return a new generator object based on the *frame* object.
|
|
A reference to *frame* is stolen by this function. The argument must not be
|
|
``NULL``.
|
|
|
|
.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
|
|
|
|
Create and return a new generator object based on the *frame* object,
|
|
with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
|
|
A reference to *frame* is stolen by this function. The *frame* argument
|
|
must not be ``NULL``.
|
|
|
|
.. c:function:: PySendResult PyGen_Send(PyGenObject *gen, PyObject *arg, PyObject **presult)
|
|
|
|
Sends the *arg* value into the generator *gen*. Coroutine objects
|
|
are also allowed to be as the *gen* argument but they need to be
|
|
explicitly casted to PyGenObject*. Returns:
|
|
|
|
- ``PYGEN_RETURN`` if generator returns. Return value is returned via *presult*.
|
|
- ``PYGEN_NEXT`` if generator yields. Yielded value is returned via *presult*.
|
|
- ``PYGEN_ERROR`` if generator has raised and exception. *presult* is set to ``NULL``.
|