GC Lite
A Partitioned Garbage Collector.
Features
- Flat partitions: Multiple independent partitions without parent–child hierarchy
- Tri-color marking: Classic tri-color mark–sweep algorithm with gray lists per partition
- Root and scope based lifetime: Root nodes and stack scopes define node reachability
- Weak references: Non-owning references that do not prevent collection
- Global memory limit and GC threshold: Heap-wide memory limit with automatic GC triggering
- Type-safe tracing: All managed types implement
GcTraceand are registered in a static type table
Core Components
- GcHeap: Owns all partitions, tracks memory usage and runs garbage collection
- GcPartitionId / GcPartition: Partition identifier and per-partition statistics
- GcRef: Typed GC reference that dereferences to
&T - GcWeak: Weak reference that can be upgraded to
GcRef<T> - GcTrace / GcTraceCtx: Tracing trait and context used by the collector
- GcScope: Scoped allocation context for local nodes to be protected from being garbage collected
- GcTypeRegistry / gc_type_register!: Static type table and helper macro used to register GC types
Before using the heap, every GC-managed type must be registered through the gc_type_register! macro. This macro generates a static GC_TYPE_REGISTRY variable that holds all type metadata and automatically defines GC_TYPE_ID and helper constructors (such as alloc_node) for each registered type. The symbol name GC_TYPE_REGISTRY is created by the macro itself and is passed to GcHeap::new(&GC_TYPE_REGISTRY) in all examples below.
Basic Usage
use ;
// Register gc managed data types
gc_type_register!
All subsequent examples assume that types have been registered with gc_type_register!
and that a GcHeap instance and at least one partition already exist.
Partition Management
use GcHeap;
let mut heap = new;
let partition1 = heap.create_partition;
let partition2 = heap.create_partition;
for id in heap.partition_ids
heap.set_memory_limit;
heap.set_gc_threshold;
heap.remove_partition;
Root Objects and Scopes
use ;
let mut heap = new;
let partition = heap.create_partition;
let scope = new;
let root: = scope.alloc_root.unwrap;
let local: = scope.alloc_local.unwrap;
scope.flush;
let freed = heap.garbage_collect;
println!;
Weak References
use ;
let mut heap = new;
let partition = heap.create_partition;
let strong: =
unsafe
.map_err?;
let weak: = heap.downgrade;
match weak.upgrade
Data Types
use ;
gc_type_register!
Errors
use ;
;
gc_type_register!
Running Examples
Notes
- Every type stored in the heap must implement the
GcTracetrait and be registered viagc_type_register! - Only root or scope-protected nodes, or nodes reachable from them, are retained
- Weak references do not keep nodes alive
- Setting the heap memory limit to
0disables the limit - Automatic GC is controlled by a heap-wide GC threshold;
0disables automatic GC - The collector uses a tri-color mark–sweep algorithm internally (white/gray/black)