Struct PoolAllocator 

pub struct PoolAllocator<A: Allocator> { /* private fields */ }

A lock-free, fixed-size block allocator backed by a single pre-allocated slab.

At construction time the slab is divided into equal-sized blocks whose size is at least max(item_layout.size(), size_of::<FreeNode>()) and whose alignment is at least max(item_layout.align(), align_of::<FreeNode>()). All blocks are linked into a free-list; allocation atomically pops the head; deallocation atomically pushes to the head.

Constraints

• Allocations larger than block_layout.size() or with stricter alignment than block_layout.align() are rejected (return None).
• The pool has a fixed capacity; once all blocks are in use, allocation returns None.

Thread Safety

PoolAllocator is Sync + Send when the backing allocator is Sync + Send. Both alloc and dealloc use lock-free CAS loops.

Implementations

impl<A: Allocator> PoolAllocator<A>

pub fn new(backing: A, item_layout: Layout, capacity: usize) -> Option<Self>

Creates a new pool with capacity blocks sized for item_layout.

The effective block size is max(item_layout.size(), size_of::<FreeNode>()) padded to the effective alignment. Returns None if the backing allocator fails to allocate the slab.

Arguments

• backing — Allocator used to allocate and later free the slab.
• item_layout — Layout of the items that will be stored in the pool.
• capacity — Maximum number of live allocations the pool can hold.

pub fn typed<T>(backing: A, capacity: usize) -> Option<Self>

Convenience constructor that derives item_layout from the type T.

Equivalent to PoolAllocator::new(backing, Layout::new::<T>(), capacity).

Examples found in repository

examples/pool_string.rs (line 9)

fn main() {
    let sys = SystemAllocator;

    let pool = PoolAllocator::typed::<[u8; 128]>(&sys, 5).unwrap();

    let mut log = ExString::new(&pool);
    write!(log, "Status: {}, Code: {}", "OK", 200).unwrap();

    println!("Log message: {}", log.as_str());
    println!("Slots left in pool: {}", pool.free_count());
}

examples/full.rs (line 39)

fn main() {
    let sys = CountingAllocator::new(SystemAllocator);
    
    println!("=== ExBox & SystemAllocator ===");
    {
        let b = ExBox::new(42, &sys).expect("Failed to alloc Box");
        println!("Box value: {}", *b);
    }
    
    let stats = sys.stats();
    println!("Allocated: {} bytes", stats.bytes_allocated);
    println!("Deallocated: {} bytes", stats.bytes_freed);
    println!("Live bytes: {}\n", stats.bytes_live);

    println!("=== ExVec & Arena (Linear Allocation) ===");
    {
        let arena = ArenaAllocator::new(&sys);
        
        let mut v = ExVec::new(&arena);
        for i in 0..5 {
            v.push(i * 10);
        }
        println!("Vec: {:?}", v.as_slice());
        
        arena.reset();
        println!("Arena reset performed");
    }

    println!("\n=== ExString & Pool (Fixed Size Blocks) ===");
    {
        let pool = PoolAllocator::typed::<[u8; 64]>(&sys, 10)
            .expect("Failed to create Pool");
        
        let mut s = ExString::new(&pool);
        s.push_str("Hello from ZigZag!");
        
        println!("String in Pool: {}", s.as_str());
        println!("Pool free slots: {}", pool.free_count());
    }

    println!("\n=== Final Global Stats ===");
    let final_stats = sys.stats();
    println!("Total count of alloc() calls: {}", final_stats.allocs);
    println!("Total count of dealloc() calls: {}", final_stats.deallocs);
    println!("Total bytes allocated: {}", final_stats.bytes_allocated);
    println!("Total bytes freed: {}", final_stats.bytes_freed);
    println!("Current leak/live size: {} bytes", final_stats.bytes_live);
}

pub fn capacity(&self) -> usize

Returns the maximum number of blocks this pool can provide simultaneously.

pub fn block_layout(&self) -> Layout

Returns the padded layout of a single pool block.

pub fn free_count(&self) -> usize

Returns the number of blocks currently on the free-list.

This traverses the entire free-list and is O(free_count), so use only for diagnostics / debugging.

Examples found in repository

examples/pool_string.rs (line 15)

fn main() {
    let sys = SystemAllocator;

    let pool = PoolAllocator::typed::<[u8; 128]>(&sys, 5).unwrap();

    let mut log = ExString::new(&pool);
    write!(log, "Status: {}, Code: {}", "OK", 200).unwrap();

    println!("Log message: {}", log.as_str());
    println!("Slots left in pool: {}", pool.free_count());
}

examples/full.rs (line 46)

fn main() {
    let sys = CountingAllocator::new(SystemAllocator);
    
    println!("=== ExBox & SystemAllocator ===");
    {
        let b = ExBox::new(42, &sys).expect("Failed to alloc Box");
        println!("Box value: {}", *b);
    }
    
    let stats = sys.stats();
    println!("Allocated: {} bytes", stats.bytes_allocated);
    println!("Deallocated: {} bytes", stats.bytes_freed);
    println!("Live bytes: {}\n", stats.bytes_live);

    println!("=== ExVec & Arena (Linear Allocation) ===");
    {
        let arena = ArenaAllocator::new(&sys);
        
        let mut v = ExVec::new(&arena);
        for i in 0..5 {
            v.push(i * 10);
        }
        println!("Vec: {:?}", v.as_slice());
        
        arena.reset();
        println!("Arena reset performed");
    }

    println!("\n=== ExString & Pool (Fixed Size Blocks) ===");
    {
        let pool = PoolAllocator::typed::<[u8; 64]>(&sys, 10)
            .expect("Failed to create Pool");
        
        let mut s = ExString::new(&pool);
        s.push_str("Hello from ZigZag!");
        
        println!("String in Pool: {}", s.as_str());
        println!("Pool free slots: {}", pool.free_count());
    }

    println!("\n=== Final Global Stats ===");
    let final_stats = sys.stats();
    println!("Total count of alloc() calls: {}", final_stats.allocs);
    println!("Total count of dealloc() calls: {}", final_stats.deallocs);
    println!("Total bytes allocated: {}", final_stats.bytes_allocated);
    println!("Total bytes freed: {}", final_stats.bytes_freed);
    println!("Current leak/live size: {} bytes", final_stats.bytes_live);
}

pub unsafe fn dealloc_zeroed(&self, ptr: NonNull<u8>)

Zeroes the block at ptr and returns it to the pool.

Useful when blocks may contain sensitive data.

Safety

• ptr must have been obtained from this pool via alloc.
• ptr must not be used after this call.

pub unsafe fn wipe_slab(&self)

Zeroes the entire slab without modifying the free-list.

Intended for secure teardown. Do not call while any block is in use.

Safety

All blocks — including live ones — will have their bytes set to zero. Any live references into the pool will read garbage (all zeros).

Trait Implementations

impl<A: Allocator> Allocator for PoolAllocator<A>

unsafe fn alloc(&self, layout: Layout) -> Option<NonNull<u8>>

Pops one block from the free-list and returns a pointer to it.

Returns None if the pool is exhausted or if layout is too large / too strictly aligned for the pool’s block size.

Safety

• layout.size() must be ≤ block_layout.size().
• layout.align() must be ≤ block_layout.align().
• The caller must eventually call dealloc with the same pointer (and any layout whose size and align fit the pool).

unsafe fn dealloc(&self, ptr: NonNull<u8>, _layout: Layout)

Pushes a block back onto the free-list.

The _layout parameter is ignored; what matters is that ptr belongs to this pool’s slab.

Safety

• ptr must have been obtained from this pool via alloc.
• ptr must not be accessed after this call.
• Calling dealloc twice with the same pointer is undefined behaviour (double-free corrupts the free-list).

impl<A: Allocator> Drop for PoolAllocator<A>

fn drop(&mut self)

Returns the entire slab to the backing allocator.

impl<A: Allocator + Send> Send for PoolAllocator<A>

impl<A: Allocator + Sync> Sync for PoolAllocator<A>