How antoniosarosi/rulloc works
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