Struct BufferPool 

pub struct BufferPool { /* private fields */ }

Thread-safe pool of pre-allocated pinned buffers.

Pre-allocates all buffers during construction and pins them in memory, making them immediately ready for io_uring operations. This eliminates allocation overhead and ensures predictable performance.

Thread Safety

BufferPool is Send and Sync - internal synchronization is handled through a Mutex protecting the pool state.

Memory Management

All buffers are pre-allocated and remain allocated for the pool’s lifetime. This provides predictable memory usage but requires careful sizing.

Examples

use safer_ring::pool::BufferPool;

let pool = BufferPool::new(10, 4096);
if let Some(buffer) = pool.try_get().unwrap() {
    // Use buffer for I/O operations
    // Buffer automatically returns to pool on drop
}

Implementations

impl BufferPool

pub fn new(capacity: usize, buffer_size: usize) -> Self

Create a new buffer pool with specified capacity and buffer size.

All buffers are pre-allocated and pinned during construction.

Arguments

• capacity - Number of buffers to pre-allocate (must be > 0)
• buffer_size - Size of each buffer in bytes (must be > 0)

Panics

Panics if capacity or buffer_size is zero.

pub fn with_factory<F>(capacity: usize, buffer_factory: F) -> Self

where F: FnMut() -> PinnedBuffer<[u8]>,

Create a buffer pool with custom buffer initialization.

Allows more control over buffer initialization, such as pre-filling buffers with specific patterns.

Arguments

• capacity - Number of buffers to create
• buffer_factory - Closure that creates each buffer

Panics

Panics if buffers have inconsistent sizes.

pub fn try_get(&self) -> Result<Option<PooledBuffer>>

Try to get a buffer from the pool.

Returns Some(PooledBuffer) if available, None if pool is empty. Never blocks and never allocates new buffers.

pub fn try_get_fast(&self) -> Result<Option<PooledBuffer>>

Fast path buffer acquisition with minimal locking.

This is an optimized version that uses atomic operations where possible to reduce lock contention in high-throughput scenarios.

pub fn get(&self) -> Option<PooledBuffer>

Get a buffer from the pool.

Returns Some(PooledBuffer) if available, None if pool is empty. This is a convenience method that unwraps the Result from try_get.

pub fn get_blocking(&self) -> Result<PooledBuffer>

Get a buffer from the pool, blocking until one becomes available.

This method blocks the current thread until a buffer is returned. Uses exponential backoff to reduce CPU usage while waiting.

Performance Note

For high-performance applications, consider using try_get() in a loop with your own scheduling strategy rather than this blocking method.

pub fn capacity(&self) -> usize

Get the total capacity of the pool.

This is a lock-free operation since capacity is immutable.

pub fn available(&self) -> Result<usize>

Get the number of available buffers.

pub fn in_use(&self) -> Result<usize>

Get the number of buffers currently in use.

pub fn buffer_size(&self) -> usize

Get the size of each buffer in the pool.

This is a lock-free operation since buffer size is immutable.

pub fn stats(&self) -> PoolStats

Get comprehensive statistics about the pool.

Returns detailed information about pool usage and allocation patterns. Takes a single lock to ensure all statistics are consistent.

pub fn is_empty(&self) -> Result<bool>

Check if the pool is empty (no available buffers).

pub fn is_full(&self) -> Result<bool>

Check if the pool is full (all buffers available).

pub fn snapshot(&self) -> Result<(usize, usize, bool, bool)>

Get a snapshot of current pool state in a single lock operation.

More efficient than calling multiple methods separately when you need multiple pieces of information about the pool state.

Trait Implementations

impl Send for BufferPool

impl Sync for BufferPool