NUMAlloc

A blazing-fast, NUMA-aware memory allocator written in pure Rust.

NUMAlloc is a drop-in replacement for the global allocator, purpose-built for Non-Uniform Memory Access (NUMA) machines. It pins threads and memory to NUMA nodes, routes freed objects back to their origin node, and shares huge pages incrementally -- delivering fewer remote memory accesses, fewer TLB misses, and lower latency than general-purpose allocators.

Note: This project has not been tested in production. Any feedback is welcome — please use with caution.

Features

• Zero-cost NUMA awareness - O(1) origin-node lookup via pointer arithmetic, no syscalls on the hot path
• Origin-aware deallocation - freed objects return to their origin node's freelist, eliminating remote reuse
• Lock-free concurrency - Treiber stacks with ABA-safe generation tags for inter-thread communication
• Incremental huge page sharing - threads on the same node share 2 MB transparent huge pages in 32 KB–256 KB increments
• Memory safe - built with Rust's ownership model; every unsafe block is documented with safety invariants
• Minimal dependencies - only libc for POSIX syscalls, no proc macros, no heavy frameworks
• Drop-in GlobalAlloc - one line to replace your allocator

Quick Start

Add to your Cargo.toml:

[dependencies]
numalloc = "0.1"

Set as global allocator:

use numalloc::NumaAlloc;

#[global_allocator]
static ALLOC: NumaAlloc = NumaAlloc::new();

fn main() {
    // All allocations now go through NUMAlloc.
    let v: Vec<u64> = vec![1, 2, 3];
    println!("{v:?}");
}

Architecture

NUMAlloc uses a five-layer allocation hierarchy, from fastest to slowest:

graph LR
    A["Thread Cache<br/>(lock-free)"] --> B["Node Heap<br/>(lock-free CAS)"]
    B --> C["Region<br/>(atomic bump)"]
    C --> D["Large Cache<br/>(per-thread)"]
    D --> E["OS mmap"]

Allocation path (small objects, <= 256 KB)

graph TD
    A["malloc(size)"] --> B["Per-Thread Freelist"]
    B -- hit --> C["return pointer<br/>(zero synchronization)"]
    B -- miss --> D["Per-Node Treiber Stack"]
    D -- hit --> E["batch-pop up to 64 objects,<br/>return one"]
    D -- miss --> F["Region Bump Allocator"]
    F --> G["carve bag (32 KB–256 KB),<br/>fill freelist, return one"]

Allocation path (large objects, > 256 KB)

graph TD
    A["malloc(size)"] --> B["Per-Thread Large Cache"]
    B -- hit --> C["reuse cached mmap region<br/>(~7.5 ns)"]
    B -- miss --> D["OS mmap"]
    D --> E["fresh mapping,<br/>mbind to thread's node"]

Deallocation path

graph TD
    A["free(ptr)"] --> B["Compute origin node<br/>(ptr - base) / region_size<br/>O(1), no syscall"]
    B --> C{"Object type?"}
    C -- "small, local" --> D["push to per-thread freelist<br/>(no locks)"]
    C -- "small, remote" --> E["push to origin node's<br/>Treiber stack (lock-free CAS)"]
    C -- "large (> 256KB)" --> F["cache mmap region for reuse<br/>(evict old if full)"]

Heap layout

A single contiguous virtual region is mapped at init and divided equally among NUMA nodes. Each sub-region is bound to its physical node via mbind. This design enables origin-node identification through simple integer division on any pointer.

block-beta
    columns 8
    block:n0["Node 0"]:2
        s0["small"]
        b0["big"]
    end
    block:n1["Node 1"]:2
        s1["small"]
        b1["big"]
    end
    block:n2["Node 2"]:2
        s2["small"]
        b2["big"]
    end
    block:nN["Node N"]:2
        sN["small"]
        bN["big"]
    end
    bp0["bpSmall"] space bp1["bpSmall"] space bp2["bpSmall"] space bpN["bpSmall"] space
    bp0 --> s0
    bp1 --> s1
    bp2 --> s2
    bpN --> sN

For the full design document with Mermaid diagrams and benchmark details, see docs/architecture_design.md.

Benchmarks

Single-threaded alloc+dealloc (steady state, lower is better):

Bulk alloc+free (1000 items, single-threaded, lower is better):

Multi-threaded alloc+dealloc (10,000 ops/thread, lower is better):

Axum HTTP server benchmark (4 threads, 100 connections, 10s, higher is better):

Run benchmarks yourself with cargo bench or cd examples/axum-bench && bash bench.sh.

Design Principles

• Hot path = zero synchronization. Per-thread freelists are single-owner, no atomics, no syscalls.
• Lock-free over locks. Shared per-node heaps use Treiber stacks with CAS, not mutexes.
• Batch everything. Drain and refill operations move objects in bulk via chain-insert, amortizing CAS cost.
• Adaptive caching. Per-thread cache thresholds scale with object size -- small objects cache up to 2048 items, large objects cache 64.
• Intrusive data structures. Free blocks store their next pointer in the freed memory itself -- zero extra overhead.
• Explicit safety. Every unsafe block carries a // SAFETY: comment. NonNull<T> over *mut T. UnsafeCell for interior mutability.

When to Use NUMAlloc

Good fit:

• Multi-threaded server applications on NUMA hardware (2+ sockets)
• Workloads with many small allocations and high thread counts
• Environments with transparent huge pages enabled

Not ideal for:

• Single-threaded applications
• Heavy cross-node producer-consumer patterns
• Asymmetric or heterogeneous memory topologies

Contributing

Contributions are welcome! Please ensure your changes pass:

cargo fmt
cargo clippy -- -D warnings
cargo test

License

See LICENSE for details.

References

Based on: Yang et al., "NUMAlloc: A Faster NUMA Memory Allocator," ISMM 2023, ACM.