summaryrefslogtreecommitdiffstats
path: root/Doc/c-api
diff options
context:
space:
mode:
authorMiss Islington (bot) <31488909+miss-islington@users.noreply.github.com>2020-03-03 03:04:13 (GMT)
committerGitHub <noreply@github.com>2020-03-03 03:04:13 (GMT)
commit1827fc30f463786ebff13752e35c3224652bc94e (patch)
tree3d88436eb00f501e60ff6e8445cdea0f9482d36f /Doc/c-api
parent394dc0db878c08d003772de163a57ac12046d865 (diff)
downloadcpython-1827fc30f463786ebff13752e35c3224652bc94e.zip
cpython-1827fc30f463786ebff13752e35c3224652bc94e.tar.gz
cpython-1827fc30f463786ebff13752e35c3224652bc94e.tar.bz2
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>
Diffstat (limited to 'Doc/c-api')
-rw-r--r--Doc/c-api/typeobj.rst14
1 files changed, 13 insertions, 1 deletions
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index bff5abf..163f599 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1218,7 +1218,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
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
@@ -1238,6 +1238,18 @@ and :c:type:`PyType_Type` effectively act as defaults.)
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.