From 3e07dde72e36b6b5303dd1dadf15f63506cbde87 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 9 Jun 2025 21:14:20 -0400 Subject: [PATCH 1/2] Docs: Fix and improve PyUnstable_Object_EnableDeferredRefcount documentation --- Doc/c-api/object.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 0fd159f1eb87f8..c0287e55b2dd12 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -596,12 +596,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 object's :term:`reference count` reaches zero. - 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 @@ -609,7 +610,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 From 1bb608867eabe78a9c57d32632e146143c52590e Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 9 Jun 2025 21:18:50 -0400 Subject: [PATCH 2/2] Use less misleading terminology. --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index c0287e55b2dd12..241fbd3a4866c7 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -597,7 +597,7 @@ Object Protocol 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, and - not when the object's :term:`reference count` reaches zero. + not when the interpreter no longer has any references to it. 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