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, stop-the-world, precise tracing collector with a forward write barrier. Incremental marking is a future enhancement; the current implementation does a full collect each time step decides it’s time.

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, finalized flag, intrusive next pointer for the allgc list).
• 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 list head, byte counters, 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 allgc intrusive list is consistent: traversing header.next from Heap.head reaches every live 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 allgc chain.

Structs

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

The heap. One per GlobalState. Owns the intrusive allgc list of every allocated GcBox, tracks total bytes, and runs collections.

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).

Marker

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

StepBudget

Work budget for one incremental step.

Enums

Color

A traced color in the tri-color invariant.

GcState

Phases of the incremental collection cycle.

StepOutcome

Outcome of one call to Heap::incremental_step_with_post_mark.

Traits

Trace

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

Functions

with_current_heap

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