Garbage Collector (Pop GC)
Relevant source files
The following files were used as context for generating this wiki page:
The Garbage Collector (Pop GC) is a core component of the Pop Lang runtime, responsible for automated memory management. It is designed as a precise, concurrent, generational collector that supports consistent behavior across different native and virtual machine backends. By utilizing a moving nursery for short-lived allocations and a mostly non-moving mature heap, it aims to achieve efficient collection with bounded pause times. Sources: README.md:162-171, AGENTS.md:652-656
Pop GC operates as a cross-backend semantic contract, ensuring that native machine-code compilation, interpreters, and future virtual machines preserve the same object initialization and visibility semantics. It utilizes the Pop Lang Runtime Interface (PLRI) to bridge the gap between generated code and runtime services, employing precise roots, stack maps, and write barriers to maintain heap integrity. Sources: README.md:173-181, AGENTS.md:661-664
Architecture Overview
The Pop GC architecture is built upon several critical sub-modules that handle specific aspects of memory management, ranging from heap allocation to object tracing and reference relocation. Sources: crates/runtime/collector/src/lib.rs:36-40
The diagram shows the internal module structure of the pop-runtime-collector crate, highlighting the separation between general collector logic and specialized relocation logic. Sources: crates/tools/architecture-tests/src/tests.rs:434-438, crates/tools/architecture-tests/src/tests.rs:446-450
Key Components
| Component | Responsibility |
|---|---|
| Nursery | A moving memory region for efficient allocation and collection of short-lived objects. |
| Mature Heap | A mostly non-moving region for objects that survive initial collection cycles. |
| Write Barriers | Generational and SATB (Snapshot-At-The-Beginning) barriers to preserve correctness during concurrent work. |
| Stack Maps | Precise data structures allowing the collector to identify managed references in native stack frames. |
| PLRI Adapters | Bridges that connect the collector to specific runtime environments (e.g., BootstrapRuntime). |
Sources: README.md:164-171, crates/tools/architecture-tests/src/tests.rs:423-428, crates/tools/architecture-tests/src/tests.rs:440
Precise Relocation and Conformance
A distinguishing feature of Pop GC is its "Relocation Conformance" protocol. This ensures that the collector can safely move managed references and update all roots accordingly. The system defines specific stages for relocation, including relocation_conformance_stage2, to verify the integrity of moving nurseries. Sources: crates/tools/architecture-tests/src/tests.rs:420-428
Relocation Workflow
This diagram illustrates how the collector interacts with the application via the PLRI during a relocation cycle to maintain precise root information. Sources: crates/tools/architecture-tests/src/tests.rs:420-428, crates/tools/architecture-tests/src/tests.rs:528-535
Dependency and Safety Boundaries
The Pop GC implementation is strictly partitioned to prevent architectural drift. The pop-runtime-collector crate depends on pop-runtime-interface (PLRI) but is forbidden from depending on native ABI or native facade crates. This ensures the collector core remains portable and backend-neutral. Sources: crates/tools/architecture-tests/src/tests.rs:439-441
Architectural Invariants
- No Runtime Reflection: GC layouts do not enable unrestricted runtime reflection; metadata retention requires explicit serializable adapters. Sources: README.md:200-203, AGENTS.md:702-706
- Precise Scanning: The collector does not use conservative scanning; it must know the exact location of every managed reference. Sources: README.md:168, AGENTS.md:658
- Backend Neutrality: MIR (Mid-level Intermediate Representation) serves as the contract for the collector, ensuring consistent GC safe points across LLVM and interpreters. Sources: README.md:214-220, AGENTS.md:744-750
Implementation Details (Rust)
The collector is implemented in Rust (Edition 2024). It uses focused modules that are kept small (typically under 320 lines) to ensure maintainability and responsibility isolation. Sources: crates/tools/architecture-tests/src/tests.rs:453-454, AGENTS.md:753
// Example of the thin module inventory in crates/runtime/collector/src/lib.rs
mod access;
mod adapter;
mod heap;
mod relocation;
mod trace;
pub use pop_runtime_interface::{SchedulerId, TaskFrameRootId};
Sources: crates/runtime/collector/src/lib.rs:36-40, crates/tools/architecture-tests/src/tests.rs:440-441
Performance and Metrics
The GC is subject to a strict "benchmark contract." Production distributions must report metrics including nanoseconds_per_operation, reclaimed_objects, and scanned_objects. These metrics are used to verify the performance budget of stabilized APIs. Sources: architecture/22.6-standard-library-implementation-plan.md:64-70, crates/tools/architecture-tests/src/tests.rs:490-505
| Metric Category | Key Data Fields |
|---|---|
| Throughput | nanoseconds_per_operation, operations, elapsed_nanoseconds |
| Utilization | logical_peak_objects, logical_peak_slots, available_parallelism |
| Collector Activity | collections, reclaimed_objects, scanned_objects, relocated_roots |
Sources: crates/tools/architecture-tests/src/tests.rs:497-505, crates/tools/architecture-tests/src/tests.rs:511-515
Summary
Pop GC provides a high-performance, precise memory management system that is central to Pop Lang's promise of predictable native runtimes. By enforcing strict architectural boundaries through the PLRI and mandating precise root tracking and relocation conformance, the project ensures that memory safety does not rely on dynamic fallbacks or conservative scanning. The generational moving nursery and concurrent SATB barriers allow for efficient execution across native machine code and virtual machine targets. Sources: README.md:162-181, AGENTS.md:652-664, architecture/19-architecture-conformance-and-regression-policy.md:280-285