Struct BufferPool 

pub struct BufferPool { /* private fields */ }

A high-performance memory pool using buddy memory allocation.

The pool manages memory in 64 MiB blocks and supports allocation of buffers at four size levels: 1 MiB, 4 MiB, 16 MiB, and 64 MiB.

Thread Safety

The pool uses tokio::sync::Mutex for thread safety, making it suitable for use in both synchronous and asynchronous contexts.

Buffer Lifetime

Each allocated Buffer holds an Arc<BufferPool> reference, ensuring the pool remains valid for the lifetime of all buffers. When a buffer is dropped, its memory is immediately returned to the pool with O(1) complexity.

Example

use ruapc_bufpool::BufferPoolBuilder;

let pool = BufferPoolBuilder::new()
    .max_memory(128 * 1024 * 1024)
    .build();

// Allocate a 1 MiB buffer
let buffer = pool.allocate(1024 * 1024)?;
assert!(buffer.len() >= 1024 * 1024);

// Buffer is automatically returned when dropped
drop(buffer);

Implementations

impl BufferPool

pub fn new() -> Arc<Self>

Creates a new buffer pool with default settings.

This is equivalent to BufferPoolBuilder::new().build().

pub fn allocate(self: &Arc<Self>, size: usize) -> Result<Buffer>

Allocates a buffer of at least the specified size.

The returned buffer may be larger than requested, rounded up to the nearest allocation level (1 MiB, 4 MiB, 16 MiB, or 64 MiB).

This method blocks the current thread while waiting for the lock. For async contexts, use async_allocate instead.

Arguments

• size - The minimum size of the buffer in bytes.

Returns

Returns a Buffer on success, or an error if:

• The requested size is 0 or exceeds 64 MiB
• The memory limit has been reached
• Memory allocation fails

Errors

Returns an error if:

• size is 0 or exceeds 64 MiB (InvalidInput)
• Memory limit has been reached (OutOfMemory)
• Underlying allocator fails (OutOfMemory)

Panics

Panics if the internal mutex is poisoned (which only happens if another thread panicked while holding the lock).

Example

use ruapc_bufpool::BufferPoolBuilder;

let pool = BufferPoolBuilder::new().build();
let buffer = pool.allocate(2 * 1024 * 1024)?; // Request 2 MiB
assert!(buffer.len() >= 4 * 1024 * 1024); // Gets 4 MiB (next level up)

pub async fn async_allocate(self: &Arc<Self>, size: usize) -> Result<Buffer>

Allocates a buffer asynchronously.

This is the async version of allocate. If the memory limit has been reached, this method will wait for other buffers to be freed rather than returning an error.

Arguments

• size - The minimum size of the buffer in bytes.

Returns

Returns a Buffer on success, or an error if:

• The requested size is 0 or exceeds 64 MiB
• Memory allocation fails

Errors

Returns an error if:

• size is 0 or exceeds 64 MiB (InvalidInput)
• Underlying allocator fails (OutOfMemory)

Note: Unlike allocate, this method will wait instead of returning OutOfMemory when the pool’s memory limit is reached.

Panics

Panics if the internal mutex is poisoned (which only happens if another thread panicked while holding the lock).

Example

use ruapc_bufpool::BufferPoolBuilder;

let pool = BufferPoolBuilder::new().build();
let buffer = pool.async_allocate(1024 * 1024).await?;

pub fn allocated_memory(&self) -> usize

Returns the current amount of allocated memory in bytes.

This includes all 64 MiB blocks that have been allocated from the underlying allocator, regardless of how much is currently in use.

Panics

Panics if the internal mutex is poisoned.

pub fn max_memory(&self) -> usize

Returns the maximum memory limit in bytes.

Panics

Panics if the internal mutex is poisoned.

pub fn free_counts(&self) -> [usize; 4]

Returns the number of free buffers at each level.

The returned array contains counts for levels 0-3 (1 MiB to 64 MiB).

Panics

Panics if the internal mutex is poisoned.