summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/c-api/object.rst24
-rw-r--r--Doc/whatsnew/3.14.rst3
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
----------------------