Crate object_pool

source ·
Expand description

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

§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 pulling 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(&mut reusable_buff).ok();
// 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_utf8(reusable_buff).unwrap();
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()));

With threads, you may also find it convenient to have owned reused objects

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

let owned_reusable = pool.pull_owned(|| 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

Structs§

Type Aliases§