Crate syncpool[−][src]

SyncPool A simple and thread-safe objects pool to reuse heavy objects placed in the heap.

What this crate is for

Inspired by Go's sync.Pool module, this crate provides a multithreading-friendly library to recycle and reuse heavy, heap-based objects, such that the overall allocation and memory pressure will be reduced, and hence boosting the performance.

What this crate is NOT for

There is no such thing as the silver bullet when designing a multithreading project, programmer has to judge use cases on a case-by-case base.

As shown by a few (hundred) benchmarks we have run, it is quite clear that the library can reliably beat the allocator in the following case:

The object is large enough that it makes sense to live in the heap. The clean up operations required to sanitize the written data before putting the element back to the pool is simple and fast to run. The estimation on the maximum number of elements simultaneously checked out during the program run is good enough, i.e. the parallelism is deterministic; otherwise when the pool is starving (i.e. it doesn't have enough elements left to provide), the performance will suffer because we will need to create (and allocate in the heap for) new elements.

If your struct is nibble enough to live in the stack without blowing it, or if it's not in middle of the hottest code path, you most likely won't need the library to labor for you, allocators nowadays work quite marvelously, especially on the stack.

Example

extern crate syncpool;

use std::collections::HashMap;
use std::sync::mpsc::{self, SyncSender};
use std::thread;
use std::time::Duration;
use syncpool::prelude::*;

/// For simplicity and illustration, here we use the most simple but unsafe way to
/// define the shared pool: make it static mut. Other safer implementation exists
/// but may require some detour depending on the business logic and project structure.
static mut POOL: Option<SyncPool<ComplexStruct>> = None;

/// Number of producers that runs in this test
const COUNT: usize = 128;

/// The complex data struct for illustration. Usually such a heavy element could also
/// contain other nested struct, and should almost always be placed in the heap. If
/// your struct is *not* heavy enough to be living in the heap, you most likely won't
/// need this library -- the allocator will work better on the stack. The only requirement
/// for the struct is that it has to implement the `Default` trait, which can be derived
/// in most cases, or implemented easily.
#[derive(Default, Debug)]
struct ComplexStruct {
    id: usize,
    name: String,
    body: Vec<String>,
    flags: Vec<usize>,
    children: Vec<usize>,
    index: HashMap<usize, String>,
    rev_index: HashMap<String, usize>,
}

fn main() {
   // Must initialize the pool first
   unsafe { POOL.replace(SyncPool::with_size(COUNT / 2)); }

   // use the channel that create a concurrent pipeline.
   let (tx, rx) = mpsc::sync_channel(64);

   // data producer loop
   thread::spawn(move || {
       let mut producer = unsafe { POOL.as_mut().unwrap() };

       for i in 0..COUNT {
           // take a pre-init element from the pool, we won't allocate in this
           // call since the boxed element is already placed in the heap, and
           // here we only reuse the one.
           let mut content: Box<ComplexStruct> = producer.get();
           content.id = i;

           // simulating busy/heavy calculations we're doing in this time period,
           // usually involving the `content` object.
           thread::sleep(Duration::from_nanos(32));

           // done with the stuff, send the result out.
           tx.send(content).unwrap_or_default();
       }
   });

   // data consumer logic
   let handler = thread::spawn(move || {
       let mut consumer = unsafe { POOL.as_mut().unwrap() };

       // `content` has the type `Box<ComplexStruct>`
       for content in rx {
           println!("Receiving struct with id: {}", content.id);
           consumer.put(content);
       }
   });

   // wait for the receiver to finish and print the result.
   handler.join().unwrap_or_default();

   println!("All done...");

}

In addition, if you prefer to use a constructor for creating and intializing the element, you may opt to use the with_builder API:

use syncpool::prelude::*;
use std::vec;

struct BigStruct {
    a: u32,
    b: u32,
    c: Vec<u8>
}

impl BigStruct {
    fn new() -> Self {
        BigStruct {
            a: 1,
            b: 42,
            c: vec::from_elem(0u8, 0x1_000_000),
        }
    }
}

let mut pool = SyncPool::with_builder(BigStruct::new);

println!("Pool created...");

let big_box = pool.get();

assert_eq!(big_box.a, 1);
assert_eq!(big_box.b, 42);
assert_eq!(big_box.c.len(), 0x1_000_000);

pool.put(big_box);

There are occassions where the struct is too large to fit into the stack (e.g. a buffer data structure), you can instead use the with_packer API to intialize the object that has already been created on heap, so you can worry less on making the object and move it to the heap (and with automatic performance boost)!

Note that if calling the with_packer API, you have to make sure that all fields shall be properly initialized. The provided placeholder object is well-aligned, however, the fields may be undefined if not initialized correctly, e.g. a field of the NonNull<T> type, or the MaybeUninit<T> type.

use syncpool::prelude::*;
use std::vec;

struct BigStruct {
    a: u32,
    b: u32,
    c: Vec<u8>
}

impl BigStruct {
    fn initializer(mut self: Box<Self>) -> Box<Self> {
        self.a = 1;
        self.b = 42;
        self.c = vec::from_elem(0u8, 0x1_000_000);
        self
    }
}

let mut pool = SyncPool::with_packer(BigStruct::initializer);

println!("Pool created...");

let big_box = pool.get();

assert_eq!(big_box.a, 1);
assert_eq!(big_box.b, 42);
assert_eq!(big_box.c.len(), 0x1_000_000);

pool.put(big_box);

You can find more complex (i.e. practical) use cases in the examples folder.

PoolManager
PoolState

Functions

default_box	Similar to the `make_box` API, the `default_box` API is a wrapper over the unsafer version of the directly-to-the-heap ones. If the struct wrapped in the box has implemented the `Default` trait, then one can call this API that will invoke the `Default::default` to initialize the object, such that the caller won't need to supply a closure to initialize all the fields.
make_box	This API is a wrapper on the unsafer version of the direct-to-the-heap-box APIs. The API is safe because it is the caller's responsiblity to supply the struct initialier as a closure, such that after calling the struct initializer, the returned object shall be valid and meaningful.
raw_box ^⚠	Create a box structure without moving the wrapped value from the stack to the heap. This API is most useful when the wrapped value is too large for the default stack size, such that initializing and packing the valuing into the box is a pain.
raw_box_zeroed ^⚠	Similar to `raw_box`, this API creates a box structure without moving the wrapped value from the stack to the heap. This API is most useful when the wrapped value is too large for the default stack size, such that initializing and packing the valuing into the box is a pain.

Crate syncpool[−][src]

What this crate is for

What this crate is NOT for

Example

Modules

Structs

Traits

Functions