visited -> candidates

Author: brandtbucher

Doc/library/gc.rst

@@ -110,16 +110,16 @@ The :mod:`gc` module provides the following functions:
      to be uncollectable (and were therefore moved to the :data:`garbage`
      list) inside this generation;
 
-   * ``visited`` is the total number of unique objects visited during each
-     collection of this generation;
+   * ``candidates`` is the total number of objects in this generation which were
+     traversed and considered for collection;
 
    * ``duration`` is the total time in seconds spent in collections for this
      generation.
 
    .. versionadded:: 3.4
 
    .. versionchanged:: next
-      Add ``duration`` and ``visited``.
+      Add ``duration`` and ``candidates``.
 
 
 .. function:: set_threshold(threshold0, [threshold1, [threshold2]])
@@ -322,8 +322,8 @@ values but should not rebind them):
       "uncollectable": When *phase* is "stop", the number of objects
       that could not be collected and were put in :data:`garbage`.
 
-      "visited": When *phase* is "stop", the number of unique objects visited
-      during the collection.
+      "candidates": When *phase* is "stop", the total number of objects in this
+      generation which were traversed and considered for collection.
 
       "duration": When *phase* is "stop", the time in seconds spent in the
       collection.
@@ -341,7 +341,7 @@ values but should not rebind them):
    .. versionadded:: 3.3
 
    .. versionchanged:: next
-      Add "duration" and "visited".
+      Add "duration" and "candidates".
 
 
 The following constants are provided for use with :func:`set_debug`:

Include/internal/pycore_interp_structs.h

@@ -179,8 +179,8 @@ struct gc_collection_stats {
     Py_ssize_t collected;
     /* total number of uncollectable objects (put into gc.garbage) */
     Py_ssize_t uncollectable;
-    // Total number of objects visited:
-    Py_ssize_t visited;
+    // Total number of objects traversed and considered for collection:
+    Py_ssize_t candidates;
     // Duration of the collection in seconds:
     double duration;
 };
@@ -193,8 +193,8 @@ struct gc_generation_stats {
     Py_ssize_t collected;
     /* total number of uncollectable objects (put into gc.garbage) */
     Py_ssize_t uncollectable;
-    // Total number of objects visited:
-    Py_ssize_t visited;
+    // Total number of objects traversed and considered for collection:
+    Py_ssize_t candidates;
     // Duration of the collection in seconds:
     double duration;
 };

Lib/test/test_gc.py

@@ -848,12 +848,12 @@ def test_get_stats(self):
             self.assertIsInstance(st, dict)
             self.assertEqual(
                 set(st),
-                {"collected", "collections", "uncollectable", "visited", "duration"}
+                {"collected", "collections", "uncollectable", "candidates", "duration"}
             )
             self.assertGreaterEqual(st["collected"], 0)
             self.assertGreaterEqual(st["collections"], 0)
             self.assertGreaterEqual(st["uncollectable"], 0)
-            self.assertGreaterEqual(st["visited"], 0)
+            self.assertGreaterEqual(st["candidates"], 0)
             self.assertGreaterEqual(st["duration"], 0)
         # Check that collection counts are incremented correctly
         if gc.isenabled():
@@ -868,7 +868,7 @@ def test_get_stats(self):
         self.assertGreater(new[0]["duration"], old[0]["duration"])
         self.assertEqual(new[1]["duration"], old[1]["duration"])
         self.assertEqual(new[2]["duration"], old[2]["duration"])
-        for stat in ["collected", "uncollectable", "visited"]:
+        for stat in ["collected", "uncollectable", "candidates"]:
             self.assertGreaterEqual(new[0][stat], old[0][stat])
             self.assertEqual(new[1][stat], old[1][stat])
             self.assertEqual(new[2][stat], old[2][stat])
@@ -880,7 +880,7 @@ def test_get_stats(self):
         self.assertEqual(new[0]["duration"], old[0]["duration"])
         self.assertEqual(new[1]["duration"], old[1]["duration"])
         self.assertGreater(new[2]["duration"], old[2]["duration"])
-        for stat in ["collected", "uncollectable", "visited"]:
+        for stat in ["collected", "uncollectable", "candidates"]:
             self.assertEqual(new[0][stat], old[0][stat])
             self.assertEqual(new[1][stat], old[1][stat])
             self.assertGreaterEqual(new[2][stat], old[2][stat])
@@ -1319,7 +1319,7 @@ def test_collect(self):
             self.assertIn("generation", info)
             self.assertIn("collected", info)
             self.assertIn("uncollectable", info)
-            self.assertIn("visited", info)
+            self.assertIn("candidates", info)
             self.assertIn("duration", info)
 
     def test_collect_generation(self):

Misc/NEWS.d/next/Core_and_Builtins/2025-11-20-22-09-22.gh-issue-140638.f6btj0.rst

@@ -1,2 +1,2 @@
-Expose a ``"visited"`` stat in :func:`gc.get_stats` and
+Expose a ``"candidates"`` stat in :func:`gc.get_stats` and
 :data:`gc.callbacks`.

Modules/gcmodule.c

@@ -362,7 +362,7 @@ gc_get_stats_impl(PyObject *module)
                              "collections", st->collections,
                              "collected", st->collected,
                              "uncollectable", st->uncollectable,
-                             "visited", st->visited,
+                             "candidates", st->candidates,
                              "duration", st->duration
                             );
         if (dict == NULL)

Python/gc.c

@@ -488,7 +488,7 @@ update_refs(PyGC_Head *containers)
 {
     PyGC_Head *next;
     PyGC_Head *gc = GC_NEXT(containers);
-    Py_ssize_t visited = 0;
+    Py_ssize_t candidates = 0;
 
     while (gc != containers) {
         next = GC_NEXT(gc);
@@ -520,9 +520,9 @@ update_refs(PyGC_Head *containers)
          */
         _PyObject_ASSERT(op, gc_get_refs(gc) != 0);
         gc = next;
-        visited++;
+        candidates++;
     }
-    return visited;
+    return candidates;
 }
 
 /* A traversal callback for subtract_refs. */
@@ -1251,7 +1251,7 @@ deduce_unreachable(PyGC_Head *base, PyGC_Head *unreachable) {
      * refcount greater than 0 when all the references within the
      * set are taken into account).
      */
-    Py_ssize_t visited = update_refs(base);  // gc_prev is used for gc_refs
+    Py_ssize_t candidates = update_refs(base);  // gc_prev is used for gc_refs
     subtract_refs(base);
 
     /* Leave everything reachable from outside base in base, and move
@@ -1292,7 +1292,7 @@ deduce_unreachable(PyGC_Head *base, PyGC_Head *unreachable) {
     move_unreachable(base, unreachable);  // gc_prev is pointer again
     validate_list(base, collecting_clear_unreachable_clear);
     validate_list(unreachable, collecting_set_unreachable_set);
-    return visited;
+    return candidates;
 }
 
 /* Handle objects that may have resurrected after a call to 'finalize_garbage', moving
@@ -1368,9 +1368,9 @@ static void
 add_stats(GCState *gcstate, int gen, struct gc_collection_stats *stats)
 {
     gcstate->generation_stats[gen].duration += stats->duration;
-    gcstate->generation_stats[gen].visited += stats->visited;
     gcstate->generation_stats[gen].collected += stats->collected;
     gcstate->generation_stats[gen].uncollectable += stats->uncollectable;
+    gcstate->generation_stats[gen].candidates += stats->candidates;
     gcstate->generation_stats[gen].collections += 1;
 }
 
@@ -1759,7 +1759,7 @@ gc_collect_region(PyThreadState *tstate,
     assert(!_PyErr_Occurred(tstate));
 
     gc_list_init(&unreachable);
-    stats->visited = deduce_unreachable(from, &unreachable);
+    stats->candidates = deduce_unreachable(from, &unreachable);
     validate_consistent_old_space(from);
     untrack_tuples(from);
 
@@ -1853,7 +1853,7 @@ do_gc_callback(GCState *gcstate, const char *phase,
             "generation", generation,
             "collected", stats->collected,
             "uncollectable", stats->uncollectable,
-            "visited", stats->visited,
+            "candidates", stats->candidates,
             "duration", stats->duration);
         if (info == NULL) {
             PyErr_FormatUnraisable("Exception ignored while invoking gc callbacks");

Python/gc_free_threading.c

@@ -98,9 +98,9 @@ struct collection_state {
     // we can't collect objects with deferred references because we may not
     // see all references.
     int skip_deferred_objects;
-    Py_ssize_t visited;
     Py_ssize_t collected;
     Py_ssize_t uncollectable;
+    Py_ssize_t candidates;
     Py_ssize_t long_lived_total;
     struct worklist unreachable;
     struct worklist legacy_finalizers;
@@ -993,7 +993,7 @@ update_refs(const mi_heap_t *heap, const mi_heap_area_t *area,
         gc_clear_unreachable(op);
         return true;
     }
-    state->visited++;
+    state->candidates++;
 
     Py_ssize_t refcount = Py_REFCNT(op);
     if (_PyObject_HasDeferredRefcount(op)) {
@@ -1914,7 +1914,8 @@ handle_resurrected_objects(struct collection_state *state)
 static void
 invoke_gc_callback(PyThreadState *tstate, const char *phase,
                    int generation, Py_ssize_t collected,
-                   Py_ssize_t uncollectable, Py_ssize_t visited, double duration)
+                   Py_ssize_t uncollectable, Py_ssize_t candidates,
+                   double duration)
 {
     assert(!_PyErr_Occurred(tstate));
 
@@ -1932,7 +1933,7 @@ invoke_gc_callback(PyThreadState *tstate, const char *phase,
             "generation", generation,
             "collected", collected,
             "uncollectable", uncollectable,
-            "visited", visited,
+            "candidates", candidates,
             "duration", duration);
         if (info == NULL) {
             PyErr_FormatUnraisable("Exception ignored while "
@@ -2431,7 +2432,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     stats->collected += m;
     stats->uncollectable += n;
     stats->duration += duration;
-    stats->visited += state.visited;
+    stats->candidates += state.candidates;
 
     GC_STAT_ADD(generation, objects_collected, m);
 #ifdef Py_STATS
@@ -2450,7 +2451,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     }
 
     if (reason != _Py_GC_REASON_SHUTDOWN) {
-        invoke_gc_callback(tstate, "stop", generation, m, n, state.visited, duration);
+        invoke_gc_callback(tstate, "stop", generation, m, n, state.candidates, duration);
     }
 
     assert(!_PyErr_Occurred(tstate));