How fitzgen/safe-gc works
Project type and purpose
• This is a Rust library implementing a garbage collector that is completely safe (i.e. without any unsafe code). Its primary purpose is to allow users to allocate and manage memory safely in Rust via a GC heap.
File structure for architectural components
• Top-level directories include:
• “src”: Contains the core library code (e.g., free_list.rs, mark_bits.rs, lib.rs) which likely implement the low-level memory management and GC algorithms.
• “crates/mutator”: Likely a separate crate/module that provides additional functionality (perhaps an API extension or mutation logic) for the main GC library, with its own Cargo.toml and source code.
• “fuzz”: Contains fuzz testing code (e.g., mutator.rs) and its own configuration; this shows an infrastructure for robustness and testing of the GC logic.
• “.github”: Contains CI configuration (GitHub workflows) to ensure code quality and build status.
• There are also top-level Cargo.toml and license files which indicate that this is a properly packaged library with multiple components (or sub-crates) in a workspace.
Key components to highlight
a. GC Core Library:
• Components from “src” such as the main library (lib.rs) and support modules (free_list.rs, mark_bits.rs) that implement the heap, memory allocation, and garbage collection logic.
• The “Trace” trait implementations and the use of types like Gc<T>, Heap, Collector and Root<T> as described in the README.
b. Mutator Crate:
• Additional functionality provided by the “crates/mutator” crate. Explain its relationship with the core GC library (likely an extension or experimental component).
c. Fuzz Testing Framework:
• The “fuzz” directory which houses fuzz tests (mutator.rs) should be shown as a separate component interacting with the core library to validate the GC logic.
d. External Integration:
e. CI Infrastructure:
Relationships and interactions
• Within the GC core component, show the relationship between:
• Heap creation and allocation modules.
• The Collector component that scans and reclaims unreachable objects.
• The Trace mechanism where user-defined types implement the Trace trait.
• From the Mutator crate, illustrate how it either augments or tests mutation aspects within the GC system.
• From the fuzz testing block, demonstrate the feedback loop where fuzz tests interact with the GC core to catch potential errors.
Architectural patterns and design principles
• Design’s safe-by-design principle; note that the entire GC library is implemented in safe Rust with no use of unsafe code.
• That the system supports multiple independent heaps and heterogeneous object types.
• Modularity by showing different modules (core, mutator, testing) as separate, well-defined components that follow the separation of concerns principle.
Final elements to be present
• Clear labels for each component (GC Core, Mutator Crate, Fuzz Tests, CI Workflow, Client API).