Struct BoundedSlab 

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

Fixed-capacity slab allocator.

Uses pointer-based freelist for O(1) allocation.

Drop Behavior

Dropping a Slab does not drop values in occupied slots. SlotCell is a union, so the compiler cannot know which slots contain live values. The caller must free all outstanding RawSlot handles before dropping the slab, or the values will be leaked.

This is acceptable for the primary use case (TLS via thread_local!) where thread exit leaks all TLS storage anyway.

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.

thread_local! {
    static SLAB: Slab<MyType> = const { Slab::new() };
}

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

For direct usage, prefer with_capacity().

Implementations

impl<T> Slab<T>

pub const 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.

For direct usage, prefer with_capacity().

Example

// For use with thread_local! const initialization
thread_local! {
    static SLAB: Slab<u64> = const { Slab::new() };
}

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

Creates a new slab with the given capacity.

Panics

Panics if capacity is zero.

pub 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.

Panics

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

pub fn is_initialized(&self) -> bool

Returns true if the slab has been initialized.

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;

let slab = Slab::with_capacity(10);
if let Some(claim) = slab.claim() {
    let slot = claim.write(42u64);
    assert_eq!(*slot, 42);
    // SAFETY: slot was allocated from this slab
    unsafe { slab.free(slot) };
}

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

Allocates a slot and writes the value.

Panics

Panics if the slab is full.

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

Tries to allocate a slot and write the value.

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

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

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

Safety

• slot must have been allocated from this slab
• No references to the slot’s value may exist

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

Frees a slot and returns the value without dropping it.

Safety

• slot must have been allocated from this slab
• No references to the slot’s value may exist

impl<const N: usize> Slab<AlignedBytes<N>>

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

Inserts a value into the slab, returning a Slot handle.

Returns Err(value) if the slab is full.

Compile-Time Checks

Fails to compile if T is too large or too aligned for the slot.

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

where T: ?Sized,

Drops the value and frees the slot.

Handles both thin and fat pointers: extracts the data pointer for freeing regardless of whether T is Sized or dyn Trait.

Safety

• slot must have been allocated from this slab

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

Extracts the value and frees the slot (Sized only).

Safety

• slot must have been allocated from this slab

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

where T: ?Sized,

Frees the slot without dropping the value.

Use when the value has already been moved out or dropped.

Safety

• slot must have been allocated from this slab
• The value must already be dropped or moved out

Trait Implementations

impl<T> BoundedStore for Slab<T>

fn try_alloc(&self, value: T) -> Result<RawSlot<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> Default for Slab<T>

fn default() -> Slab<T>

Returns the “default value” for a type.

impl<T> SlabStore for Slab<T>

type Item = T

The type stored in each slot.

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

Allocates a slot with the given value.

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

Drops the value and returns the slot to the freelist.

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

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

unsafe fn free_ptr(&self, ptr: *mut SlotCell<T>)

Returns a slot to the freelist by raw pointer.