Crate fastalloc 

fastalloc

A memory pooling library for Rust with type-safe handles and RAII-based memory management.

Version 1.5.0 - Production-ready release with performance optimizations and comprehensive documentation.

Overview

fastalloc provides memory pools that allow you to reuse allocations efficiently, offering 1.3-1.4x faster allocation than standard heap with the key benefits of:

• Predictable latency: No allocation spikes or fragmentation slowdowns
• Cache locality: Objects stored contiguously improve cache hit rates
• Zero fragmentation: Eliminates long-term heap fragmentation
• Real-time guarantees: Bounded worst-case allocation time

Designed for use cases where objects are frequently created and destroyed:

• Game development (entities, particles, physics objects)
• Real-time systems (audio processing, robotics)
• High-performance servers (connection pooling, request handling)
• Embedded systems (constrained memory, no fragmentation)
• Scientific computing (matrices, particles, graph nodes)

Features

• Multiple pool types: Fixed-size, growing, thread-local, and thread-safe pools
• Type-safe handles: RAII-based handles that automatically return objects to the pool
• Flexible configuration: Builder pattern with extensive customization options
• Multiple allocation strategies: Stack (LIFO), free-list, and bitmap allocators
• Optional statistics: Track allocation patterns and pool usage (with stats feature)
• no_std support: Works in embedded and bare-metal environments

Quick Start

use fastalloc::{FixedPool, PoolConfig};

// Create a pool of 1000 integers
let pool = FixedPool::<i32>::new(1000).unwrap();

// Allocate from the pool
let mut handle = pool.allocate(42).unwrap();

// Use the value
assert_eq!(*handle, 42);
*handle = 100;
assert_eq!(*handle, 100);

// Automatically returned to pool when handle is dropped
drop(handle);

Builder Configuration

use fastalloc::{PoolConfig, GrowthStrategy};

let config: PoolConfig<i32> = PoolConfig::builder()
    .capacity(1000)
    .max_capacity(Some(10000))
    .growth_strategy(GrowthStrategy::Exponential { factor: 2.0 })
    .alignment(64) // Cache-line aligned
    .pre_initialize(true)
    .build()
    .unwrap();

Performance

Benchmark results (criterion.rs, release mode with LTO):

• Fixed pool allocation: ~3.5ns per object (1.3-1.4x faster than Box)
• Growing pool allocation: ~4.6ns per object
• Allocation reuse (LIFO): ~7.2ns per cycle

See BENCHMARKS.md for detailed methodology and results.

Safety

This crate minimizes the use of unsafe code and leverages Rust’s ownership system to prevent common memory safety issues:

• ✅ Use-after-free: Handles maintain exclusive ownership via borrow checker
• ✅ Double-free: Allocator tracks which slots are in use (bitmap in debug mode)
• ✅ Memory leaks: RAII ensures objects are returned to pool when dropped
• ✅ Data races: Thread-safe types use proper synchronization (Arc + Mutex)

Debug builds include additional runtime checks:

• Double-free detection (O(1) bitmap check)
• Index bounds validation
• Allocation state consistency

See SAFETY.md for detailed safety guarantees and unsafe code documentation.

Documentation

• API Documentation - Complete API reference
• BENCHMARKS.md - Benchmark results, methodology, and library comparisons
• SAFETY.md - Safety guarantees, unsafe code, and fragmentation behavior
• ARCHITECTURE.md - Internal design and memory overhead analysis
• ERROR_HANDLING.md - Pool exhaustion strategies and error recovery
• Examples - Working code examples for common use cases

Re-exports

pub use config::GrowthStrategy;

pub use config::InitializationStrategy;

pub use config::PoolConfig;

pub use error::Error;

pub use error::Result;

pub use handle::OwnedHandle;

pub use handle::SharedHandle;

pub use handle::WeakHandle;

pub use pool::FixedPool;

pub use pool::GrowingPool;

pub use traits::Poolable;

pub use pool::ThreadLocalPool;std

pub use pool::ThreadSafePool;std

pub use pool::LockFreePool;std and lock-free

pub use stats::PoolStatistics;stats

pub use stats::StatisticsCollector;stats

Modules

config

Configuration types for memory pools.

error

Error types for the fastalloc crate.

handle

Smart handles for pool-allocated objects.

pool

Memory pool implementations.

prelude

Convenient re-exports of commonly used types

statsstats

Statistics collection and reporting for memory pools.

traits

Traits for working with memory pools.