@@ -611,20 +611,22 @@ Object Protocol
611
611
if supported by the runtime. In the :term: `free-threaded <free threading> ` build,
612
612
this allows the interpreter to avoid reference count adjustments to *obj *,
613
613
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.
615
616
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 *,
618
618
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.
620
621
621
622
This function does nothing on builds with the :term: `GIL ` enabled, which do
622
623
not support deferred reference counting. This also does nothing if *obj * is not
623
624
an object tracked by the garbage collector (see :func: `gc.is_tracked ` and
624
625
:c:func: `PyObject_GC_IsTracked `).
625
626
626
627
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.
628
630
629
631
.. versionadded:: 3.14
630
632
0 commit comments