# dropbox/rust-alloc-no-stdlib architecture

> Architecture diagram of the GitHub repository dropbox/rust-alloc-no-stdlib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dropbox/rust-alloc-no-stdlib
- Repository: https://github.com/dropbox/rust-alloc-no-stdlib

## Overview

##### Project type and purpose
- This is an open-source Rust library (“crate”) named alloc-no-stdlib.
- Purpose: provide a pluggable framework for dynamic memory allocation in no_std environments, with multiple allocation strategies (stack, heap, calloc, global, uninitialized).

##### File structure
- Top level:
- Cargo.toml, README.md, LICENSE, CI config (.travis.yml)
- alloc-stdlib/ – a companion crate that re-exports std-based allocators when the standard library is available
- src/ – the main alloc-no-stdlib crate:
- allocator.rs – core traits and types
- stack_allocator.rs – stack-based freelist implementation
- bin examples under src/bin/
- init.rs, tests.rs, and a subfolder allocated_memory/ with macros (declare_stack_allocator_struct!, define_allocator_memory_pool!, etc.)
- tests/ – integration tests for the crate
- alloc-stdlib/src – analogous modules for std-enabled allocation

##### README for additional insights
- Describes six allocation modes: stack, heap (initialized and uninitialized), heap with single preallocated pool, calloc, static global buffer
- Shows use of Rust macros to declare allocator structs and define memory pools
- Mentions unsafe C FFI for calloc/malloc/free

##### Detail
- Every allocation strategy as its own component
- Feature-flag path: std feature enables alloc-stdlib crate and std_alloc.rs
- Macro expansion path so it’s clear how users generate concrete types
- Tests and examples as consumers of the public API

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "alloc-no-stdlib Crate (no_std)"
        direction TB
        CrateRoot["Cargo.toml\nsrc/lib.rs"]:::crate
        AllocatorTrait["Allocator Trait\n(src/allocator.rs)"]:::core
        StackAllocator["StackAllocator\n(src/stack_allocator.rs)"]:::strategy
        HeapAlloc["HeapAlloc (Box)\n(src/std_alloc.rs)"]:::strategy
        InitHelpers["init.rs\n(src/init.rs)"]:::macro
        MacrosMod["allocated_memory mod\n(src/allocated_memory/mod.rs)"]:::macro
        IndexMacro["index_macro.rs\n(src/allocated_memory/index_macro.rs)"]:::macro
        GeneratedAllocator["Generated Allocator Type"]:::core

        subgraph "Examples / Binaries"
            direction TB
            Example1["example.rs\n(src/bin/example.rs)"]:::consumer
            ExampleHeapBin["heap_alloc.rs\n(src/bin/heap_alloc.rs)"]:::consumer
            ExampleTestsBin["tests.rs\n(src/bin/tests.rs)"]:::consumer
        end

        subgraph "Integration Tests"
            direction TB
            IntegrationTests["tests.rs & lib.rs\n(src/tests.rs, tests/lib.rs)"]:::consumer
        end
    end

    subgraph "alloc-stdlib Crate (std-enabled)"
        direction TB
        ALLOC_STDLIB["Cargo.toml\nalloc-stdlib/src/lib.rs"]:::crate
        StdAllocStd["std_alloc.rs\n(alloc-stdlib/src/std_alloc.rs)"]:::strategy
        HeapAllocStd["heap_alloc.rs\n(alloc-stdlib/src/heap_alloc.rs)"]:::strategy
        TestStd["test.rs\n(alloc-stdlib/src/test.rs)"]:::consumer
        TestsLibStd["lib.rs\n(alloc-stdlib/tests/lib.rs)"]:::consumer

        subgraph "Examples / Binaries"
            direction TB
            ExampleStdBin["example.rs\n(alloc-stdlib/src/bin/example.rs)"]:::consumer
            TestStdBin["tests.rs\n(alloc-stdlib/src/bin/tests.rs)"]:::consumer
        end
    end

    subgraph "Memory Sources"
        direction TB
        StackBuffer["Stack Buffer"]:::external
        HeapBox["Heap (Box)"]:::external
        CHeap["C Heap (calloc/free)"]:::external
        GlobalBuffer["Global Static Buffer"]:::external
    end

    FeatureStd["std feature flag"]:::external

    Example1 -->|"uses macros"| MacrosMod
    ExampleHeapBin -->|"uses macros"| MacrosMod
    ExampleTestsBin -->|"uses macros"| MacrosMod
    MacrosMod --> IndexMacro
    IndexMacro --> GeneratedAllocator
    GeneratedAllocator --> AllocatorTrait
    AllocatorTrait --> StackAllocator
    AllocatorTrait --> HeapAlloc
    AllocatorTrait --> InitHelpers
    AllocatorTrait --> CallocAllocator["CallocAllocatedFreelist"]:::strategy
    AllocatorTrait --> GlobalAllocator["GlobalAllocatedFreelist"]:::strategy

    StackAllocator --> StackBuffer
    HeapAlloc --> HeapBox
    CallocAllocator --> CHeap
    GlobalAllocator --> GlobalBuffer

    FeatureStd --> ALLOC_STDLIB
    ALLOC_STDLIB --> StdAllocStd
    ALLOC_STDLIB --> HeapAllocStd
    ALLOC_STDLIB --> TestStd
    ALLOC_STDLIB --> TestsLibStd
    ExampleStdBin --> ALLOC_STDLIB
    TestStdBin --> ALLOC_STDLIB

    click CrateRoot "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/Cargo.toml"
    click AllocatorTrait "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/allocator.rs"
    click StackAllocator "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/stack_allocator.rs"
    click HeapAlloc "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/std_alloc.rs"
    click InitHelpers "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/init.rs"
    click MacrosMod "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/allocated_memory/mod.rs"
    click IndexMacro "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/allocated_memory/index_macro.rs"
    click Example1 "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/bin/example.rs"
    click ExampleHeapBin "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/bin/heap_alloc.rs"
    click ExampleTestsBin "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/bin/tests.rs"
    click IntegrationTests "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/src/tests.rs"
    click ALLOC_STDLIB "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/Cargo.toml"
    click ALLOC_STDLIB "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/src/lib.rs"
    click StdAllocStd "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/src/std_alloc.rs"
    click HeapAllocStd "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/src/heap_alloc.rs"
    click TestStd "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/src/test.rs"
    click TestsLibStd "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/tests/lib.rs"
    click ExampleStdBin "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/src/bin/example.rs"
    click TestStdBin "https://github.com/dropbox/rust-alloc-no-stdlib/blob/master/alloc-stdlib/src/bin/tests.rs"

    classDef crate fill:#D6EAF8,stroke:#3498DB
    classDef core fill:#D5F5E3,stroke:#27AE60
    classDef macro fill:#FCF3CF,stroke:#F1C40F
    classDef strategy fill:#FADBD8,stroke:#E74C3C
    classDef consumer fill:#F2F3F4,stroke:#95A5A6
    classDef external fill:#EBEDEF,stroke:#85929E
```
