# antoniosarosi/rulloc architecture

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

- Interactive diagram: https://gitdiagram.com/antoniosarosi/rulloc
- Repository: https://github.com/antoniosarosi/rulloc

## Overview

##### Project type and purpose
- This is a Rust library (“Rulloc”) implementing a general-purpose memory allocator. It exposes two public interfaces—`std::alloc::Allocator` and `std::alloc::GlobalAlloc`—and is accompanied by a set of small example programs (`examples/*.rs`) demonstrating standalone, global, bucketed, and aligned allocations.

##### File structure
- Top-level files:
- Cargo.toml / rustfmt.toml / LICENSE / README.md
- `.gitignore`
- `src/` directory: each file maps to one allocator component:
- `allocator.rs` – overall allocator orchestration
- `bucket.rs` – bucket size classes and their region & free-list management
- `region.rs` – contiguous OS‐allocated memory chunks, list of blocks
- `block.rs` + `header.rs` – block metadata and content layout
- `freelist.rs` + `list.rs` – free‐list and doubly linked list utilities
- `allocator.rs` – top-level array of buckets + global mutex
- `platform.rs` – OS‐specific `mmap` / `VirtualAlloc` abstraction
- `realloc.rs` + `alignment.rs` + `allocator.rs` – alignment and resizing logic
- `examples/` folder: four small executables demonstrating various usage patterns.

##### README for architecture insights
- Block header + content layout
- How blocks chain inside a region
- How free blocks are tracked per bucket
- How the allocator is an array of buckets, each with its regions + free lists
- Implementation notes on mutex placement (global, per-bucket, per-thread), optimization opportunities, and how system calls happen when buckets run dry.

##### Main components and their relationships
a. Components:
– API Layer: `Allocator` + `GlobalAlloc` trait implementations
– GlobalAllocator (in `allocator.rs`): array of N buckets behind a mutex
– Bucket[i]: manages multiple Regions and a free-list for that size class
– Region: OS‐backed contiguous memory chunk (multiple pages), holds a doubly-linked list of Blocks
– Block: allocation unit with header (prev/next pointers, size, free flag, alignment padding) and user content
– FreeList: linked list of free Blocks inside a bucket
– Platform Abstraction: dispatches `mmap` on Unix or `VirtualAlloc` on Windows
– Examples: consumers of the public API
b. Data flow & interactions:
– Allocation request → API Layer → lock GlobalAllocator mutex → pick Bucket based on size →
if FreeList nonempty, pop a Block and return pointer → otherwise request a new Region → split into Blocks → add Blocks to FreeList → pop one → unlock → return pointer
– Deallocation request → API Layer → lock mutex → mark Block free → push back onto FreeList → possibly release Region to OS
– Buckets and Regions request memory from OS via `platform.rs` → syscalls (`mmap`/`VirtualAlloc`)
c. Architectural patterns:
– Layered (API → Allocator → Bucket → Region → Block → OS)
– Modular decomposition (each concern in its own module)
– Linked lists and free lists for memory management
– Bucket size classes for fragmentation reduction
– Mutex for thread safety (future per-bucket/thread refinements)
d. Key technologies:
– Rust and Cargo
– `std::alloc` traits
– OS syscalls (`mmap`, `VirtualAlloc`) via `platform.rs`
– Miri for testing memory safety

##### Detail
- Modules as subcomponents (e.g., alignment logic, realloc path)
- Where alignment or resizing occurs
- Call out where the global mutex sits and note TODO for per-bucket or per-thread locking

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers
    subgraph "Examples" 
        direction TB
        Standalone["standalone.rs"]:::examples
        GlobalEx["global.rs"]:::examples
        BucketsEx["buckets.rs"]:::examples
        AlignedEx["aligned.rs"]:::examples
    end

    subgraph "API Layer" 
        direction TB
        API["API Layer\n(std::alloc::Allocator & GlobalAlloc)"]:::api
    end

    subgraph "Allocator Layer"
        direction TB
        GlobalAlloc["GlobalAllocator\n(array of buckets + global mutex)"]:::allocator
        Alignment["Alignment Logic"]:::allocator
        Realloc["Reallocation Logic"]:::allocator
    end

    subgraph "Bucket Layer"
        direction TB
        Bucket["Bucket[size class]\n(regions & free-list)"]:::bucket
        subgraph "Bucket Internals"
            direction TB
            Region["Region[n pages]\n(OS-backed memory chunk)"]:::region
            Block["Block(header | content)"]:::block
            Header["Block Header\n(prev/next,size,flags)"]:::block
            FreeList["FreeList"]:::freeList
            ListUtil["List Utilities"]:::freeList
        end
    end

    subgraph "Platform"
        direction TB
        Platform["Platform Abstraction\n(mmap / VirtualAlloc)"]:::platform
    end

    %% Connections
    Standalone -->|uses| API
    GlobalEx -->|uses| API
    BucketsEx -->|uses| API
    AlignedEx -->|uses| API

    API -->|alloc/dealloc| GlobalAlloc
    GlobalAlloc -->|align/resizing| Alignment
    GlobalAlloc -->|realloc| Realloc
    GlobalAlloc -->|manages| Bucket

    Bucket -->|contains| Region
    Bucket -->|has free-list| FreeList
    Region -->|chains| Block
    Block -->|metadata| Header
    FreeList -->|pop/push| Block
    FreeList -->|uses| ListUtil

    Bucket -->|requests memory| Platform

    %% Click Events
    click API "https://github.com/antoniosarosi/rulloc/blob/master/src/lib.rs"
    click GlobalAlloc "https://github.com/antoniosarosi/rulloc/blob/master/src/allocator.rs"
    click Bucket "https://github.com/antoniosarosi/rulloc/blob/master/src/bucket.rs"
    click Region "https://github.com/antoniosarosi/rulloc/blob/master/src/region.rs"
    click Block "https://github.com/antoniosarosi/rulloc/blob/master/src/block.rs"
    click Header "https://github.com/antoniosarosi/rulloc/blob/master/src/header.rs"
    click FreeList "https://github.com/antoniosarosi/rulloc/blob/master/src/freelist.rs"
    click ListUtil "https://github.com/antoniosarosi/rulloc/blob/master/src/list.rs"
    click Platform "https://github.com/antoniosarosi/rulloc/blob/master/src/platform.rs"
    click Alignment "https://github.com/antoniosarosi/rulloc/blob/master/src/alignment.rs"
    click Realloc "https://github.com/antoniosarosi/rulloc/blob/master/src/realloc.rs"
    click Standalone "https://github.com/antoniosarosi/rulloc/blob/master/examples/standalone.rs"
    click GlobalEx "https://github.com/antoniosarosi/rulloc/blob/master/examples/global.rs"
    click BucketsEx "https://github.com/antoniosarosi/rulloc/blob/master/examples/buckets.rs"
    click AlignedEx "https://github.com/antoniosarosi/rulloc/blob/master/examples/aligned.rs"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#3A7CA5,color:#003366
    classDef allocator fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef bucket fill:#E6FFE6,stroke:#66B266,color:#337733
    classDef region fill:#FFE6CC,stroke:#CC9933,color:#663300
    classDef block fill:#FFEBCC,stroke:#CC7A29,color:#663300
    classDef freeList stroke:#CC0000,stroke-dasharray: 5 5,fill:none,color:#CC0000
    classDef platform fill:#F2F2F2,stroke:#999999,color:#666666
    classDef examples fill:#F0E6FF,stroke:#8D38C9,color:#551A8B
```
