gh-159437: Combine GC reference passes for full collections

Author: mfalco-oai

Include/internal/pycore_pystate.h

@@ -62,6 +62,18 @@ _Py_IsMainInterpreter(PyInterpreterState *interp)
     return (interp == _PyInterpreterState_Main());
 }
 
+/* Return whether tracked objects may belong to another interpreter lifetime.
+ *
+ * Result:
+ * - false before any subinterpreter reservation or runtime reinitialization.
+ * - true after either event, including across Py_Finalize()/Py_Initialize().
+ *
+ * Extension-owned objects may outlive the interpreter whose GC list held them,
+ * so callers must not assume every tracked object belongs to the current
+ * runtime when this returns true.
+ */
+PyAPI_FUNC(bool) _PyInterpreterState_MayHaveForeignGcObjects(void);
+
 extern int _Py_IsMainInterpreterFinalizing(PyInterpreterState *interp);
 
 // Export for _interpreters module.

Lib/test/test_gc.py

@@ -1422,6 +1422,54 @@ def test_heap_size(self):
         del l
         self.assertEqual(count, _testinternalcapi.get_tracked_heap_size())
 
+    @requires_gil_enabled("tests fused full-collection reference accounting")
+    @unittest.skipIf(_testinternalcapi is None, "requires _testinternalcapi")
+    def test_full_collection_preserves_refs_while_untracking_immortal(self):
+        """Untracking an immortal preserves adjacent candidates and heap accounting."""
+        import_module("ctypes")
+        source = textwrap.dedent("""
+            import ctypes
+            import gc
+            import _testinternalcapi
+
+            set_immortal = ctypes.pythonapi._Py_SetImmortal
+            set_immortal.argtypes = [ctypes.py_object]
+            set_immortal.restype = None
+            track = ctypes.pythonapi.PyObject_GC_Track
+            track.argtypes = [ctypes.py_object]
+            track.restype = None
+            may_have_foreign_gc_objects = ctypes.pythonapi._PyInterpreterState_MayHaveForeignGcObjects
+            may_have_foreign_gc_objects.argtypes = []
+            may_have_foreign_gc_objects.restype = ctypes.c_bool
+
+            gc.disable()
+            gc.collect(2)
+            candidates_before = gc.get_stats()[2]["candidates"]
+            parent = []
+            middle = []
+            set_immortal(middle)
+            track(middle)
+            child = []
+            parent.append(child)
+            child.append(parent)
+
+            # Traversing parent initializes child before the intervening
+            # immortal is removed from the forward chain.
+            del parent, child
+            assert gc.get_freeze_count() == 0
+            assert not may_have_foreign_gc_objects()
+            # Every tracked object except middle is a candidate here.
+            expected_candidates = _testinternalcapi.get_tracked_heap_size() - 1
+            assert gc.collect(2) == 2
+            assert not gc.is_tracked(middle)
+            assert gc.get_stats()[2]["candidates"] - candidates_before == expected_candidates
+
+            # get_objects() omits the result list itself.
+            objects = gc.get_objects()
+            assert _testinternalcapi.get_tracked_heap_size() == len(objects) + 1
+        """)
+        assert_python_ok("-c", source)
+
 
 class GCCallbackTests(unittest.TestCase):
     def setUp(self):

Lib/test/test_gdb/test_backtrace.py

@@ -97,15 +97,21 @@ def test_gc(self):
                'def bar():\n'
                '    foo()\n'
                'bar()\n')
+        # Full GIL collections may skip update_refs(). Stop at a visible phase
+        # after the collector marks collection active.
+        if support.Py_GIL_DISABLED:
+            gc_breakpoint = 'update_refs'
+        else:
+            gc_breakpoint = 'prepare_callbacks'
         # Verify with "py-bt":
         gdb_output = self.get_stack_trace(cmd,
-                                          cmds_after_breakpoint=['break update_refs', 'continue', 'py-bt'],
+                                          cmds_after_breakpoint=[f'break {gc_breakpoint}', 'continue', 'py-bt'],
                                           )
         self.assertIn('Garbage-collecting', gdb_output)
 
         # Verify with "py-bt-full":
         gdb_output = self.get_stack_trace(cmd,
-                                          cmds_after_breakpoint=['break update_refs', 'continue', 'py-bt-full'],
+                                          cmds_after_breakpoint=[f'break {gc_breakpoint}', 'continue', 'py-bt-full'],
                                           )
         self.assertIn('Garbage-collecting', gdb_output)
 

Misc/NEWS.d/next/Core_and_Builtins/2026-10-16-01-07-10.gh-issue-159437.reffus.rst

@@ -0,0 +1 @@
+With the GIL enabled, combine reference initialization and subtraction in the initial pass of a full collection when the permanent generation is empty and tracked objects cannot belong to another interpreter lifetime.

Programs/_testembed.c

@@ -191,6 +191,10 @@ static int test_repeated_init_and_subinterpreters(void)
     for (int i=1; i <= INIT_LOOPS; i++) {
         printf("--- Pass %d ---\n", i);
         _testembed_initialize();
+        if (i > 1 && !_PyInterpreterState_MayHaveForeignGcObjects()) {
+            error("foreign GC object risk was reset");
+            return 1;
+        }
         mainstate = PyThreadState_Get();
 
         PyEval_ReleaseThread(mainstate);
@@ -204,6 +208,10 @@ static int test_repeated_init_and_subinterpreters(void)
             print_subinterp();
             Py_EndInterpreter(substate);
         }
+        if (!_PyInterpreterState_MayHaveForeignGcObjects()) {
+            error("subinterpreter lifetime did not record foreign GC object risk");
+            return 1;
+        }
 
         PyThreadState_Swap(mainstate);
         print_subinterp();
@@ -279,6 +287,14 @@ static int test_repeated_simple_init(void)
         fflush(stderr);
 
         _testembed_initialize();
+        if (i == 1 && _PyInterpreterState_MayHaveForeignGcObjects()) {
+            error("initial main interpreter may have foreign GC objects");
+            return 1;
+        }
+        if (i > 1 && !_PyInterpreterState_MayHaveForeignGcObjects()) {
+            error("runtime reinitialization lost foreign GC object risk");
+            return 1;
+        }
         Py_Finalize();
         printf("Finalized\n"); // Give test_embed some output to check
     }

Python/gc.c

@@ -29,9 +29,8 @@ typedef struct _gc_runtime_state GCState;
 #define GC_NEXT _PyGCHead_NEXT
 #define GC_PREV _PyGCHead_PREV
 
-// update_refs() set this bit for all objects in current generation.
-// subtract_refs() and move_unreachable() uses this to distinguish
-// visited object is in GCing or not.
+// Reference initialization marks objects in the current generation.
+// Reference subtraction and reachability use this bit to recognize them.
 //
 // move_unreachable() removes this flag from reachable objects.
 // Only unreachable objects have this flag.
@@ -168,15 +167,14 @@ During a collection, _gc_prev is temporary used for gc_refs, and the gc list
 is singly linked until _gc_prev is restored.
 
 gc_refs
-    At the start of a collection, update_refs() copies the true refcount
-    to gc_refs, for each object in the generation being collected.
-    subtract_refs() then adjusts gc_refs so that it equals the number of
-    times an object is referenced directly from outside the generation
-    being collected.
+    The true refcount is copied to gc_refs and reduced by references from
+    objects in the generation being collected. The remaining count is the
+    number of direct references from outside that generation. Full collections
+    may initialize and subtract these counts in one traversal.
 
 PREV_MASK_COLLECTING
-    Objects in generation being collected are marked PREV_MASK_COLLECTING in
-    update_refs().
+    Reference initialization marks objects in the generation being collected
+    with PREV_MASK_COLLECTING.
 
 
 _gc_next values
@@ -456,14 +454,52 @@ visit_decref(PyObject *op, void *parent)
     return 0;
 }
 
+/* Subtract a GC reference, initializing and marking the referent on first visit.
+ *
+ * This visitor is used only when every tracked mortal object it may reach
+ * belongs to the collection. Non-GC, untracked, and immortal referents remain
+ * unchanged.
+ *
+ * Arguments:
+ * - `op`: the object referenced by the traversed parent.
+ * - `parent`: the traversed owner used by debug reference validation.
+ *
+ * Return zero, as required by traversal callbacks.
+ */
+static int
+gc_decref_and_mark_collecting(PyObject *op, void *parent)
+{
+    OBJECT_STAT_INC(object_visits);
+    _PyObject_ASSERT(_PyObject_CAST(parent), !_PyObject_IsFreed(op));
+
+    if (!_PyObject_IS_GC(op)) {
+        return 0;
+    }
+
+    PyGC_Head *gc = AS_GC(op);
+    if (gc_is_collecting(gc)) {
+        gc_decref(gc);
+        return 0;
+    }
+
+    if (!_PyObject_GC_IS_TRACKED(op) || _Py_IsImmortal(op)) {
+        return 0;
+    }
+    Py_ssize_t refs = Py_REFCNT(op);
+    _PyObject_ASSERT(op, refs != 0);
+    gc_reset_refs(gc, refs - 1);
+    return 0;
+}
+
 int
 _PyGC_VisitStackRef(_PyStackRef *ref, visitproc visit, void *arg)
 {
     // This is a bit tricky! We want to ignore stackrefs with embedded
     // refcounts when computing the incoming references, but otherwise treat
     // them like normal.
     assert(!PyStackRef_IsTaggedInt(*ref));
-    if (!PyStackRef_RefcountOnObject(*ref) && (visit == visit_decref)) {
+    if (!PyStackRef_RefcountOnObject(*ref) &&
+        (visit == visit_decref || visit == gc_decref_and_mark_collecting)) {
         return 0;
     }
     Py_VISIT(PyStackRef_AsPyObjectBorrow(*ref));
@@ -501,6 +537,60 @@ subtract_refs(PyGC_Head *containers)
     }
 }
 
+/* Initialize and subtract references in one traversal of all ordinary generations.
+ *
+ * Mortal candidates retain adjusted gc_refs. Dynamic immortal candidates become
+ * untracked without changing other candidates' temporary counts.
+ *
+ * Prerequisites:
+ * - This is the initial pass of a full collection, not a resurrection recheck.
+ * - `containers` is a valid list containing all ordinary generations with no masks set.
+ * - The permanent generation is empty.
+ * - `_PyInterpreterState_MayHaveForeignGcObjects()` is false.
+ *
+ * Arguments:
+ * - `containers`: tracked objects belonging to the initial main interpreter.
+ *
+ * Return the number of mortal collection candidates.
+ */
+static Py_ssize_t
+update_and_subtract_refs(PyGC_Head *containers)
+{
+    Py_ssize_t candidates = 0;
+    PyGC_Head *previous = containers;
+    PyGC_Head *gc = GC_NEXT(containers);
+
+    while (gc != containers) {
+        PyGC_Head *next = GC_NEXT(gc);
+        PyObject *op = FROM_GC(gc);
+
+        if (!gc_is_collecting(gc)) {
+            if (_Py_IsImmortal(op)) {
+                assert(!_Py_IsStaticImmortal(op));
+                // The next node may already hold gc_refs instead of a predecessor,
+                // so ordinary untracking would corrupt its count.
+                _PyGCHead_SET_NEXT(previous, next);
+                gc->_gc_prev &= _PyGC_PREV_MASK_FINALIZED;
+                gc->_gc_next = 0;
+                _PyInterpreterState_GET()->gc.heap_size--;
+                gc = next;
+                continue;
+            }
+            gc_reset_refs(gc, Py_REFCNT(op));
+            _PyObject_ASSERT(op, gc_get_refs(gc) != 0);
+        }
+
+        candidates++;
+        (void)Py_TYPE(op)->tp_traverse(op, gc_decref_and_mark_collecting, op);
+        previous = gc;
+        gc = next;
+    }
+
+    // The tail must remain valid until reachability restores predecessor links.
+    containers->_gc_prev = (uintptr_t)previous;
+    return candidates;
+}
+
 /* A traversal callback for move_unreachable. */
 static int
 visit_reachable(PyObject *op, void *arg)
@@ -1185,6 +1275,8 @@ show_stats_each_generations(GCState *gcstate)
 /* Deduce which objects among "base" are unreachable from outside the list
    and move them to 'unreachable'. The process consist in the following steps:
 
+The first two steps may be combined for the initial pass of a full collection.
+
 1. Copy all reference counts to a different field (gc_prev is used to hold
    this copy to save memory).
 2. Traverse all objects in "base" and visit all referred objects using
@@ -1204,22 +1296,39 @@ show_stats_each_generations(GCState *gcstate)
     * The "unreachable" list must be uninitialized (this function calls
       gc_list_init over 'unreachable').
 
+    * "full_collection_pass" means this is the initial pass over all ordinary generations.
+      Resurrection rechecks pass false even during a full collection.
+
+    * "reachable" must point to storage for the number of survivors that remain tracked.
+
+    * The return value is the number of mortal collection candidates.
+
 IMPORTANT: This function leaves 'unreachable' with the NEXT_MASK_UNREACHABLE
 flag set but it does not clear it to skip unnecessary iteration. Before the
 flag is cleared (for example, by using 'clear_unreachable_mask' function or
 by a call to 'move_legacy_finalizers'), the 'unreachable' list is not a normal
 list and we can not use most gc_list_* functions for it. */
 static inline Py_ssize_t
 deduce_unreachable(PyGC_Head *base, PyGC_Head *unreachable,
-                   Py_ssize_t *reachable) {
+                   bool full_collection_pass, Py_ssize_t *reachable) {
     validate_list(base, collecting_clear_unreachable_clear);
     /* Using ob_refcnt and gc_refs, calculate which objects in the
      * container set are reachable from outside the set (i.e., have a
      * refcount greater than 0 when all the references within the
      * set are taken into account).
      */
-    Py_ssize_t candidates = update_refs(base);  // gc_prev is used for gc_refs
-    subtract_refs(base);
+    // Lazy initialization can touch any tracked mortal referent. Use it only
+    // when all such objects belong to this initial full collection.
+    Py_ssize_t candidates;
+    if (full_collection_pass &&
+        gc_list_is_empty(&get_gc_state()->permanent_generation.head) &&
+        !_PyInterpreterState_MayHaveForeignGcObjects()) {
+        candidates = update_and_subtract_refs(base);
+    }
+    else {
+        candidates = update_refs(base);  // gc_prev is used for gc_refs
+        subtract_refs(base);
+    }
 
     /* Leave everything reachable from outside base in base, and move
      * everything else (in base) to unreachable.
@@ -1290,7 +1399,7 @@ handle_resurrected_objects(PyGC_Head *unreachable, PyGC_Head* still_unreachable,
     // removed so we can skip the expense of clearing the flag.
     PyGC_Head* resurrected = unreachable;
     Py_ssize_t reachable;
-    deduce_unreachable(resurrected, still_unreachable, &reachable);
+    deduce_unreachable(resurrected, still_unreachable, false, &reachable);
     clear_unreachable_mask(still_unreachable);
 
     // Move the resurrected objects to the old generation for future collection.
@@ -1597,7 +1706,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     validate_list(old, collecting_clear_unreachable_clear);
 
     Py_ssize_t reachable;
-    stats.candidates = deduce_unreachable(young, &unreachable, &reachable);
+    stats.candidates = deduce_unreachable(young, &unreachable, generation == NUM_GENERATIONS - 1, &reachable);
 
     /* Move reachable objects to next generation. */
     if (young != old) {

Python/pystate.c

@@ -309,6 +309,17 @@ _Py_COMP_DIAG_IGNORE_DEPR_DECLS
 static const _PyRuntimeState initial = _PyRuntimeState_INIT(_PyRuntime, "");
 _Py_COMP_DIAG_POP
 
+/* Monotonic guard for tracked objects that may outlive their interpreter.
+ * Kept outside _PyRuntime so reinitialization cannot clear it.
+ */
+static int may_have_foreign_gc_objects;
+
+bool
+_PyInterpreterState_MayHaveForeignGcObjects(void)
+{
+    return _Py_atomic_load_int_relaxed(&may_have_foreign_gc_objects) != 0;
+}
+
 #define LOCKS_INIT(runtime) \
     { \
         &(runtime)->interpreters.mutex, \
@@ -364,6 +375,7 @@ _PyRuntimeState_Init(_PyRuntimeState *runtime)
 
     if (runtime->_initialized) {
         // Py_Initialize() must be running again.
+        _Py_atomic_store_int_relaxed(&may_have_foreign_gc_objects, 1);
         // Reset to _PyRuntimeState_INIT.
         memcpy(runtime, &initial, sizeof(*runtime));
         // Preserve the cookie from the original runtime.
@@ -723,6 +735,8 @@ _PyInterpreterState_New(PyThreadState *tstate, PyInterpreterState **pinterp)
         assert(interpreters->main != NULL);
         assert(id != 0);
 
+        _Py_atomic_store_int_relaxed(&may_have_foreign_gc_objects, 1);
+
         interp = alloc_interpreter();
         if (interp == NULL) {
             status = _PyStatus_NO_MEMORY();