Update InternalDocs/garbge_collector.md

Co-Authored-By: Zanie Blue <contact@zanie.dev>

Author: sergey-miryanov

InternalDocs/garbage_collector.md

@@ -107,7 +107,7 @@ As is explained later in the
 [Optimization: reusing fields to save memory](#optimization-reusing-fields-to-save-memory)
 section, these two extra fields are normally used to keep doubly linked lists of all the
 objects tracked by the garbage collector (these lists are the GC generations, more on
-that in the [Optimization: incremental collection](#Optimization-incremental-collection) section), but
+that in the [Optimization: generations](#Optimization-generations) section), but
 they are also reused to fulfill other purposes when the full doubly linked list
 structure is not needed as a memory optimization.
 
@@ -199,22 +199,22 @@ unreachable:
 
 ```pycon
 >>> import gc
->>> 
+>>>
 >>> class Link:
 ...    def __init__(self, next_link=None):
 ...        self.next_link = next_link
-...  
+...
 >>> link_3 = Link()
 >>> link_2 = Link(link_3)
 >>> link_1 = Link(link_2)
 >>> link_3.next_link = link_1
 >>> A = link_1
 >>> del link_1, link_2, link_3
->>> 
+>>>
 >>> link_4 = Link()
 >>> link_4.next_link = link_4
 >>> del link_4
->>> 
+>>>
 >>> # Collect the unreachable Link object (and its .__dict__ dict).
 >>> gc.collect()
 2
@@ -350,88 +350,42 @@ follows these steps in order:
    the reference counts fall to 0, triggering the destruction of all unreachable
    objects.
 
-Optimization: incremental collection
-====================================
+Optimization: generations
+=========================
 
-In order to bound the length of each garbage collection pause, the GC implementation
-for the default build uses incremental collection with two generations.
+In order to limit the time each garbage collection takes, the GC
+implementation for the default build uses a popular optimization:
+generations.
 
 Generational garbage collection takes advantage of what is known as the weak
 generational hypothesis: Most objects die young.
 This has proven to be very close to the reality of many Python
 programs as many temporary objects are created and destroyed very quickly.
 
 To take advantage of this fact, all container objects are segregated into
-two generations: young and old. Every new object starts in the young generation.
-Each garbage collection scans the entire young generation and part of the old generation.
-
-The time taken to scan the young generation can be controlled by controlling its
-size, but the size of the old generation cannot be controlled.
-In order to keep pause times down, scanning of the old generation of the heap
-occurs in increments.
-
-To keep track of what has been scanned, the old generation contains two lists:
-
-* Those objects that have not yet been scanned, referred to as the `pending` list.
-* Those objects that have been scanned, referred to as the `visited` list.
-
-To detect and collect all unreachable objects in the heap, the garbage collector
-must scan the whole heap. This whole heap scan is called a full scavenge.
-
-Increments
-----------
-
-Each full scavenge is performed in a series of increments.
-For each full scavenge, the combined increments will cover the whole heap.
-
-Each increment is made up of:
-
-* The young generation
-* The old generation's least recently scanned objects
-* All objects reachable from those objects that have not yet been scanned this full scavenge
-
-The surviving objects (those that are not collected) are moved to the back of the
-`visited` list in the old generation.
-
-When a full scavenge starts, no objects in the heap are considered to have been scanned,
-so all objects in the old generation must be in the `pending` space.
-When all objects in the heap have been scanned a cycle ends, and all objects are moved
-to the `pending` list again. To avoid having to traverse the entire list, which list is
-`pending` and which is `visited` is determined by a field in the `GCState` struct.
-The `visited` and `pending` lists can be swapped by toggling this bit.
-
-Correctness
------------
-
-The [algorithm for identifying cycles](#Identifying-reference-cycles) will find all
-unreachable cycles in a list of objects, but will not find any cycles that are
-even partly outside of that list.
-Therefore, to be guaranteed that a full scavenge will find all unreachable cycles,
-each cycle must be fully contained within a single increment.
-
-To make sure that no partial cycles are included in the increment we perform a
-[transitive closure](https://en.wikipedia.org/wiki/Transitive_closure)
-over reachable, unscanned objects from the initial increment.
-Since the transitive closure of objects reachable from an object must be a (non-strict)
-superset of any unreachable cycle including that object, we are guaranteed that a
-transitive closure cannot contain any partial cycles.
-We can exclude scanned objects, as they must have been reachable when scanned.
-If a scanned object becomes part of an unreachable cycle after being scanned, it will
-not be collected at this time, but it will be collected in the next full scavenge.
+three spaces/generations. Every new
+object starts in the first generation (generation 0). The previous algorithm is
+executed only over the objects of a particular generation and if an object
+survives a collection of its generation it will be moved to the next one
+(generation 1), where it will be surveyed for collection less often. If
+the same object survives another GC round in this new generation (generation 1)
+it will be moved to the last generation (generation 2) where it will be
+surveyed the least often.
 
 > [!NOTE]
 > The GC implementation for the free-threaded build does not use incremental collection.
 > Every collection operates on the entire heap.
 
+
 In order to decide when to run, the collector keeps track of the number of object
 allocations and deallocations since the last collection. When the number of
 allocations minus the number of deallocations exceeds `threshold0`,
-collection starts. `threshold1` determines the fraction of the old
-collection that is included in the increment.
-The fraction is inversely proportional to `threshold1`,
-as historically a larger `threshold1` meant that old generation
-collections were performed less frequently.
-`threshold2` is ignored.
+collection starts. Initially only generation 0 is examined. If generation 0 has
+been examined more than `threshold_1` times since generation 1 has been
+examined, then generation 1 is examined as well. With generation 2,
+things are a bit more complicated; see
+[Collecting the oldest generation](#Collecting-the-oldest-generation) for
+more information.
 
 These thresholds can be examined using the
 [`gc.get_threshold()`](https://docs.python.org/3/library/gc.html#gc.get_threshold)
@@ -440,7 +394,7 @@ function:
 ```pycon
 >>> import gc
 >>> gc.get_threshold()
-(700, 10, 10)
+(2000, 10, 10)
 ```
 
 The content of these generations can be examined using the
@@ -453,84 +407,61 @@ specifically in a generation by calling `gc.collect(generation=NUM)`.
 ...     pass
 ...
 >>> # Move everything to the old generation so it's easier to inspect
->>> # the young generation.
+>>> # the younger generation.
 >>> gc.collect()
 0
 >>> # Create a reference cycle.
 >>> x = MyObj()
 >>> x.self = x
->>> 
->>> # Initially the object is in the young generation.
+>>>
+>>> # Initially the object is in the youngest generation.
 >>> gc.get_objects(generation=0)
 [..., <__main__.MyObj object at 0x7fbcc12a3400>, ...]
->>> 
+>>>
 >>> # After a collection of the youngest generation the object
->>> # moves to the old generation.
+>>> # moves to the next generation.
 >>> gc.collect(generation=0)
 0
 >>> gc.get_objects(generation=0)
 []
 >>> gc.get_objects(generation=1)
-[]
->>> gc.get_objects(generation=2)
 [..., <__main__.MyObj object at 0x7fbcc12a3400>, ...]
 ```
 
+Collecting the oldest generation
+--------------------------------
+
+In addition to the various configurable thresholds, the GC only triggers a full
+collection of the oldest generation if the ratio `long_lived_pending / long_lived_total`
+is above a given value (hardwired to 25%). The reason is that, while "non-full"
+collections (that is, collections of the young and middle generations) will always
+examine roughly the same number of objects (determined by the aforementioned
+thresholds) the cost of a full collection is proportional to the total
+number of long-lived objects, which is virtually unbounded.  Indeed, it has
+been remarked that doing a full collection every <constant number> of object
+creations entails a dramatic performance degradation in workloads which consist
+of creating and storing lots of long-lived objects (for example, building a large list
+of GC-tracked objects would show quadratic performance, instead of linear as
+expected). Using the above ratio, instead, yields amortized linear performance
+in the total number of objects (the effect of which can be summarized thusly:
+"each full garbage collection is more and more costly as the number of objects
+grows, but we do fewer and fewer of them").
+
 
 Optimization: excluding reachable objects
 =========================================
 
 An object cannot be garbage if it can be reached. To avoid having to identify
-reference cycles across the whole heap, we can reduce the amount of work done
-considerably by first identifying objects reachable from objects known to be
-alive.  These objects are excluded from the normal cyclic detection process.
-
-The default and free-threaded build both implement this optimization but in
-slightly different ways.
-
-Finding reachable objects for the default build GC
---------------------------------------------------
-
-This works by first moving most reachable objects to the `visited` space.
-Empirically, most reachable objects can be reached from a small set of global
-objects and local variables. This step does much less work per object, so
-reduces the time spent performing garbage collection by at least half.
-
-> [!NOTE]
-> Objects that are not determined to be reachable by this pass are not necessarily
-> unreachable. We still need to perform the main algorithm to determine which objects
-> are actually unreachable.
-We use the same technique of forming a transitive closure as the incremental
-collector does to find reachable objects, seeding the list with some global
-objects and the currently executing frames.
-
-This phase moves objects to the `visited` space, as follows:
-
-1. All objects directly referred to by any builtin class, the `sys` module, the `builtins`
-module and all objects directly referred to from stack frames are added to a working
-set of reachable objects.
-2. Until this working set is empty:
-   1. Pop an object from the set and move it to the `visited` space
-   2. For each object directly reachable from that object:
-      * If it is not already in `visited` space and it is a GC object,
-        add it to the working set
-
-
-Before each increment of collection is performed, the stacks are scanned
-to check for any new stack frames that have been created since the last
-increment. All objects directly referred to from those stack frames are
-added to the working set.
-Then the above algorithm is repeated, starting from step 2.
-
+reference cycles across the whole heap, the free-threaded build first identifies
+objects reachable from objects known to be alive. These objects are excluded
+from the normal cyclic detection process.
 
 Finding reachable objects for the free-threaded GC
 --------------------------------------------------
 
 Within the `gc_free_threading.c` implementation, this is known as the "mark
-alive" pass or phase.  It is similar in concept to what is done for the default
-build GC.  Rather than moving objects between double-linked lists, the
-free-threaded GC uses a flag in `ob_gc_bits` to track if an object is
-found to be definitely alive (not garbage).
+alive" pass or phase. The free-threaded GC uses a flag in `ob_gc_bits` to track
+if an object is found to be definitely alive (not garbage).
 
 To find objects reachable from known alive objects, known as the "roots", the
 `gc_mark_alive_from_roots()` function is used.  Root objects include