Skip to content

Docs: Fix and improve the PyUnstable_Object_EnableDeferredRefcount documentation #135323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions Doc/c-api/object.rst
Original file line number Diff line number Diff line change
Expand Up @@ -596,20 +596,22 @@ Object Protocol
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.
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
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.
by the code that creates it, such as in the object's :c:member:`~PyTypeObject.tp_new`
slot.

.. versionadded:: 3.14

Expand Down
Loading