Skip to content

Commit 0d4fd10

Browse files
Docs: Fix and improve the PyUnstable_Object_EnableDeferredRefcount documentation (GH-135323)
1 parent 609d5ad commit 0d4fd10

File tree

1 file changed

+7
-5
lines changed

1 file changed

+7
-5
lines changed

Doc/c-api/object.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -611,20 +611,22 @@ Object Protocol
611611
if supported by the runtime. In the :term:`free-threaded <free threading>` build,
612612
this allows the interpreter to avoid reference count adjustments to *obj*,
613613
which may improve multi-threaded performance. The tradeoff is
614-
that *obj* will only be deallocated by the tracing garbage collector.
614+
that *obj* will only be deallocated by the tracing garbage collector, and
615+
not when the interpreter no longer has any references to it.
615616
616-
This function returns ``1`` if deferred reference counting is enabled on *obj*
617-
(including when it was enabled before the call),
617+
This function returns ``1`` if deferred reference counting is enabled on *obj*,
618618
and ``0`` if deferred reference counting is not supported or if the hint was
619-
ignored by the runtime. This function is thread-safe, and cannot fail.
619+
ignored by the interpreter, such as when deferred reference counting is already
620+
enabled on *obj*. This function is thread-safe, and cannot fail.
620621
621622
This function does nothing on builds with the :term:`GIL` enabled, which do
622623
not support deferred reference counting. This also does nothing if *obj* is not
623624
an object tracked by the garbage collector (see :func:`gc.is_tracked` and
624625
:c:func:`PyObject_GC_IsTracked`).
625626
626627
This function is intended to be used soon after *obj* is created,
627-
by the code that creates it.
628+
by the code that creates it, such as in the object's :c:member:`~PyTypeObject.tp_new`
629+
slot.
628630
629631
.. versionadded:: 3.14
630632

0 commit comments

Comments
 (0)