fastalloc/
lib.rs

1//! # fastalloc
2//!
3//! A high-performance memory pooling library for Rust with type-safe handles and zero-cost abstractions.
4//!
5//! **Version 1.0** - Production-ready stable release with comprehensive testing and battle-tested API.
6//!
7//! ## Overview
8//!
9//! `fastalloc` provides memory pools that allow you to reuse allocations efficiently, reducing
10//! allocation overhead and improving cache locality. It's designed for use cases where objects
11//! are frequently created and destroyed, such as:
12//!
13//! - Game development (entities, particles, physics objects)
14//! - Real-time systems (audio processing, robotics)
15//! - High-performance servers (connection pooling, request handling)
16//! - Data processing (temporary objects in hot paths)
17//! - Scientific computing (matrices, particles, graph nodes)
18//!
19//! ## Features
20//!
21//! - **Multiple pool types**: Fixed-size, growing, thread-local, and thread-safe pools
22//! - **Type-safe handles**: RAII-based handles that automatically return objects to the pool
23//! - **Flexible configuration**: Builder pattern with extensive customization options
24//! - **Multiple allocation strategies**: Stack (LIFO), free-list, and bitmap allocators
25//! - **Optional statistics**: Track allocation patterns and pool usage (with `stats` feature)
26//! - **no_std support**: Works in embedded and bare-metal environments
27//!
28//! ## Quick Start
29//!
30//! ```rust
31//! use fastalloc::{FixedPool, PoolConfig};
32//!
33//! // Create a pool of 1000 integers
34//! let pool = FixedPool::<i32>::new(1000).unwrap();
35//!
36//! // Allocate from the pool
37//! let mut handle = pool.allocate(42).unwrap();
38//!
39//! // Use the value
40//! assert_eq!(*handle, 42);
41//! *handle = 100;
42//! assert_eq!(*handle, 100);
43//!
44//! // Automatically returned to pool when handle is dropped
45//! drop(handle);
46//! ```
47//!
48//! ## Builder Configuration
49//!
50//! ```rust
51//! use fastalloc::{PoolConfig, GrowthStrategy};
52//!
53//! let config = PoolConfig::builder()
54//!     .capacity(1000)
55//!     .max_capacity(Some(10000))
56//!     .growth_strategy(GrowthStrategy::Exponential { factor: 2.0 })
57//!     .alignment(64) // Cache-line aligned
58//!     .pre_initialize(true)
59//!     .build()
60//!     .unwrap();
61//! ```
62//!
63//! ## Performance
64//!
65//! Typical performance characteristics:
66//! - Fixed pool allocation: < 20ns per object
67//! - Deallocation: < 10ns per object
68//! - Memory overhead: < 5% for pools over 1000 objects
69//! - Thread-safe pool: < 100ns with moderate contention
70//!
71//! ## Safety
72//!
73//! This crate minimizes the use of `unsafe` code and leverages Rust's ownership system
74//! to prevent common memory safety issues like use-after-free and double-free.
75//! Debug builds include additional runtime checks for:
76//! - Double-free detection
77//! - Leak detection
78//! - Pool exhaustion warnings
79
80#![cfg_attr(not(feature = "std"), no_std)]
81#![cfg_attr(docsrs, feature(doc_cfg))]
82#![warn(missing_docs, rust_2018_idioms)]
83#![allow(clippy::module_inception)]
84
85extern crate alloc;
86
87#[cfg(feature = "std")]
88extern crate std;
89
90// Core modules
91pub mod config;
92pub mod error;
93pub mod handle;
94pub mod pool;
95pub mod traits;
96
97// Internal modules
98mod allocator;
99mod utils;
100
101// Optional modules
102#[cfg(feature = "stats")]
103#[cfg_attr(docsrs, doc(cfg(feature = "stats")))]
104pub mod stats;
105
106// Re-exports for convenience
107pub use config::{GrowthStrategy, InitializationStrategy, PoolConfig};
108pub use error::{Error, Result};
109pub use handle::{OwnedHandle, SharedHandle, WeakHandle};
110pub use pool::{FixedPool, GrowingPool};
111pub use traits::Poolable;
112
113#[cfg(feature = "std")]
114pub use pool::{ThreadLocalPool, ThreadSafePool};
115
116#[cfg(all(feature = "std", feature = "lock-free"))]
117#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "lock-free"))))]
118pub use pool::LockFreePool;
119
120#[cfg(feature = "stats")]
121pub use stats::{PoolStatistics, StatisticsCollector};
122
123// Prelude for convenient imports
124pub mod prelude {
125    //! Convenient re-exports of commonly used types
126    
127    pub use crate::config::{GrowthStrategy, InitializationStrategy, PoolConfig};
128    pub use crate::error::{Error, Result};
129    pub use crate::handle::{OwnedHandle, SharedHandle, WeakHandle};
130    pub use crate::pool::{FixedPool, GrowingPool};
131    pub use crate::traits::Poolable;
132    
133    #[cfg(feature = "std")]
134    pub use crate::pool::{ThreadLocalPool, ThreadSafePool};
135    
136    #[cfg(all(feature = "std", feature = "lock-free"))]
137    pub use crate::pool::LockFreePool;
138    
139    #[cfg(feature = "stats")]
140    pub use crate::stats::{PoolStatistics, StatisticsCollector};
141}
142
143// Provide Poolable implementations for common types
144impl Poolable for i32 {}
145impl Poolable for i64 {}
146impl Poolable for u8 {}
147impl Poolable for u32 {}
148impl Poolable for u64 {}
149impl Poolable for u128 {}
150impl Poolable for f32 {}
151impl Poolable for f64 {}
152impl Poolable for bool {}
153impl Poolable for String {}
154impl<T: Poolable> Poolable for alloc::vec::Vec<T> {}
155impl<T: Poolable> Poolable for alloc::boxed::Box<T> {}
156impl<T: Poolable> Poolable for Option<T> {}
fastalloc/lib.rs

fastalloc/
lib.rs
