Typos in garbage collector docs

Documentation

Hello Python team!

Thanks so much for everything you do!
It seems there are a few typos and possibly unclear statements about memory usage in the InternalDocs garbage collector page (hopefully reporting it is useful to the team; I would have fixed the typos and the bad L2 cache size, e.g. where the Python team has written 6GB instead of MB, except that there appear also to be possible conceptual issues so I figured I should ask here.)

In describing the Python garbage collector, the Internal Docs at
https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L299 mention:

Pragmatically, it's important to note that no recursion is required by any of this,
and neither does it in any other way require additional memory proportional to the
number of objects, number of pointers, or the lengths of pointer chains.
Apart from O(1) storage for internal C needs, the objects themselves contain all the storage
the GC algorithms require.

This seems to be making the claim that the extra data stored on the objects (e.g. the doubly linked list bidirectional pointers used for GC) are the only O(n) storage used by the GC in any of its algorithms.

However, using a separate unbounded LIFO stack is mentioned:
https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L536

Second, there is a LIFO stack, of unlimited size. When object references are found using tp_traverse, they are enqueued in the buffer if it is not full, otherwise they are pushed to the stack.

(Note also the typo, "prefech" should be "prefetch" at https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L536 .)

But a LIFO stack of unbounded size (for any GC phase) does not seem consistent with the earlier claim (see above for link) that "Apart from O(1) storage for internal C needs, the objects themselves contain all the storage
the GC algorithms require"

(Also a breadth first search is mentioned
https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L294

This process is really a breadth first search over the object graph.
).

---

Next, the display of text seems to be broken for most markdown viewers (including Github's) at https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L451

Indeed, it has
been remarked that doing a full collection every 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").

where <constant number> doesn't display on GitHub's markdown viewer (so it is showing instead as "doing a full collection every of object creations"):

Indeed, it has been remarked that doing a full collection every 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).

See the following screenshots:

---

Finally, at:
https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L619

specifications for a machine used for testing are given:

AMD Ryzen 5 7600X, 64 GB RAM, 384 KB L1, 6 GB L2, 32 MB L3

where "6 GB L2" should be "6 MB L2" (off by ~1000x) ( compare to AMD's listing also https://web.archive.org/web/20260918004211/https://www.amd.com/en/products/processors/desktops/ryzen/7000-series/amd-ryzen-5-7600x.html )

---

Thanks so much!

Linked PRs

• gh-157733