Struct syncpool::SyncPool

pub struct SyncPool<T> { /* fields omitted */ }

Methods

impl<T: Default> SyncPool<T>

pub fn new() -> Self

Create a pool with default size of 64 pre-allocated elements in it.

pub fn with_size(size: usize) -> Self

Create a SyncPool with pre-defined number of elements. Note that we will round-up the size such that the total number of elements in the pool will mod to 8.

pub fn get(&mut self) -> Box<T>

Try to obtain a pre-allocated element from the pool. This method will always succeed even if the pool is empty or not available for anyone to access, and in this case, a new boxed-element will be created.

pub fn put(&mut self, val: Box<T>) -> Option<Box<T>>

Try to return an element to the SyncPool. If succeed, we will return None to indicate that the value has been placed in an empty slot; otherwise, we will return Option<Box<T>> such that the caller can decide if the element shall be just discarded, or try put it back again.

Trait Implementations

impl<T: Default> PoolState for SyncPool<T>

fn expansion_enabled(&self) -> bool

fn miss_count(&self) -> usize

fn capacity(&self) -> usize

fn len(&self) -> usize

fn is_empty(&self) -> bool

impl<T: Default> PoolManager<T> for SyncPool<T> where
    T: Default, 

The pool manager that provide many useful utilities to keep the SyncPool close to the needs of the caller program.

fn reset_handle(&mut self, handle: fn(_: &mut T)) -> &mut Self

Set or update the reset handle. If set, the reset handle will be invoked every time an element has been returned back to the pool (i.e. calling the put method), regardless of if the element is created by the pool or not.

fn allow_expansion(&mut self, allow: bool) -> &mut Self

Set or update the settings that if we will allow the SyncPool to be expanded.

fn expand(&mut self, additional: usize, block: bool) -> bool

Try to expand the SyncPool and add more elements to it. Usually invoke this API only when the caller is certain that the pool is under pressure, and that a short block to the access of the pool won't cause serious issues, since the function will block the current caller's thread until it's finished (i.e. get the opportunity to raise the writer's barrier and wait everyone to leave).

If we're unable to expand the pool, it's due to one of the following reasons: 1) someone has already raised the writer's barrier and is likely modifying the pool, we will leave immediately, and it's up to the caller if they want to try again; 2) we've waited too long but still couldn't obtain an exclusive access to the pool, and similar to reason 1), we will quit now.

fn refill(&mut self, additional: usize) -> usize

Due to contentious access to the pool, sometimes the put action could not finish and return the element to the pool successfully. Overtime, this could cause the number of elements in the pool to dwell. This would only happen slowly if we're running a very contentious multithreading program, but it surely could happen. If the caller detects such situation, they can invoke the refill API and try to refill the pool with elements.

We will try to refill as many elements as requested

impl<T> Default for SyncPool<T> where
    T: Default, 

fn default() -> Self

Returns the "default value" for a type.

impl<T> Drop for SyncPool<T>

fn drop(&mut self)

Executes the destructor for this type.