Skip to content

gh-145921: Clarify return value of tp_traverse #160455

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.

Sign up for GitHub

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
encukou wants to merge 3 commits into
base: main
Choose a base branch
from
Open

gh-145921: Clarify return value of tp_traverse #160455

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
03d41f6
gh-145921: Clarify return value of tp_traverse
encukou Oct 23, 2026
2303aae
Fix Py_VISIT expansion
encukou Oct 23, 2026
c8f1f2a
More precise wording
encukou Oct 23, 2026
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
11 changes: 10 additions & 1 deletion Doc/c-api/gcsupport.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,7 @@ The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
to the handler. The *visit* function must not be called with a ``NULL``
object argument. If *visit* returns a non-zero value, that value should be
returned immediately.
Otherwise, return zero.

A typical :c:member:`!tp_traverse` function calls the :c:func:`Py_VISIT`
convenience macro on each of the instance's members that are Python
Expand Down Expand Up @@ -317,6 +318,14 @@ The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
For a list of safe functions, see a
:ref:`separate section <duringgc-functions>` below.

If an error occurs during traversal, ignore it and return 0.
If ``tp_traverse`` fails to visit some strong references, garbage reference
cycles involving the skipped references will not be reliably broken,
but correctness won't be affected.
For example, if traversal requires a lock that cannot be acquired promptly,
skip the traversal.
The garbage collector will visit your object again in a future pass.

.. note::

The :c:func:`Py_VISIT` call may be skipped for those members that provably
Expand Down Expand Up @@ -362,7 +371,7 @@ implementation must name its arguments exactly *visit* and *arg*:
This corresponds roughly to::

#define Py_VISIT(o) \
if (op) { \
if (o) { \
int visit_result = visit(o, arg); \
if (visit_result != 0) { \
return visit_result; \
Expand Down
Loading