# kyren/gc-arena architecture

> Architecture diagram of the GitHub repository kyren/gc-arena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kyren/gc-arena
- Repository: https://github.com/kyren/gc-arena

## Overview

Based on our analysis of the file tree and README, this project is a Rust library (a “crate”) that implements garbage‐collected arenas. Its primary purpose is to let users allocate objects into an arena where garbage collection can safely occur in a single-threaded context. The system employs a safe API to ensure that all garbage-collected pointers live only within the arena’s boundaries and that only a single root of the arena can be used at a time. It also splits the functionality across two crates – one for the core functionality (gc-arena) and a helper crate (gc-arena-derive) that supplies a procedural macro to safely implement the user-facing unsafe Collect trait.

##### Main Components and Their Roles
- Core GC-Arena Crate:
– Components from the “src” directory such as arena.rs, gc.rs, dynamic_roots.rs, context.rs, metrics.rs, etc., illustrate how allocation, garbage collection, and safety are detailed.
– The GC mechanism is implemented as an incremental mark-and-sweep collector (akin to Lua 5.4’s design) with modules for managing barriers, weak pointers, and static/dynamic collections.
- Procedural Macro Crate (“derive” directory):
– Contains code to derive the Collect trait implementations for user data types, ensuring that the unsafe tracing functions are auto-generated correctly.
- Examples and Tests:
– The “examples” directory (e.g., linked_list.rs) demonstrates usage scenarios, and the “tests” directory (with both functional tests and UI tests) serves to validate the invariants and error conditions.
- Build and CI Configurations:
– Files like Cargo.toml and the .circleci config show how the project is built, versioned, and continuously integrated.

##### Relationships and Interactions
- User/Application Layer:
– Users interact with the arena via the API provided by the gc-arena crate. The primary access point is through the ‘mutate’ method, which passes a callback ensuring that GC pointers cannot leak beyond the life of the arena’s root.
- GC Engine and Arena:
– The arena holds the root pointer, and the GC engine (modules like gc.rs, gc_weak.rs, and static_collect.rs) is responsible for performing garbage collection when allocation “debt” triggers the incremental mark-and-sweep process.
- Trait Implementation:
– The Collect trait is central to traversing allocated objects. The derive crate provides procedural macro-based safe implementations of this trait, bridging user types with the collector logic.
- Safety and Lifetime Guarantees:
– Modules such as barrier.rs, lock.rs, and context.rs enforce invariant lifetimes and safe access patterns, ensuring the borrow checker prohibits misuse of GC pointers outside allowed scopes.

##### Architectural Patterns and Design Principles
- Encapsulation of GC Arena:
– The arena is the isolated memory region which limits GC pointer lifetimes; it uses invariants enforced by the Rust type system.
- Callback-based Mutation:
– Drawing attention to the design principle that all mutation occurs within a controlled callback (evidenced in the README’s description of transpose lifetimes during the arena’s ‘mutate’ calls).
- Incremental GC Design:
– The design emphasizes low pause time (accumulated allocation “debt” mapping to incremental collection), which is central to the architecture.
- Procedural Macro for Safety:
– The inclusion of the gc-arena-derive crate emphasizes automation and safety in trait implementation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Application"]:::external

    subgraph "Core GC-Arena Crate"
        AAM["Arena & Memory Management"]:::core
        GCE["Garbage Collection Engine (Incremental Mark-and-Sweep)"]:::core
        SIE["Safety & Invariant Enforcement (Single Root Ownership)"]:::core
    end

    PM["Collect Trait Implementation (Procedural Macro)"]:::macro
    EX["Examples & Usage Demonstrations"]:::example
    TS["Tests & Validation"]:::test
    CI["Build & CI Configurations"]:::ci

    U -->|"calls_mutate"| AAM
    AAM -->|"allocates_objects"| GCE
    GCE -->|"performs_GC"| SIE
    SIE -->|"triggers_Collect_trait"| PM
    EX -->|"demonstrates_usage"| U
    TS -->|"validates_invariants"| AAM
    CI -->|"runs_build_and_tests"| TS

    click AAM "https://github.com/kyren/gc-arena/blob/master/src/arena.rs"
    click AAM "https://github.com/kyren/gc-arena/blob/master/src/context.rs"
    click AAM "https://github.com/kyren/gc-arena/blob/master/src/dynamic_roots.rs"
    click GCE "https://github.com/kyren/gc-arena/blob/master/src/gc.rs"
    click GCE "https://github.com/kyren/gc-arena/blob/master/src/gc_weak.rs"
    click GCE "https://github.com/kyren/gc-arena/blob/master/src/static_collect.rs"
    click SIE "https://github.com/kyren/gc-arena/blob/master/src/barrier.rs"
    click SIE "https://github.com/kyren/gc-arena/blob/master/src/lock.rs"
    click SIE "https://github.com/kyren/gc-arena/blob/master/src/collect.rs"
    click SIE "https://github.com/kyren/gc-arena/blob/master/src/collect_impl.rs"
    click SIE "https://github.com/kyren/gc-arena/blob/master/src/metrics.rs"
    click PM "https://github.com/kyren/gc-arena/blob/master/derive/src/lib.rs"
    click EX "https://github.com/kyren/gc-arena/blob/master/examples/linked_list.rs"
    click TS "https://github.com/kyren/gc-arena/blob/master/tests/tests.rs"
    click TS "https://github.com/kyren/gc-arena/tree/master/tests/ui/"
    click CI "https://github.com/kyren/gc-arena/blob/master/Cargo.toml"
    click CI "https://github.com/kyren/gc-arena/blob/master/.circleci/config.yml"

    classDef external fill:#ffcccc,stroke:#aa0000,stroke-width:2px;
    classDef core fill:#ccf5ff,stroke:#005f99,stroke-width:2px;
    classDef macro fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef example fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef test fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef ci fill:#e6e6e6,stroke:#666666,stroke-width:2px;
```
