diff options
| author | Peter Bierma <zintensitydev@gmail.com> | 2024-11-13 13:27:16 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-11-13 13:27:16 (GMT) |
| commit | d00878b06a05ea04790813dba70b09cc1d11bf45 (patch) | |
| tree | e7508c9d7769379ae50a0f6e7572a61bb6dc952f /Doc | |
| parent | 29b5323c4567dc7772e1d30a7ba1cbad52fe10a9 (diff) | |
| download | cpython-d00878b06a05ea04790813dba70b09cc1d11bf45.zip cpython-d00878b06a05ea04790813dba70b09cc1d11bf45.tar.gz cpython-d00878b06a05ea04790813dba70b09cc1d11bf45.tar.bz2 | |
gh-123619: Add an unstable C API function for enabling deferred reference counting (GH-123635)
Co-authored-by: Sam Gross <colesbury@gmail.com>
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/object.rst | 24 | ||||
| -rw-r--r-- | Doc/whatsnew/3.14.rst | 3 |
2 files changed, 27 insertions, 0 deletions
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 630114a..1e1cf6e 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -575,3 +575,27 @@ Object Protocol has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set. .. versionadded:: 3.13 + +.. c:function:: int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj) + + Enable `deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_ on *obj*, + if supported by the runtime. In the :term:`free-threaded <free threading>` build, + this allows the interpreter to avoid reference count adjustments to *obj*, + which may improve multi-threaded performance. The tradeoff is + that *obj* will only be deallocated by the tracing garbage collector. + + This function returns ``1`` if deferred reference counting is enabled on *obj* + (including when it was enabled before the call), + and ``0`` if deferred reference counting is not supported or if the hint was + ignored by the runtime. This function is thread-safe, and cannot fail. + + This function does nothing on builds with the :term:`GIL` enabled, which do + not support deferred reference counting. This also does nothing if *obj* is not + an object tracked by the garbage collector (see :func:`gc.is_tracked` and + :c:func:`PyObject_GC_IsTracked`). + + This function is intended to be used soon after *obj* is created, + by the code that creates it. + + .. versionadded:: next + diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index a98fe3f..31754fb 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -890,6 +890,9 @@ New features * Add :c:func:`PyType_Freeze` function to make a type immutable. (Contributed by Victor Stinner in :gh:`121654`.) +* Add :c:func:`PyUnstable_Object_EnableDeferredRefcount` for enabling + deferred reference counting, as outlined in :pep:`703`. + Porting to Python 3.14 ---------------------- |