Struct GcHeap 

pub struct GcHeap { /* private fields */ }

Main GC heap — owns all regions, allocator, marker, and relocation state.

Implementations

impl GcHeap

pub fn new() -> Self

Create a new GC heap with default configuration.

pub fn with_threshold(gc_threshold: usize) -> Self

Create a new GC heap with a custom collection threshold.

pub fn alloc<T>(&self, value: T) -> *mut T

Allocate memory for a value of type T, prefixed with a GcHeader.

Returns a raw pointer to the T allocation (header is at ptr - 8).

Safety

The caller must initialize the memory before the next GC cycle.

pub fn alloc_raw(&self, layout: Layout) -> *mut u8

Allocate raw bytes with a GcHeader prefix.

pub fn should_collect(&self) -> bool

Check if a GC cycle should be triggered.

pub fn collect(&mut self, trace_roots: &mut dyn FnMut(&mut dyn FnMut(*mut u8)))

Run a full stop-the-world collection.

trace_roots is called to enumerate the root set.

pub fn collect_incremental( &mut self, mark_budget: usize, trace_roots: &mut dyn FnMut(&mut dyn FnMut(*mut u8)), ) -> CollectResult

Run one incremental collection step.

On the first call this starts a new marking cycle (short STW for root snapshot). Subsequent calls process up to mark_budget gray objects. When marking completes, a short STW termination pass drains the SATB buffer and, once converged, sweeps dead objects.

Returns CollectResult::InProgress while marking, or CollectResult::Complete(stats) when a full cycle finishes.

pub fn write_barrier(&mut self, old_ref: *mut u8)

SATB write barrier — call this whenever a reference field is about to be overwritten during an active marking phase.

old_ref is the pointer value that is being overwritten (before the store takes place).

pub fn write_barrier_combined(&mut self, slot_addr: usize, _new_val: *mut u8)

Combined write barrier: card table dirty + SATB enqueue.

Call this whenever a reference slot at slot_addr is about to be overwritten with new_val. This performs two duties:

1. Card table: marks the card containing slot_addr as dirty so that the next young-generation collection knows to scan this card for old-to-young pointers.

2. SATB: if an incremental marking cycle is in progress, reads the old pointer value from slot_addr and enqueues it so the marker does not miss a reference that was live at the start of the cycle.

This must be called before the store overwrites *slot_addr.

Safety

slot_addr must be a valid, aligned pointer to a *mut u8 field within a GC-managed object.

pub fn generations_mut(&mut self) -> &mut GenerationalCollector

Get a mutable reference to the generational collector (for card table init).

pub fn generations(&self) -> &GenerationalCollector

Get a reference to the generational collector.

pub fn is_marking(&self) -> bool

Check whether incremental marking is currently active.

pub fn satb_buffer_mut(&mut self) -> &mut SatbBuffer

Get a mutable reference to the SATB buffer (for testing / direct access).

pub fn mark_phase(&self) -> MarkPhase

Get the current mark phase.

pub fn stats(&self) -> &GcHeapStats

Get current statistics.

pub fn safepoint(&self) -> &SafepointState

Get the safepoint state for coordination.

pub fn allocator(&self) -> &BumpAllocator

Get a reference to the allocator (for TLAB refill in JIT code).

pub fn heap_size(&self) -> usize

Total bytes in all regions.

pub fn enable_adaptive_scheduling(&mut self)

Enable adaptive scheduling with default configuration.

pub fn enable_adaptive_scheduling_with_config( &mut self, young_utilization_threshold: f64, headroom_factor: f64, )

Enable adaptive scheduling with custom thresholds.

pub fn scheduler(&self) -> Option<&AdaptiveScheduler>

Get a reference to the adaptive scheduler, if enabled.

pub fn scheduler_mut(&mut self) -> Option<&mut AdaptiveScheduler>

Get a mutable reference to the adaptive scheduler, if enabled.

pub fn should_collect_adaptive(&self) -> CollectionType

Query the adaptive scheduler to determine what collection (if any) should be performed.

If no scheduler is configured, falls back to simple byte-threshold check (returns CollectionType::Full or CollectionType::None).

pub fn avg_gc_pause_secs(&self) -> f64

Average GC pause time in seconds. Returns 0.0 if no collections yet.

pub fn collect_young(&mut self, roots: &[*mut u8]) -> SweepStats

Run a young-generation collection.

Collects only young-gen regions + dirty cards. Objects that have survived enough cycles are promoted to old gen.

pub fn collect_old(&mut self, roots: &[*mut u8]) -> SweepStats

Run an old-generation (full) collection.

Marks from all roots across both generations and sweeps old-gen regions.

pub fn record_allocation(&mut self, bytes: usize)

Record an allocation with the adaptive scheduler.

This should be called after each allocation so the scheduler can track allocation rates for predictive old-gen collection.

pub fn young_gen_utilization(&self) -> f64

Young generation utilization (0.0 to 1.0).

pub fn old_gen_free_bytes(&self) -> usize

Free bytes in old generation.

Trait Implementations

impl Default for GcHeap

fn default() -> Self

Returns the “default value” for a type.