Update docs and tests

Author: brandtbucher

Doc/library/gc.rst

@@ -110,13 +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;
+
    * ``duration`` is the total time in seconds spent in collections for this
      generation.
 
    .. versionadded:: 3.4
 
    .. versionchanged:: next
-      Add ``duration``.
+      Add ``duration`` and ``visited``.
 
 
 .. function:: set_threshold(threshold0, [threshold1, [threshold2]])
@@ -319,6 +322,9 @@ 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.
+
       "duration": When *phase* is "stop", the time in seconds spent in the
       collection.
 
@@ -335,7 +341,7 @@ values but should not rebind them):
    .. versionadded:: 3.3
 
    .. versionchanged:: next
-      Add "duration".
+      Add "duration" and "visited".
 
 
 The following constants are provided for use with :func:`set_debug`:

Lib/test/test_gc.py

@@ -846,11 +846,14 @@ def test_get_stats(self):
         self.assertEqual(len(stats), 3)
         for st in stats:
             self.assertIsInstance(st, dict)
-            self.assertEqual(set(st),
-                             {"collected", "collections", "uncollectable", "duration"})
+            self.assertEqual(
+                set(st),
+                {"collected", "collections", "uncollectable", "visited", "duration"}
+            )
             self.assertGreaterEqual(st["collected"], 0)
             self.assertGreaterEqual(st["collections"], 0)
             self.assertGreaterEqual(st["uncollectable"], 0)
+            self.assertGreaterEqual(st["visited"], 0)
             self.assertGreaterEqual(st["duration"], 0)
         # Check that collection counts are incremented correctly
         if gc.isenabled():
@@ -865,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"]:
+        for stat in ["collected", "uncollectable", "visited"]:
             self.assertGreaterEqual(new[0][stat], old[0][stat])
             self.assertEqual(new[1][stat], old[1][stat])
             self.assertEqual(new[2][stat], old[2][stat])
@@ -877,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"]:
+        for stat in ["collected", "uncollectable", "visited"]:
             self.assertEqual(new[0][stat], old[0][stat])
             self.assertEqual(new[1][stat], old[1][stat])
             self.assertGreaterEqual(new[2][stat], old[2][stat])
@@ -1316,6 +1319,7 @@ def test_collect(self):
             self.assertIn("generation", info)
             self.assertIn("collected", info)
             self.assertIn("uncollectable", info)
+            self.assertIn("visited", info)
             self.assertIn("duration", info)
 
     def test_collect_generation(self):

Python/gc.c

@@ -1759,7 +1759,7 @@ gc_collect_region(PyThreadState *tstate,
     assert(!_PyErr_Occurred(tstate));
 
     gc_list_init(&unreachable);
-    stats->visited += deduce_unreachable(from, &unreachable);
+    stats->visited = deduce_unreachable(from, &unreachable);
     validate_consistent_old_space(from);
     untrack_tuples(from);