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