README.md

Object Pool

A thread-safe object pool with automatic return and attach/detach semantics

The goal of an object pool is to reuse expensive to allocate objects or frequently allocated objects

Usage

[dependencies]
object-pool = "0.5"

extern crate object_pool;

Examples

Creating a Pool

The general pool creation looks like this

 let pool: Pool<T> = Pool::new(capacity, || T::new());

Example pool with 32 Vec<u8> with capacity of 4096

 let pool: Pool<Vec<u8>> = Pool::new(32, || Vec::with_capacity(4096));

Using a Pool

Basic usage for ing from the pool

let pool: Pool<Vec<u8>> = Pool::new(32, || Vec::with_capacity(4096));
let mut reusable_buff = pool.try_pull().unwrap(); // returns None when the pool is saturated
reusable_buff.clear(); // clear the buff before using
some_file.read_to_end(reusable_buff);
// reusable_buff is automatically returned to the pool when it goes out of scope

Pull from pool and detach()

let pool: Pool<Vec<u8>> = Pool::new(32, || Vec::with_capacity(4096));
let mut reusable_buff = pool.try_pull().unwrap(); // returns None when the pool is saturated
reusable_buff.clear(); // clear the buff before using
let (pool, reusable_buff) = reusable_buff.detach();
let mut s = String::from(reusable_buff);
s.push_str("hello, world!");
pool.attach(s.into_bytes()); // reattach the buffer before reusable goes out of scope
// reusable_buff is automatically returned to the pool when it goes out of scope

Using Across Threads

You simply wrap the pool in a [std::sync::Arc]

let pool: Arc<Pool<T>> = Arc::new(Pool::new(cap, || T::new()));

Warning

Objects in the pool are not automatically reset, they are returned but NOT reset You may want to call object.reset() or object.clear() or any other equivalent for the object that you are using, after pulling from the pool

Check out the docs for more examples

Performance

The benchmarks compare alloc() vs pool.try_pull() vs pool.detach().

Check out the results

For those who don't like graphs, here's the raw output