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

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.