Struct piscina::pool::Pool

pub struct Pool<T> { /* private fields */ }

A pool of generic items

Internally it maintains two lists: one of ready items and one of borrowed

Examples

Non-async Pool example:

use piscina::Pool;

let mut pool = Pool::new();
pool.put(1);
pool.put(2);

let item1 = pool.try_get();
assert!(item1.is_some());

let item2 = pool.blocking_get();

let none = pool.try_get();
assert!(none.is_none());

drop(item1); // Return the item to the pool by dropping it
let item3 = pool.try_get();
assert!(item3.is_some());

Async Pool example:

use piscina::Pool;

futures::executor::block_on(async {
    let mut pool = Pool::new();
    pool.put(1);
    pool.put(2);

    let item1 = pool.get().await;
    let item2 = pool.get().await;

    let none = pool.try_get();
    assert!(none.is_none());

    drop(item1); // Return the item to the pool by dropping it
    let item3 = pool.get().await;
});

Implementations

impl<T> Pool<T>

pub fn new() -> Self

Creates an empty pool

pub fn with_capacity(capacity: usize) -> Self

Creates an empty pool with the specified capacity for both the ready and borrowed lists.

pub fn len(&self) -> usize

Returns the number of all items, whether ready or borrowed.

pub fn is_empty(&self) -> bool

Returns true if the pool contains no items.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of both the ready and borrowed lists as much as possible.

pub fn put(&mut self, item: T)

Puts an item into the pool

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);

pub fn try_get(&mut self) -> Option<PooledItem<T>>

Tries to get an item from the pool. Returns None if there is no item immediately available.

Please note that if the sender is dropped before the item is returned to the pool, the item will be lost and this will be reflected on the pool’s length.

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);
let item = pool.try_get();
assert!(item.is_some());

pub fn blocking_get(&mut self) -> PooledItem<T>

Gets an item from the pool. If there is no item immediately available, this will wait in a blocking manner until an item is available.

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);
let item = pool.blocking_get();

Panic

This will panic if the sender is dropped before the item is returned to the pool, which should never happen.

pub fn get(&mut self) -> Get<'_, T>

Gets an item from the pool. If there is no item immediately available, the future will .await until one is available.

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);
futures::executor::block_on(async {
    let item = pool.get().await;
});

Panic

This future will panic if any sender is dropped before the item is returned to the pool, which should never happen.

pub fn try_pop(&mut self) -> Option<T>

Tries to pop an item from the pool. Returns None if there is no item immediately available.

Please note that if the sender is dropped before the item is returned to the pool, the item will be lost and this will be reflected on the pool’s length.

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);
assert_eq!(pool.len(), 1);
 
let item = pool.try_pop();
assert!(item.is_some());
assert_eq!(pool.len(), 0);

pub fn blocking_pop(&mut self) -> T

Pops an item from the pool. If there is no item immediately available, this will wait in a blocking manner until an item is available.

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);
assert_eq!(pool.len(), 1);
let item = pool.blocking_pop();
assert_eq!(pool.len(), 0);

Panic

This will panic if the sender is dropped before the item is returned to the pool, which should never happen.

pub fn pop(&mut self) -> Pop<'_, T>

Pops an item from the pool. If there is no item immediately available, this will wait in a blocking manner until an item is available.

Example

use piscina::Pool;
 
let mut pool = Pool::new();
pool.put(1);
assert_eq!(pool.len(), 1);
futures::executor::block_on(async {
   let item = pool.pop().await;
   assert_eq!(pool.len(), 0);
});

Panic

This will panic if the sender is dropped before the item is returned to the pool, which should never happen.

Trait Implementations

impl<T: Debug> Debug for Pool<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Pool<T>

fn default() -> Pool<T>

Returns the “default value” for a type.