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

(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 in comments (no code changes) in gc.c and gc_free_threading.c

• 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

• For the free-threaded build object header description, replace the "pad" field with "ob_flags":
  At bc262de#diff-87272721a5cf1cd9915d6f503f6a7bbefa2f26c935c7ce83ca78706afd0ad05aR155
  it seems _padding was replaced with ob_flags as part of GH-125174: Mark objects as statically allocated. #127797 .

• Note ob_ref_shared is Py_ssize_t so size_t-sized and not necessarily pointer sized.
  See

  cpython/Include/object.h

  Line 165 in b0dda15

  Py_ssize_t ob_ref_shared; // shared (atomic) reference count

  , vs claim in original

  cpython/InternalDocs/garbage_collector.md

  Line 150 in b0dda15

  other fields, `ob_tid`, `ob_ref_shared`, and `ob_type`, are all

  .
  Also https://peps.python.org/pep-0353/#why-not-py-intptr-t .

• In garbage_collector.md

  • note "Why moving unreachable objects is better" applies only to the non-free-threaded build (update

    cpython/InternalDocs/garbage_collector.md

    Line 304 in 212e603

    Why moving unreachable objects is better

    )
  • note that objects do not move to/from an unreachable list in the free-threaded build (the _PyGC_BITS_UNREACHABLE ob_gc_bits flag is set)
  • remove "This process is really a breadth first search over the object graph" regarding propagating reachable status from objects found to be reachable as it is not so simple
    e.g. on the free-threaded build, for each object during the heap traversal found to be reachable within the unreachable flagged items,
    it seems a new depth-first (not breadth-first) search is initiated to propagate the reachability status
    see

    cpython/Python/gc_free_threading.c

    Line 1461 in 212e603

    if (gc_visit_heaps(interp, &mark_heap_visitor, &state->base) < 0) {

    , mark_heap_visitor , calls gc_clear_unreachable then
    mark_reachable (important)
    

    cpython/Python/gc_free_threading.c

    Line 1039 in 212e603

    mark_reachable(PyObject *op)

    which seems to use a stack to do a DFS

    cpython/Python/gc_free_threading.c

    Line 1032 in 212e603

    return _PyObjectStack_Push((_PyObjectStack *)stack, op);

    ,

    cpython/Python/gc_free_threading.c

    Line 1048 in 212e603

    op = _PyObjectStack_Pop(&stack);

• 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:

This should not be backported (at least without modification, to any version prior to v3.14 as it references content that is specific to that version or later, e.g. ob_flags replacing the padding field in the object headers).

• Issue: Typos in garbage collector docs #157724