Add a private API to defer automatic garbage collection

[pablogsal]

I would like to propose a private API that allows CPython internals to defer automatic garbage collection on the current thread without changing the interpreter-visible GC state.

Some CPython internals build large object graphs in a burst, where a collection triggered halfway through cannot reclaim anything from that operation and only traverses a half-built graph. Using PyGC_Disable() for this changes interpreter-wide state. Saving and restoring that state is racy in the free-threaded build, and it can also be observed or changed by user code in the GIL build.

What we want is something approximately like:

_PyGC_DeferAutomaticCollection(tstate);
/* Build a large object graph. */
_PyGC_ResumeAutomaticCollection(tstate);

This would be a private CPython API. It should be per-thread and nestable, keep allocation counters running, leave gc.isenabled() unchanged, and defer only automatic collection. Leaving the outermost scope would schedule a collection if one became due.

I think there are many possible cases in the stdlib and core that can benefit from this, and we currently do not have a safe tool for them. This can be implemented with a small nesting counter in _PyThreadStateImpl, checked by the allocation paths and _Py_RunGC(). This would allow these optimizations without changing user-visible GC state or introducing cross-thread races.

[pablogsal]

CC @nascheme

[maurycy]

Can we actually guarantee that no other thread will collect, in a free-threading build? Another approach, in the context of #153583, could be a simple counter (atomic, and not per thread) in the GCState, and then: enabled && pause_count <= 0. This way we don't race with the user(land :-). I believe we have similar problem in other places, eg:

cpython/Modules/_posixsubprocess.c

Lines 1063 to 1067 in 1b9fe5c

	/* We need to call gc.disable() when we'll be calling preexec_fn */
	if (preexec_fn != Py_None) {
	need_to_reenable_gc = PyGC_Disable();
	}

FYI: https://learn.microsoft.com/en-us/dotnet/api/system.gc.trystartnogcregion?view=net-10.0

cc @sergey-miryanov

[pablogsal]

Yes, I think an interpreter atomic counter in GCState is the indeed better. Free threading will require some thinking for sure, we should check pause_count in gc_should_collect() and check it again after _PyEval_StopTheWorld(), before traversing the heaps. That second check should make the guarantee race-free: a thread either incremented the counter before being stopped, or it was stopped before entering the protected region. The existing collecting serialization prevents competing collectors.

Perhaps manual gc.collect() should ignore the counter, and leaving the outermost paused region should schedule an automatic collection if one became due. This is similar in spirit to TryStartNoGCRegion, but narrower because it only defers automatic collection.

[vstinner]

If the intent is to use it outside CPython code base, IMO an unstable API would be better than an internal API. (I would prefer to not add private APIs anymore.)

[nascheme]

This sounds like an okay idea to me. One question: should it also disable the counting of net new container objects? If the structure you are building is known to have no reference cycles, not counting the allocated containers would make sense. However, the free-threaded GC does more than just break reference cycles. So we need to be careful not to defer too long. If you keep counting then a GC collection would likely happen soon after _PyGC_ResumeAutomaticCollection(), i.e. when the next container object is allocated/tracked. I'd safe continuing to count is the safer and better design.

I don't have a strong opinion on internal vs unstable. Feels like internal is safer to add (since we can remove again on a whim) but perhaps it doesn't take much extra design/consideration to make it "unstable". This does seem like an API some extensions that are hyper-focused on performance might use.

[maurycy]

leaving the outermost paused region should schedule an automatic collection if one became due

If you keep counting then a GC collection would likely happen soon after _PyGC_ResumeAutomaticCollection(), i.e. when the next container object is allocated/tracked.

This may need measuring but my hunch is that there's a risk of nullifying the #153583 performance gains if we collected immediately, especially if the returned objects were still around and if we plan on pausing in more places. I'd just keep counting but avoid scheduling an automatic collection. This would also sparse us a special-case trigger.

[sergey-miryanov]

It might also be worth adding a context manager that pauses the GC.

[sergey-miryanov]

Here's an example where pausing the GC improves performance: #139951. Any GC calls triggered while building the dict merely promote objects between generations without doing any meaningful work.