Struct Heap 

pub struct Heap { /* private fields */ }

Implementations

impl Heap

pub fn new() -> Self

pub fn unpause(&self)

Enable collection. Until this is called, step is a no-op (so the runtime can bootstrap without prematurely freeing objects).

pub fn is_paused(&self) -> bool

pub fn allocate<T: Trace + 'static>(&self, value: T) -> Gc<T>

Allocate a new GcBox<T> and prepend it to the allgc chain.

pub fn bytes_used(&self) -> usize

Bytes currently retained by GC-tracked objects (rough estimate).

pub fn adjust_bytes(&self, delta: isize)

Adjust the heap’s pacer byte counter by a signed delta, saturating at zero. Used by Gc::account_buffer to charge or refund the bytes of an object’s owned heap buffers (table array/node Vecs) so collections fire at honest memory pressure rather than only on header sizes.

pub fn threshold_bytes(&self) -> usize

Current collection threshold in bytes. When bytes_used() >= threshold_bytes(), the next step() will run a full collection (unless paused). Used by callers that want to short-circuit expensive prep work (e.g. snapshotting weak tables / pending finalizers) when no collection will actually fire.

pub fn set_threshold_bytes(&self, threshold: usize)

Override the next automatic collection threshold.

The VM uses this when Lua-level GC pacing (GCdebt, minor-debt, and pause-debt calculations) has already computed a byte threshold from the collector-owned live-byte counter.

pub fn would_collect(&self) -> bool

Cheap predicate: would a step() actually do work? Equivalent to !paused && bytes_used() >= threshold_bytes(). Callers that build snapshot state before invoking the heap should gate on this.

pub fn collections(&self) -> usize

pub fn allocation_token(&self, identity: usize) -> Option<usize>

Return the current heap token for a live allocation identity.

Weak handles use this before sweep to capture their target allocation without dereferencing stale pointers later.

pub fn contains_allocation(&self, identity: usize, token: usize) -> bool

Return true when identity still names the same heap allocation.

The token check prevents allocator address reuse from making a stale weak handle look live again.

pub fn barrier<P, C>(&self, parent: Gc<P>, child: Gc<C>)

where P: Trace + 'static, C: Trace + 'static,

Forward write barrier: invoked when parent (already-traced black object) gains a new reference to child. To preserve the tri-color invariant (“no black points to white”), we mark the child gray immediately. Cheap: one branch + maybe one queue push.

During incremental mode this prevents the marking phase from missing the new edge. In current stop-the-world mode it’s still correct (a no-op when the collection is idle), so call sites can be wired now and the incremental upgrade is mechanical later.

pub fn generational_forward_barrier<P, C>(&self, parent: Gc<P>, child: Gc<C>)

where P: Trace + 'static, C: Trace + 'static,

Generational forward barrier: if an old object receives a reference to a young object, the child cannot jump directly to OLD because it may still point at younger objects. Lua marks it OLD0 so later young collections advance it through OLD1 to OLD.

pub fn generational_backward_barrier<P>(&self, parent: Gc<P>)

where P: Trace + 'static,

Generational backward barrier: an old object that now points to a young object is revisited by the next young collection. This mirrors luaC_barrierback_’s age transition to TOUCHED1.

pub fn step(&self, roots: &dyn Trace)

Possibly run a collection. Trigger: bytes_used > threshold. Caller passes the root set (the runtime — typically GlobalState implementing Trace).

pub fn step_with_post_mark<F: FnMut(&mut Marker)>( &self, roots: &dyn Trace, post_mark: F, )

Like [step] but invokes a post_mark hook when a collection actually fires (threshold reached). Hook is a no-op on the short-circuit path. The runtime uses this to bridge weak-table pruning into implicit GC steps fired from inside the VM loop.

pub fn full_collect(&self, roots: &dyn Trace)

Stop-the-world full collect. Marks every reachable object from roots, then sweeps white (unreachable) boxes from the allgc chain.

pub fn mark_only_with_post_mark<F: FnMut(&mut Marker)>( &self, roots: &dyn Trace, post_mark: F, )

Run only the mark/atomic hook portion of a collection, without sweeping.

This is used by runtimes that need an atomic reachability snapshot for weak-table cleanup while they are deliberately avoiding object freeing.

pub fn promote_all_to_old(&self)

Metadata transition used when entering generational mode after a full mark: all currently live objects become old.

pub fn reset_all_ages(&self)

Metadata transition used when returning to incremental mode: Lua clears age information and treats all objects as new again.

pub fn minor_collect_with_post_mark<F: FnMut(&mut Marker)>( &self, roots: &dyn Trace, post_mark: F, )

Run a complete young-generation collection.

This is the first generational path: it uses the normal root tracer for correctness, then limits sweep/freeing to young objects. Later work can replace the full root traversal with cohort-list traversal without changing the age/sweep contract introduced here.

pub fn full_collect_with_post_mark<F: FnMut(&mut Marker)>( &self, roots: &dyn Trace, post_mark: F, )

Stop-the-world full collect with a post-mark hook.

Internally drives the incremental state machine to completion with an unbounded budget — equivalent to repeatedly calling [incremental_step_with_post_mark] until it returns Paused. The post-mark hook is invoked exactly once, during the atomic transition.

pub fn incremental_step_with_post_mark<F: FnMut(&mut Marker)>( &self, roots: &dyn Trace, budget: StepBudget, post_mark: F, ) -> StepOutcome

Run one budgeted step of the incremental collector.

The state machine advances Pause → Propagate → Atomic → Sweep → Finalize → Pause. Each phase consumes budget; the call returns when the budget runs out or the cycle reaches Pause. The post_mark hook is invoked exactly once per cycle, during the Atomic transition (after the initial gray-queue drain, before sweep starts).

Returns:

• StepOutcome::Paused — the cycle completed.
• StepOutcome::InProgress — budget exhausted before the cycle finished; caller may step again.
• StepOutcome::SkippedStopped — heap is paused; nothing happened.

pub fn incremental_run_until_state_with_post_mark<F: FnMut(&mut Marker)>( &self, roots: &dyn Trace, target: GcState, max_work: isize, post_mark: F, ) -> StepOutcome

Drive an incremental cycle until target is entered, stopping before any subsequent phase work. Intended for testC-style inspection of mid-cycle color/barrier invariants; normal collector pacing uses Self::incremental_step_with_post_mark.

pub fn gc_state(&self) -> GcState

Returns the current state of the incremental collector.

pub fn allgc_count(&self) -> usize

Approximate number of live GC boxes, computed by walking the allgc chain. Linear in heap size; used for cycle-cost estimation and tests.

pub fn type_name_count( &self, predicate: impl FnMut(&'static str) -> bool, ) -> usize

Count live allgc objects whose concrete Rust type name matches predicate. This is diagnostic/testC telemetry only; collector logic must not depend on Rust type names.

pub fn drop_all(&self)

Drop every allocation, ignoring reachability. Called at shutdown. After this returns, every outstanding Gc<T> is dangling — callers must ensure no Gc<T> outlives the Heap.

Trait Implementations

impl Default for Heap

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Heap

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.