nexus-slab

A high-performance slab allocator for stable memory addresses without heap allocation overhead.

What Is This?

nexus-slab is a custom allocator pattern—not a replacement for Rust's global allocator, but a specialized allocator for specific use cases where you need:

• Stable memory addresses - pointers remain valid until explicitly freed
• Box-like semantics without Box - RAII ownership with pre-allocated backing storage
• Node-based data structures - linked lists, trees, graphs with internal pointers
• Predictable tail latency - no reallocation spikes during growth

Think of Slot<T> as analogous to Box<T>: an owning handle that provides access to a value and deallocates on drop. The difference is that Box allocates from the heap on every call, while Slot allocates from a pre-allocated slab—making allocation O(1) with no syscalls.

Quick Start

use nexus_slab::create_allocator;

// Define an allocator for your type
create_allocator!(order_alloc, Order);

// Initialize at startup (once per thread)
order_alloc::init().bounded(1024).build();

// Insert returns an 8-byte RAII Slot
let slot = order_alloc::insert(Order::new());
assert_eq!(slot.price, 100);

// Modify through the slot
slot.get_mut().quantity = 50;

// Slot auto-deallocates on drop
drop(slot);
assert_eq!(order_alloc::len(), 0);

Performance

All measurements in CPU cycles. See BENCHMARKS.md for methodology.

Macro API vs slab crate (p50)

Key insight: The TLS lookup adds ~4 cycles to INSERT/REMOVE, but access operations (GET/REPLACE) have zero overhead because Slot caches the pointer. For access-heavy workloads, this is a net win.

Full Lifecycle Cost

One cycle per object lifecycle for the ergonomics of a global allocator pattern.

vs Box (Isolation Advantage)

The killer feature: slab is isolated from the global allocator. In production, Box::new() shares malloc with everything else. Your slab is yours alone.

Hot Cache (realistic steady-state)

Cold Cache (single-op, true first-access latency)

Cold Cache (batched burst pattern)

Key findings:

• Hot cache: Slab 1.7x faster at p50 for 4096B (62 vs 105 cycles)
• Cold single-op: Slab 27% faster at p50 for 256B (122 vs 166 cycles)
• Cold batched 4096B: Slab 1.5x faster at p50 (120 vs 181 cycles)
• Tail latency: Slab consistently 1.5-2x better at p99

See BENCHMARKS.md for full methodology and stress test results.

Use Cases

Node-Based Data Structures

use nexus_slab::{create_allocator, Key};

struct Node {
    value: i32,
    next: Key,  // 4 bytes, not 8 for Option<Box<Node>>
    prev: Key,
}

create_allocator!(node_alloc, Node);

fn build_list() {
    node_alloc::init().bounded(1000).build();

    let head = node_alloc::insert(Node {
        value: 1,
        next: Key::NONE,
        prev: Key::NONE,
    });

    // Keys are stable - safe to store in other nodes
    let head_key = head.key();

    let tail = node_alloc::insert(Node {
        value: 2,
        next: Key::NONE,
        prev: head_key,
    });

    head.get_mut().next = tail.key();
}

Stable Memory Addresses

create_allocator!(buffer_alloc, [u8; 4096]);

fn get_stable_buffer() -> *const u8 {
    buffer_alloc::init().bounded(100).build();

    let slot = buffer_alloc::insert([0u8; 4096]);
    let ptr = slot.as_ptr() as *const u8;

    // Pointer remains valid as long as slot exists
    // No reallocation, no movement

    let _ = slot.leak();  // Keep alive, return key for later cleanup
    ptr
}

Key Serialization

Keys can be converted to/from u32 for external storage:

let slot = my_alloc::insert(value);
let key = slot.leak();

// Serialize
let raw: u32 = key.into_raw();
store_somewhere(raw);

// Deserialize
let raw = load_from_somewhere();
let key = Key::from_raw(raw);

// Access (caller must ensure validity)
let value = unsafe { my_alloc::get_unchecked(key) };

Warning: Keys are simple indices with no generation counter. If you store keys externally (databases, wire protocols), you must ensure the key is still valid before use. For wire protocols, prefer authoritative external identifiers (exchange order IDs, database primary keys) and use the slab key only for internal indexing.

API

Allocator Module (generated by create_allocator!)

Slot (8 bytes)

Slot implements Deref and DerefMut for ergonomic access.

Key (4 bytes)

Builder Pattern

// Bounded: fixed capacity, returns None when full
my_alloc::init()
    .bounded(1024)
    .build();

// Unbounded: grows by adding chunks (no copying)
my_alloc::init()
    .unbounded()
    .chunk_capacity(4096)  // slots per chunk
    .capacity(10_000)      // pre-allocate
    .build();

Bounded vs Unbounded

Use bounded when capacity is known—it's faster and fully deterministic.

Use unbounded when you need overflow headroom without Vec reallocation spikes.

Architecture

Slot Design

Each Slot is 8 bytes (single pointer). The VTable for slab operations is stored in thread-local storage:

Slot (8 bytes):
┌─────────────────────────┐
│ *mut SlotCell<T>        │  ← Direct pointer to value
└─────────────────────────┘

TLS (per allocator):
┌─────────────────────────┐
│ *const VTable<T>        │  ← Cached for fast access
└─────────────────────────┘

This design gives:

• 8-byte handles (vs 16+ for pointer+vtable designs)
• Zero-cost access (GET/REPLACE don't touch TLS)
• RAII semantics (drop returns slot to freelist)

Memory Layout

Slab (contiguous allocation):
┌──────────────────────────────────────────┐
│ SlotCell 0: [stamp: u64][value: T]       │
│ SlotCell 1: [stamp: u64][value: T]       │
│ ...                                       │
│ SlotCell N: [stamp: u64][value: T]       │
└──────────────────────────────────────────┘

No Generational Indices

Keys are simple indices. This is intentional—see the Key documentation for rationale.

TL;DR: Your data has authoritative external identifiers (exchange order IDs, database keys). You validate against those anyway. Generational indices add ~8 cycles to catch bugs that domain validation already catches.

Thread Safety

Each thread has its own allocator instance. The allocator is !Send and !Sync.

Do not store Slot in thread_local!. Rust drops stack variables before TLS, so stack slots drop correctly. But if both Slot and the slab are in TLS, drop order is unspecified.

Direct API (Advanced)

For cases where the macro API doesn't fit (multiple slabs, dynamic creation), use the direct API:

use nexus_slab::bounded::BoundedSlab;

let slab = BoundedSlab::with_capacity(1024);
let slot = slab.insert(42).unwrap();
assert_eq!(*slot.get(), 42);

See the bounded and unbounded modules.

License

MIT OR Apache-2.0