Struct BoundedSlab

Source

pub struct BoundedSlab<T> { /* private fields */ }

Expand description

Fixed-capacity slab allocator for manual memory management.

Construction is unsafe — by creating a slab, you accept the contract:

Free everything you allocate. Dropping the slab does NOT drop values in occupied slots. Unfree’d slots leak silently.
Free from the same slab. Passing a Slot to a different slab’s free() corrupts the freelist.
Don’t share across threads. The slab is !Send and !Sync.

In practice, most systems have one slab per type in thread_local! storage. Cross-slab free is a programming error caught by debug_assert.

Uses pointer-based freelist for O(1) allocation. ~20-24 cycle operations.

§Const Construction

Supports const construction via new() followed by runtime initialization via init(). This enables use with thread_local! using the const { } block syntax for zero-overhead TLS access.

use nexus_slab::bounded::Slab;

struct MyType(u64);

// SAFETY: single slab per type, freed before thread exit
thread_local! {
    static SLAB: Slab<MyType> = const { unsafe { Slab::new() } };
}

// Later, at runtime:
SLAB.with(|s| unsafe { s.init(1024) });

For direct usage, prefer with_capacity().

Implementations§

Source §

impl<T> Slab<T>

Source

pub const unsafe fn new() -> Slab<T>

Creates an empty, uninitialized slab.

This is a const function that performs no allocation. Call init() to allocate storage before use.

§Safety

See struct-level safety contract.

§Example

use nexus_slab::bounded::Slab;

// SAFETY: single slab per type, freed before thread exit
thread_local! {
    static SLAB: Slab<u64> = const { unsafe { Slab::new() } };
}

Source

pub unsafe fn with_capacity(capacity: usize) -> Slab<T>

Creates a new slab with the given capacity.

§Safety

See struct-level safety contract.

§Panics

Panics if capacity is zero.

Source

pub unsafe fn init(&self, capacity: usize)

Initializes the slab with the given capacity.

This allocates slot storage and builds the freelist. Must be called exactly once before any allocations.

§Safety

See struct-level safety contract.

§Panics

Panics if the slab is already initialized (capacity > 0)
Panics if capacity is zero

Source

pub fn is_initialized(&self) -> bool

Returns true if the slab has been initialized.

Source

pub fn capacity(&self) -> usize

Returns the capacity.

Source

pub fn claim(&self) -> Option<Claim<'_, T>>

Claims a slot from the freelist without writing a value.

Returns None if the slab is full. The returned Claim must be consumed via Claim::write() to complete the allocation.

This two-phase allocation enables placement new optimization: the value can be constructed directly into the slot memory.

§Example

use nexus_slab::bounded::Slab;

// SAFETY: caller guarantees slab contract (see struct docs)
let slab = unsafe { Slab::with_capacity(10) };
if let Some(claim) = slab.claim() {
    let slot = claim.write(42u64);
    assert_eq!(*slot, 42);
    slab.free(slot);
}

Source

pub fn alloc(&self, value: T) -> Slot<T>

Allocates a slot and writes the value.

§Panics

Panics if the slab is full.

Source

pub fn try_alloc(&self, value: T) -> Result<Slot<T>, Full<T>>

Tries to allocate a slot and write the value.

Returns Err(Full(value)) if the slab is at capacity.

Source

pub fn free(&self, slot: Slot<T>)

Frees a slot, dropping the value and returning storage to the freelist.

Consumes the handle — the slot cannot be used after this call. The caller’s safety obligation (free from the correct slab) was accepted at construction time.

Source