@@ -496,7 +496,7 @@ type objects) *must* have the :attr:`ob_size` field.
496
496
The :c:member: `~PyTypeObject.tp_traverse ` pointer is used by the garbage collector to detect
497
497
reference cycles. A typical implementation of a :c:member: `~PyTypeObject.tp_traverse ` function
498
498
simply calls :c:func: `Py_VISIT ` on each of the instance's members that are Python
499
- objects. For example, this is function :c:func: `local_traverse ` from the
499
+ objects that the instance owns. For example, this is function :c:func: `local_traverse ` from the
500
500
:mod: `_thread ` extension module::
501
501
502
502
static int
@@ -516,6 +516,18 @@ type objects) *must* have the :attr:`ob_size` field.
516
516
debugging aid you may want to visit it anyway just so the :mod: `gc ` module's
517
517
:func: `~gc.get_referents ` function will include it.
518
518
519
+ .. warning ::
520
+ When implementing :c:member: `~PyTypeObject.tp_traverse `, only the members
521
+ that the instance *owns * (by having strong references to them) must be
522
+ visited. For instance, if an object supports weak references via the
523
+ :c:member: `~PyTypeObject.tp_weaklist ` slot, the pointer supporting
524
+ the linked list (what *tp_weaklist * points to) must **not ** be
525
+ visited as the instance does not directly own the weak references to itself
526
+ (the weakreference list is there to support the weak reference machinery,
527
+ but the instance has no strong reference to the elements inside it, as they
528
+ are allowed to be removed even if the instance is still alive).
529
+
530
+
519
531
Note that :c:func: `Py_VISIT ` requires the *visit * and *arg * parameters to
520
532
:c:func: `local_traverse ` to have these specific names; don't name them just
521
533
anything.
0 commit comments