Module heap 

Mark-and-sweep garbage collector.

This module is the production GC for the Lua runtime — a single-threaded precise tracing collector with incremental and generational paths plus forward/backward write barriers. GcRef<T> (in lua-types) is a type alias for this crate’s Gc<T>; an earlier revision backed GcRef<T> with a plain Rc<T> instead.

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, and an intrusive next pointer for exactly one heap owner list). The grayagain revisit set is heap-owned (Heap::grayagain), not an intrusive 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.

Allocation paths

GcRef::new(value) (in lua-types) allocates through state.heap().allocate(value), joining the active heap’s owner lists; a guard-less call panics rather than silently falling back to an untracked allocation (issue #249). Gc::new_uncollected remains a separate, explicit escape hatch for the rare detached/process-lifetime case — it allocates a GcBox but does not register it in any heap.

Structs

AllGcCohortStats

Diagnostic counts for the allgc list split by generational cursors.

BootstrapScope

RAII handle for a heap bootstrap window; created by Heap::bootstrap_scope, ends the window on drop. Exists so error paths (? during stdlib install, lua_open failure) cannot leave the heap stuck in bootstrap mode the way a manual end_bootstrap call can.

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

A non-owning heap identity handle for weak references (issue #252): holds a Weak<Heap>, so a GcWeak that outlives its heap answers “does the heap still contain my target” with a plain false — after sweep or after heap teardown, indistinguishably — instead of dereferencing freed memory. No unsafe, no outlives contract.

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.

Udata51Probe

A Lua 5.1 collect-time finalizability probe for a single userdata.

WeakEntry

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

Functions

detached_allocations

Total detached (Gc::new_uncollected) allocations made on this thread since it started. Leak canaries assert a zero delta across embedding scenarios. This counter deliberately lives outside the heap’s own bookkeeping: detached boxes never touch bytes/objects, which is exactly the blind spot that hid issue #249 — a mechanism must not be verified with bookkeeping it maintains itself.

with_current_heap

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