Add notes about untrack_dicts() change.

Author: nascheme

InternalDocs/garbage_collector.md

@@ -702,6 +702,14 @@ tuples can be untracked. A tuple can be untracked if all of its contents are
 already not tracked. Tuples are examined for untracking in all garbage collection
 cycles.
 
+Dictionaries are always tracked from creation and are not untracked by the
+garbage collector. Earlier versions (up to 3.13) used lazy tracking: empty or
+atomic-only dicts were untracked on creation and re-tracked when a trackable
+value was inserted (via `MAINTAIN_TRACKING`), and full collections called
+`_PyDict_MaybeUntrack` to prune dicts whose values had become atomic. That
+machinery was removed in 3.14 (GH-127010) because the per-set-item cost of
+checking the tracking invariant outweighed the savings on full collections.
+
 The garbage collector module provides the Python function `is_tracked(obj)`, which returns
 the current tracking status of the object. Subsequent garbage collections may change the
 tracking status of the object.

Python/gc.c

@@ -1510,10 +1510,13 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
         gc_list_merge(young, old);
     }
     else {
-        /* We only un-track dicts in full collections, to avoid quadratic
-           dict build-up. See issue #14775.
-           Note: _PyDict_MaybeUntrack was removed in 3.14, so dict
-           untracking during GC is no longer done. */
+        // In Python <= 3.13, we called untrack_dicts(young) here to untrack
+        // atomic-only dicts (see issue #14775). Python 3.14 removed the lazy
+        // dict tracking machinery entirely (GH-127010) -- dicts are always
+        // tracked from creation and never untracked by GC. That way, we don't
+        // have to restore MAINTAIN_TRACKING across every PyDict_SetItem call
+        // site; the cost is slightly more work for full collections on dicts
+        // with only atomic values.
         gcstate->long_lived_pending = 0;
         gcstate->long_lived_total = gc_list_size(young);
     }