From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 3 Mar 2020 03:03:56 +0000 (-0800)
Subject: bpo-39778: Add clarification about tp_traverse and ownership (GH-18754)
X-Git-Tag: v3.7.7rc1~5
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=72fff60d7649df88026838d8b5f14f541393f268;p=thirdparty%2FPython%2Fcpython.git

bpo-39778: Add clarification about tp_traverse and ownership (GH-18754)


Automerge-Triggered-By: @pablogsal
(cherry picked from commit 6df421fe87a9418d6c59f89dbc5d5573b6826855)

Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
---

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 71b45a6e7158..057187e4ba84 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -496,7 +496,7 @@ type objects) *must* have the :attr:`ob_size` field.
    The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect
    reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function
    simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python
-   objects.  For example, this is function :c:func:`local_traverse` from the
+   objects that the instance owns. For example, this is function :c:func:`local_traverse` from the
    :mod:`_thread` extension module::
 
       static int
@@ -516,6 +516,18 @@ type objects) *must* have the :attr:`ob_size` field.
    debugging aid you may want to visit it anyway just so the :mod:`gc` module's
    :func:`~gc.get_referents` function will include it.
 
+   .. warning::
+       When implementing :c:member:`~PyTypeObject.tp_traverse`, only the members
+       that the instance *owns* (by having strong references to them) must be
+       visited. For instance, if an object supports weak references via the
+       :c:member:`~PyTypeObject.tp_weaklist` slot, the pointer supporting
+       the linked list (what *tp_weaklist* points to) must **not** be
+       visited as the instance does not directly own the weak references to itself
+       (the weakreference list is there to support the weak reference machinery,
+       but the instance has no strong reference to the elements inside it, as they
+       are allowed to be removed even if the instance is still alive).
+
+
    Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
    :c:func:`local_traverse` to have these specific names; don't name them just
    anything.