https://github.com/python/cpython/commit/a6616f25d95a497ed05e3bb23ae7aa982c2845ce commit: a6616f25d95a497ed05e3bb23ae7aa982c2845ce branch: 3.15 author: Miss Islington (bot) <[email protected]> committer: encukou <[email protected]> date: 2026-10-28T18:16:56+01:00 summary:
[3.15] gh-145921: Clarify return value of tp_traverse (GH-160455) (GH-160826) (cherry picked from commit cfe7e0a5ea5043991492ee71a8c6a322172b353a) Co-authored-by: Petr Viktorin <[email protected]> files: M Doc/c-api/gcsupport.rst diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst index 9c71bb3d59d5e9..904303274ba075 100644 --- a/Doc/c-api/gcsupport.rst +++ b/Doc/c-api/gcsupport.rst @@ -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 @@ -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 @@ -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; \ _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
