Struct BoundedSlab 

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

Fixed-capacity slab allocator for manual memory management.

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

Safety Contract

Construction is unsafe because it opts you into manual memory management. By creating a slab, you accept these invariants:

• Free from the correct slab. Passing a Slot to a different slab’s free() is undefined behavior — it corrupts the freelist. In debug builds, this is caught by debug_assert!.
• Free everything you allocate. Dropping the slab does NOT drop values in occupied slots. Unfreed slots leak silently.
• Single-threaded. The slab is !Send and !Sync.

Why free() is safe

The safety contract is accepted once, at construction. After that:

• Slot is move-only (no Copy, no Clone) — double-free is prevented by the type system.
• free() consumes the Slot — the handle cannot be used after.
• Cross-slab misuse is the only remaining hazard, and it was accepted as the caller’s responsibility at construction time.

Implementations

impl<T> Slab<T>

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.

pub fn capacity(&self) -> usize

Returns the capacity.

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);
}

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

Allocates a slot and writes the value.

Panics

Panics if the slab is full.

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.

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.

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

Frees a slot and returns the value without dropping it.

Consumes the handle — the slot cannot be used after this call.

Trait Implementations

impl<T> BoundedStore for Slab<T>

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

Attempts to allocate a slot with the given value.

impl<T> Debug for Slab<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> SlabStore for Slab<T>

type Item = T

The type stored in each slot.

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

Allocates a slot with the given value.

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

Drops the value and returns the slot to the freelist.

fn take(&self, slot: Slot<T>) -> T

Moves the value out and returns the slot to the freelist.