Struct LockFreeStack 

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

Lock-free stack for object pooling.

Safety

This implementation uses a pre-allocated array of slots with a generation counter packed in an AtomicU64 to prevent ABA problems and use-after-free without blocking.

Capacity

The slot array is fixed at construction; Self::push returns the item back when every slot is occupied. Use Self::with_capacity to size the stack; Self::new uses DEFAULT_STACK_CAPACITY.

Performance Characteristics

• Push: O(1) amortized, < 20ns
• Pop: O(1) amortized, < 30ns
• Thread-safe: All operations are lock-free

Implementations

impl<T> LockFreeStack<T>

pub fn new() -> LockFreeStack<T>

Create a new empty lock-free stack with DEFAULT_STACK_CAPACITY slots.

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

Create a new empty lock-free stack with exactly capacity slots.

A capacity of 0 yields a stack whose push always returns the item back.

Panics

Panics if capacity >= u32::MAX (the sentinel index must stay unused).

pub fn push(&self, item: T) -> Result<(), T>

Push an item onto the stack.

Errors

Returns Err(item) — handing the value back to the caller — when every slot is occupied. The item is never silently dropped.

pub fn pop(&self) -> Option<T>

Pop an item from the stack.

pub fn len(&self) -> usize

Get the current length of the stack.

pub fn is_empty(&self) -> bool

Check if the stack is empty.

pub fn capacity(&self) -> usize

Get the fixed slot capacity of the stack.

Trait Implementations

impl<T> Default for LockFreeStack<T>

fn default() -> LockFreeStack<T>

Returns the “default value” for a type.

impl<T> Drop for LockFreeStack<T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T> Send for LockFreeStack<T>

where T: Send,

impl<T> Sync for LockFreeStack<T>

where T: Send,