Module heap 

Phase D mark-and-sweep garbage collector.

This module is the production GC for the Lua runtime, replacing the Rc<T>-backed GcRef<T> placeholder used through Phase B/C. It is a single-threaded precise tracing collector with incremental and generational paths plus forward/backward write barriers.

Vocabulary

• Gc: a pointer-sized handle. Copy + Clone. Replaces GcRef<T>.
• GcBox: the heap allocation; contains a header and the value.
• GcHeader: per-object metadata (color, age, finalized flag, intrusive next pointer for exactly one heap owner list, and grayagain revisit link).
• Trace: trait every GC-rooted type implements. The trace method walks all Gc<_> fields and calls Marker::mark on each.
• Marker: passed to trace; carries the gray queue.
• Heap: owns the allgc/finobj/tobefnz list heads, byte counters, and GC state machine.

Safety model

All unsafe is confined to this crate (per harness/unsafe-budgets.toml). The invariants are:

1. Every Gc<T> points to a valid, allocated, not-yet-swept GcBox<T>.
2. The intrusive heap lists are consistent: traversing header.next from Heap.head, Heap.finobj, and Heap.tobefnz reaches every live heap-owned GcBox exactly once.
3. After Heap::full_collect(roots), every Gc<T> reachable from roots is still valid; unreachable boxes are dropped and deallocated.

Migration shape

Existing code holds GcRef<T> (which after Phase D is a type alias for Gc<T>). Legacy call sites like GcRef::new(value) route through Gc::new_uncollected which allocates a GcBox but does NOT register it in any heap. Phase D-1b agent work converts these to state.heap().allocate(value) so the new box joins the heap owner lists.

Structs

AllGcCohortStats

Diagnostic counts for the allgc list split by generational cursors.

FinalizerRegistry

FinalizerRegistryStats

Gc

A GC-managed pointer. Copy + Clone (one-machine-word). Replaces GcRef<T>.

GcBox

A heap-allocated, GC-tracked value plus its header.

GcHeader

Per-object GC metadata. Lives at the start of every GcBox.

Heap

HeapGuard

A scoped guard for the currently-active heap. Pushed at entry to state.run() / state.protected_call() / state.load(); popped on drop. Supports nesting (multiple LuaStates on one thread).

HeapRef

Marker

Holds the gray queue during a mark phase. Passed to Trace::trace.

MarkerStats

Diagnostic counters for the latest mark phase.

StepBudget

Work budget for one incremental step.

SweepStats

Diagnostic counters for the latest sweep phase.

WeakRegistry

WeakRegistrySnapshot

WeakRegistryStats

Enums

Color

A traced color in the tri-color invariant.

GcAge

Object age used by Lua’s generational collector.

GcState

Phases of the incremental collection cycle.

StepOutcome

Outcome of one call to Heap::incremental_step_with_post_mark.

WeakListKind

Traits

FinalizerEntry

Minimal metadata a finalizable VM object must expose for collector-owned finalizer-list bookkeeping.

Trace

Every GC-rooted type implements Trace to expose its Gc<_> fields.

WeakEntry

Minimal operations needed for collector-owned weak-registry bookkeeping.

Functions

with_current_heap

Runs f with a reference to the currently-active heap, or None if no HeapGuard is in scope.