GH-157724: Fix typos in InternalDocs/garbage_collector.md (and in gc_free_threading.c comments, NO code changes)

[willy-b]

(no AI or LLMs were used in discovering the typos or preparing these changes)

• Typo fixes for a few items in InternalDocs/garbage_collector.md

  • At

    cpython/InternalDocs/garbage_collector.md

    Line 619 in 5539c2a

    - AMD Ryzen 5 7600X, 64 GB RAM, 384 KB L1, 6 GB L2, 32 MB L3, compiled with GCC 12.2.0

    "6 GB L2" should be "6 MB L2" (describing AMD Ryzen 5 7600X L2 cache size, see https://web.archive.org/web/20260918004211/https://www.amd.com/en/products/processors/desktops/ryzen/7000-series/amd-ryzen-5-7600x.html for reference)
  • At

    cpython/InternalDocs/garbage_collector.md

    Line 451 in 5539c2a

    been remarked that doing a full collection every <constant number> of object

    "<constant number>" should be "constant number" so that it is not hidden in markdown display
  • At

    cpython/InternalDocs/garbage_collector.md

    Line 536 in 5539c2a

    prefech buffer. Second, there is a LIFO stack, of unlimited size. When object

    "prefech" should be "prefetch" ; I also replaced "LIFO stack, of unlimited size" with "LIFO stack, limited only by available memory" (e.g.

    cpython/Python/gc_free_threading.c

    Line 1426 in a64b7ec

    gc_abort_mark_alive(interp, state, &mark_args);

    ,

    cpython/Python/gc_free_threading.c

    Lines 826 to 831 in a64b7ec

    	// We failed to allocate memory while doing the "mark alive" phase.
    	// In that case, free the memory used for marking state and make
    	// sure that no objects have the alive bit set.
    	_PyObjectStack_Clear(&args->stack);
    	if (args->spans.stack != NULL) {
    	PyMem_Free(args->spans.stack);

    , before

    cpython/Python/gc_free_threading.c

    Line 2116 in a64b7ec

    PyErr_NoMemory();

    )

• Typo fixes for 2x "contigous" (in comments, in gc_free_threading.c - NO code/functionality changes):

  cpython/Python/gc_free_threading.c

  Line 579 in a64b7ec

  // a contigous sequence of PyObject pointers, can contain NULLs

  and

  cpython/Python/gc_free_threading.c

  Line 749 in a64b7ec

  // Called when we have a contigous sequence of PyObject pointers, either

• Add a note in two places where something is specific to the non-free-threaded build

  • At

    cpython/InternalDocs/garbage_collector.md

    Line 285 in 41d0922

    objects that have already been visited once (by unsetting the `PREV_MASK_COLLECTING`

    note "PREV_MASK_COLLECTING" is the name of the flag used in the non-free-threaded build
  • At

    cpython/InternalDocs/garbage_collector.md

    Line 634 in 41d0922

    In order to save memory, the two linked list pointers in every object with GC

    , note the "fat pointer"/"tagged pointer" memory saving techniques applied to the two linked list pointers discussed in that section are specific to the non-free-threaded build

• Propose to remove a seemingly outdated (not applicable to e.g. mark alive phase of free-threaded Python builds), potentially confusing paragraph

  In the free-threaded build ( https://peps.python.org/pep-0703/ , https://peps.python.org/pep-0779/ ) already discussed in many places in this article, the "LIFO stack, of unlimited size"¹ mentioned seems to not use the existing pointers on "the objects themselves"², e.g. in gc_propagate_alive (of which it is said "In most programs, this marks nearly all objects that are not actually unreachable"³) _PyObjectStack_Pop⁴ and _PyObjectStack_Push⁵ are used, and the push seems to allocate fresh memory⁶

  cpython/Include/internal/pycore_object_stack.h

  Lines 37 to 48 in e2ff498

  	_PyObjectStack_Push(_PyObjectStack *stack, PyObject *obj)
  	{
  	_PyObjectStackChunk *buf = stack->head;
  	if (buf == NULL || buf->n == _Py_OBJECT_STACK_CHUNK_SIZE) {
  	buf = _PyObjectStackChunk_New();
  	if (buf == NULL) {
  	return -1;
  	}
  	buf->prev = stack->head;
  	buf->n = 0;
  	stack->head = buf;
  	}

  (for one simple case to consider, in the free threaded build with prefetch disabled, the gc_propagate_alive appears to be a DFS of "nearly all objects that are not actually unreachable"³ so would seem to have worst case O(n) additional memory requirements -- contrary to "neither does it in any other way require additional memory proportional to the number of objects"²).

  Thus I propose to remove a paragraph on O(1) space usage, "no additional memory proportional to the number of objects" in its current form as potentially confusing. (

  cpython/InternalDocs/garbage_collector.md

  Lines 298 to 302 in 5539c2a

  	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.

  )

  (it might still be descriptive of some configuration of the non-free threaded GC⁷, to gc.c instead of gc_free_threading.c, only if the doubly linked list pointers used for all traversals in that implementation are built into the objects in advance, with the caveat that adding overhead to each object, instead of externalizing it to a separate stack, still requires memory proportional to the number of objects. Note also comments at

  cpython/Python/gc_free_threading.c

  Lines 1192 to 1193 in a64b7ec

  	// The free-threaded GC cost is proportional to the number of objects in
  	// the mimalloc GC heap and so we should include the counts for untracked

  , and

  cpython/Misc/NEWS.d/3.13.0a4.rst

  Lines 150 to 153 in a64b7ec

  	The free-threaded build no longer allocates space for the ``PyGC_Head``
  	structure in objects that support cyclic garbage collection. A number of
  	other fields and data structures are used as replacements, including
  	``ob_gc_bits``, ``ob_tid``, and mimalloc internal data structures.

  )

  References:

• Issue: Typos in garbage collector docs #157724

Footnotes

1. ."LIFO stack, of unlimited size" used during mark alive free threaded build GC phase: https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L536 ↩

2. .vs. "the objects themselves contain all the storage the GC algorithms require" https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L301 (may be true for the non-free threaded build only, for gc.c NOT gc_free_threading.c ; though "neither does it in any other way require additional memory proportional to the number of objects" is still possibly misleading as adding per object overhead still requires memory proportional to the number of objects and is not necessarily more scalable than externalizing that cost to a separate data structure.) ↩ ↩²

3. ."nearly all objects that are not actually unreachable" are visited during the mark alive free threaded build GC phase: https://github.com/python/cpython/blob/e2ff498cc03886b73fca0429ee745b04646ad8e0/Python/gc_free_threading.c#L1363 ↩ ↩²

4. ._PyObjectStack_Pop is used by gc_propagate_alive, e.g. at https://github.com/python/cpython/blob/e2ff498cc03886b73fca0429ee745b04646ad8e0/Python/gc_free_threading.c#L1346 ; also after the mark alive stage too at e.g. mark_reachable https://github.com/python/cpython/blob/41d09220bda74cda6897a4e807d7af0edaff1fd8/Python/gc_free_threading.c#L1048 ↩

5. ._PyObjectStack_Push is used by gc_propagate_alive, e.g. at https://github.com/python/cpython/blob/e2ff498cc03886b73fca0429ee745b04646ad8e0/Python/gc_free_threading.c#L705 ; also after the mark alive stage too at e.g. visit_clear_unreachable https://github.com/python/cpython/blob/41d09220bda74cda6897a4e807d7af0edaff1fd8/Python/gc_free_threading.c#L1032 . ↩

6. . _PyObjectStack_Push seems to allocate fresh memory, not reuse pointers already on the "objects themselves": https://github.com/python/cpython/blob/e2ff498cc03886b73fca0429ee745b04646ad8e0/Include/internal/pycore_object_stack.h#L37-L48 ; and see also gc_mark_span_push https://github.com/python/cpython/blob/e2ff498cc03886b73fca0429ee745b04646ad8e0/Python/gc_free_threading.c#L666-L678 ↩

7. in other places in the same section distinctions are made between the free threaded and non-free threaded GCs, e.g. at https://github.com/python/cpython/blob/5539c2a5437acc4f4719aabac375368e0d310bd9/InternalDocs/garbage_collector.md?plain=1#L229 but not for this paragraph ↩