gh-145921: Add "_DuringGC" functions for tp_traverse by encukou · Pull Request #145925 · python/cpython

encukou · 2026-03-13T15:48:54Z

There are newly documented restrictions on tp_traverse:

The traversal function must not have any side effects.
It must not modify the reference counts of any Python
objects nor create or destroy any Python objects.

Add several functions that are guaranteed side-effect-free, with a _DuringGC suffix.
Use these in ctypes
Consolidate tp_traverse docs in gcsupport.rst, moving unique content from typeobj.rst there

Issue: Add _DuringGC functions for tp_traverse #145921

📚 Documentation preview 📚: https://cpython-previews--145925.org.readthedocs.build/

There are newly documented restrictions on tp_traverse: The traversal function must not have any side effects. It must not modify the reference counts of any Python objects nor create or destroy any Python objects. * Add several functions that are guaranteed side-effect-free, with a _DuringGC suffix. * Use these in ctypes * Consolidate tp_traverse docs in gcsupport.rst, moving unique content from typeobj.rst there

zooba

Mostly doc suggestions, the actual change LGTM!

zooba · 2026-03-16T20:22:20Z

Doc/c-api/gcsupport.rst

+   The traversal function has a limitation:
+
+   .. warning::


I don't think this kind of structure flows well in the docs? It probably works better to go straight to the warning, then in the paragraph after it replace "This means" with "The limitation on side effects means ..."

Hmm, I'll push back here.
The red box looks like it stands on its own. Maybe it's my banner blindness that kicks in, but my brain doesn't immediately connect "The limitation on side effects" to the box above it, so I added the line to make it a part of the running text more obviously.

zooba · 2026-03-16T20:25:48Z

Doc/c-api/gcsupport.rst

+   effects may start having them in future versions, without warning.
+
+   For a list of safe functions, see a
+   :ref:`separate section <durniggc-functions>` below.


Suggested change

:ref:`separate section <durniggc-functions>` below.

:ref:`separate section <duringgc-functions>` below.

If this didn't trigger a build warning, maybe you've got other typos?

Also, I prefer to name the section even when it's linked, so that someone can find it or recognise it later without actually having to click the link.

Thanks for the catch!
The other typo is in the link target itself ;)

zooba · 2026-03-16T20:27:17Z

Doc/c-api/gcsupport.rst

+   .. note::
+
+      The :c:member:`~PyTypeObject.tp_traverse` function can be called from any
+      thread.


Should we mention something about "though all other Python threads are guaranteed to be blocked at the time" here?

AFAIK that's an implementation detail some people want to get rid of.

zooba · 2026-03-16T20:30:26Z

Doc/c-api/gcsupport.rst

+   Note that these functions may fail (return ``NULL`` or -1).
+   Only creating and setting the exception is suppressed.


If they fail during tp_traverse, should we be bailing out as quickly as possible? What value should we return?

That's a good question; honestly I'm not sure about the intentions behind tp_traverse's result.

@pablogsal: would it be correct to say tp_traverse should return zero on recoverable errors, including being unable to visit some objects?
Currently gc.c ignores errors*, but non-zero a result makes VISIT return early; gc_free_threading.c calls PyErr_NoMemory if traversal fails.

* except _PyGC_GetReferrers (gc.get_referrers) which instead assumes that tp_traverse sets an exception on failure -- that's wrong, right?

zooba · 2026-03-16T20:31:54Z

Doc/c-api/gcsupport.rst

+   Note that these functions may fail (return ``NULL`` or -1).
+   Only creating and setting the exception is suppressed.


Suggested change

Note that these functions may fail (return ``NULL`` or -1).

Only creating and setting the exception is suppressed.

Note that these functions may fail (return ``NULL`` or -1),

but no exception is set and no error information is available.

Slight rephrasing to be a little less ambiguous, though I'm not totally committed to that wording - you might have something better. There are a few other places this phrase appears below

With additional info on error handling, it makes sense to only have this in one place.

zooba · 2026-03-16T20:35:06Z

Modules/_testmultiphase.c

+    PyObject *m = PyType_GetModuleByDef(Py_TYPE(self), &def_nonmodule);
    assert(PyErr_Occurred());
+    assert(m == NULL);
    return NULL;


Returning m is probably the easiest way to avoid those warnings, and to avoid an actual refleak if the function passes but assertions are disabled.

encukou requested review from a team, ZeroIntensity, ericsnowcurrently and markshannon as code owners March 13, 2026 15:48

bedevere-app bot added the awaiting core review label Mar 13, 2026

bedevere-app bot mentioned this pull request Mar 13, 2026

Add _DuringGC functions for tp_traverse #145921

Open

Exclude PyObject_GetItemData_DuringGC from limited ABI

01cd8f7

zooba reviewed Mar 16, 2026

View reviewed changes

encukou added 3 commits March 17, 2026 11:16

Fix typo in link

a94159a

Move common info to a common section.

f5a0b07

return m

6730065

	:ref:`separate section <durniggc-functions>` below.
	:ref:`separate section <duringgc-functions>` below.

		Note that these functions may fail (return ``NULL`` or -1).
		Only creating and setting the exception is suppressed.

Uh oh!

Conversation

encukou commented Mar 13, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zooba left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

encukou commented Mar 13, 2026 •

edited by github-actions bot

Loading