From: Peter Bierma Date: Sun, 13 Jul 2025 06:46:13 +0000 (-0400) Subject: Docs: Fix and improve the `PyUnstable_Object_EnableDeferredRefcount` documentation... X-Git-Tag: v3.15.0a1~991 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0d4fd10fbab2767fad3eb27639905c8885b88c89;p=thirdparty%2FPython%2Fcpython.git Docs: Fix and improve the `PyUnstable_Object_EnableDeferredRefcount` documentation (GH-135323) --- diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 21fa1491b33d..55f0d0f9fb7f 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -611,12 +611,13 @@ Object Protocol if supported by the runtime. In the :term:`free-threaded ` 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. + that *obj* will only be deallocated by the tracing garbage collector, and + not when the interpreter no longer has any references to it. - This function returns ``1`` if deferred reference counting is enabled on *obj* - (including when it was enabled before the call), + This function returns ``1`` if deferred reference counting is enabled on *obj*, 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. + ignored by the interpreter, such as when deferred reference counting is already + enabled on *obj*. 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 @@ -624,7 +625,8 @@ Object Protocol :c:func:`PyObject_GC_IsTracked`). This function is intended to be used soon after *obj* is created, - by the code that creates it. + by the code that creates it, such as in the object's :c:member:`~PyTypeObject.tp_new` + slot. .. versionadded:: 3.14