gh-159437: Skip unnecessary late weakref cleanup

Count the stable unreachable set while preparing callbacks and retain a conservative cleanup flag. Reuse the count only when late weakref clearing has no work, and force fresh cleanup and counting after resurrection analysis.

Add a regression for a callback-free weakref observed when clearing a young cycle releases an older finalizer.

Author: mfalco-oai

Lib/test/test_gc.py

@@ -1196,6 +1196,36 @@ def getstats():
 
         gc.enable()
 
+    @requires_gil_enabled("tests the generation-list collector")
+    def test_callback_free_weakref_clear_without_pending_callbacks(self):
+        """Clear callback-free weakrefs before tp_clear can expose garbage."""
+        was_enabled = gc.isenabled()
+        gc.disable()
+        self.addCleanup(gc.enable if was_enabled else gc.disable)
+        self.addCleanup(gc.collect)
+        observed = []
+        self.addCleanup(observed.clear)
+
+        class Observer:
+            """Inspect a young target when its clearing releases this object."""
+
+            def __del__(self):
+                """Record whether the weakref still exposes the target."""
+                observed.append(reference())
+
+        observer = Observer()
+        gc.collect()
+        # The older observer does not open the callback path for generation 0.
+        # Clearing the target releases it, so the weakref must already be dead.
+        target = C1055820(0)
+        target.observer = observer
+        reference = weakref.ref(target)
+        del observer, target
+
+        self.assertEqual(gc.collect(0), 1)
+        self.assertEqual(observed, [None])
+        self.assertIsNone(reference())
+
     @unittest.skipIf(ContainerNoGC is None,
                      'requires ContainerNoGC extension type')
     def test_trash_weakref_clear(self):

Misc/NEWS.d/next/Core_and_Builtins/2026-10-16-00-00-00.gh-issue-159437.weakrf.rst

@@ -0,0 +1 @@
+Garbage collection in builds with the GIL now reuses the initial garbage count and skips late weakref cleanup when no weakrefs need clearing and the unreachable set remains valid.

Python/gc.c

@@ -798,16 +798,22 @@ move_legacy_finalizer_reachable(PyGC_Head *finalizers)
  * Arguments:
  * - `unreachable`: normalized collecting list to inspect.
  * - `wrcb_to_call`: initialized list receiving weakrefs whose callbacks are safe to invoke.
+ * - `collectable_count_out`: receives the number of objects in `unreachable`.
+ * - `needs_weakref_cleanup_out`: receives whether garbage weakrefs or remaining incoming weakrefs may need cleanup.
  *
  * Return whether any finalizer is pending or a weakref callback is queued.
- * This function does not invoke callbacks.
+ * This function does not invoke callbacks. The count and cleanup decision
+ * remain valid only while the unreachable set and its weakrefs cannot change.
  */
 Py_NO_INLINE static bool
-prepare_callbacks(PyGC_Head *unreachable, PyGC_Head *wrcb_to_call)
+prepare_callbacks(PyGC_Head *unreachable, PyGC_Head *wrcb_to_call,
+                  Py_ssize_t *collectable_count_out, bool *needs_weakref_cleanup_out)
 {
     PyGC_Head *gc;
     PyGC_Head *next;
+    Py_ssize_t count = 0;
     bool has_pending_finalizer = false;
+    bool needs_weakref_cleanup = false;
 
     /* Find all weakrefs with callbacks and move into `wrcb_to_call` if the
      * callback needs to be invoked. We make another pass over wrcb_to_call,
@@ -818,11 +824,16 @@ prepare_callbacks(PyGC_Head *unreachable, PyGC_Head *wrcb_to_call)
 
         PyObject *op = FROM_GC(gc);
         PyTypeObject *type = Py_TYPE(op);
+        count++;
         if (type->tp_finalize != NULL && !has_pending_finalizer) {
             has_pending_finalizer = !_PyGC_FINALIZED(op);
         }
         next = GC_NEXT(gc);
 
+        // Garbage weakrefs need clearing even if their referents are outside
+        // this collection (bpo-38006).
+        needs_weakref_cleanup |= PyWeakref_Check(op);
+
         if (! _PyType_SUPPORTS_WEAKREFS(type)) {
             continue;
         }
@@ -900,8 +911,12 @@ prepare_callbacks(PyGC_Head *unreachable, PyGC_Head *wrcb_to_call)
             _PyObject_ASSERT((PyObject *)wr, wrasgc != next);
             gc_list_move(wrasgc, wrcb_to_call);
         }
+        // Callback-free weakrefs remain linked until finalization.
+        needs_weakref_cleanup |= *wrlist != NULL;
     }
 
+    *collectable_count_out = count;
+    *needs_weakref_cleanup_out = needs_weakref_cleanup;
     return has_pending_finalizer || !gc_list_is_empty(wrcb_to_call);
 }
 
@@ -1632,7 +1647,9 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
 
     PyGC_Head wrcb_to_call;
     gc_list_init(&wrcb_to_call);
-    bool has_pending_callbacks = prepare_callbacks(&unreachable, &wrcb_to_call);
+    Py_ssize_t collectable_count;
+    bool needs_weakref_cleanup;
+    bool has_pending_callbacks = prepare_callbacks(&unreachable, &wrcb_to_call, &collectable_count, &needs_weakref_cleanup);
     has_pending_callbacks |= needs_resurrection_check;
 
     PyGC_Head final_unreachable;
@@ -1641,6 +1658,9 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
         bool resurrection_checked = handle_callbacks(tstate, collectable, &final_unreachable, old, &wrcb_to_call, &stats.collected, needs_resurrection_check);
         if (resurrection_checked) {
             collectable = &final_unreachable;
+            // Python code may have changed the garbage set or created weakrefs.
+            // Refresh both cleanup and counting.
+            needs_weakref_cleanup = true;
         }
     }
     validate_list(old, collecting_clear_unreachable_clear);
@@ -1652,7 +1672,10 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
      * and create new weakrefs.  If those weakrefs were not cleared, they
      * could reveal unreachable objects.  Callbacks are not executed.
      */
-    stats.collected += clear_weakrefs(collectable);
+    if (needs_weakref_cleanup) {
+        collectable_count = clear_weakrefs(collectable);
+    }
+    stats.collected += collectable_count;
 
     /* Call tp_clear on objects in the collectable set.  This will cause
     * the reference cycles to be broken.  It may also cause some objects