Struct BufferPool 

pub struct BufferPool { /* private fields */ }

A pool of reusable, aligned buffers.

Buffers are organized into power-of-two size classes. When a buffer is requested, the smallest size class that fits is used. Buffers are automatically returned to the pool when dropped.

Alignment

Buffer alignment is guaranteed only at the base pointer (when cursor == 0). After calling Buf::advance, the pointer returned by as_mut_ptr() may no longer be aligned. For direct I/O operations that require alignment, do not advance the buffer before use.

Implementations

impl BufferPool

pub fn try_alloc(&self, capacity: usize) -> Result<IoBufMut, PoolError>

Attempts to allocate a pooled buffer.

Unlike Self::alloc, this method does not fall back to untracked allocation.

The returned buffer has len() == 0 and capacity() >= capacity.

Initialization

The returned buffer contains uninitialized memory. Do not read from it until data has been written.

Errors

• PoolError::Oversized: capacity exceeds max_size
• PoolError::Exhausted: Pool exhausted for required size class

pub fn alloc(&self, capacity: usize) -> IoBufMut

Allocates a buffer with capacity for at least capacity bytes.

The returned buffer has len() == 0 and capacity() >= capacity, matching the semantics of IoBufMut::with_capacity and bytes::BytesMut::with_capacity. Use BufMut::put_slice or other BufMut methods to write data to the buffer.

If the pool can provide a buffer (capacity within limits and pool not exhausted), returns a pooled buffer that will be returned to the pool when dropped. Otherwise, falls back to an untracked aligned heap allocation that is deallocated when dropped.

Use Self::try_alloc if you need pooled-only behavior.

Initialization

The returned buffer contains uninitialized memory. Do not read from it until data has been written.

pub unsafe fn alloc_len(&self, len: usize) -> IoBufMut

Allocates a buffer and sets its readable length to len without initializing bytes.

Equivalent to Self::alloc followed by IoBufMut::set_len.

Safety

Caller must ensure all bytes are initialized before any read operation.

pub fn try_alloc_zeroed(&self, len: usize) -> Result<IoBufMut, PoolError>

Attempts to allocate a zero-initialized pooled buffer.

Unlike Self::alloc_zeroed, this method does not fall back to untracked allocation.

The returned buffer has len() == len and capacity() >= len.

Initialization

Bytes in 0..len are initialized to zero. Bytes in len..capacity may be uninitialized.

Errors

• PoolError::Oversized: len exceeds max_size
• PoolError::Exhausted: Pool exhausted for required size class

pub fn alloc_zeroed(&self, len: usize) -> IoBufMut

Allocates a zero-initialized buffer with readable length len.

The returned buffer has len() == len and capacity() >= len.

If the pool can provide a buffer (len within limits and pool not exhausted), returns a pooled buffer that will be returned to the pool when dropped. Otherwise, falls back to an untracked aligned heap allocation that is deallocated when dropped.

Use this for read APIs that require an initialized &mut [u8]. This avoids unsafe set_len at callsites.

Use Self::try_alloc_zeroed if you need pooled-only behavior.

Initialization

Bytes in 0..len are initialized to zero. Bytes in len..capacity may be uninitialized.

pub fn config(&self) -> &BufferPoolConfig

Returns the pool configuration.

Trait Implementations

impl Clone for BufferPool

fn clone(&self) -> BufferPool

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BufferPool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.