Struct piscina::priority::PriorityPool

pub struct PriorityPool<T, P>where
    P: Ord,{ /* private fields */ }

A pool that can be used to borrow items with a priority.

This internally uses a BinaryHeap which is a max-heap. This means that the item with the highest priority will be returned first.

Type parameters

• T: The type of the items.
• P: The type of the priority.

Examples

Non-async example:

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 1);
pool.put("world", 2); // Larger value means higher priority.
 
// Get the highest priority item.
let item = pool.try_get();
assert!(item.is_some());
let item = item.unwrap();
assert_eq!(item.item(), &"world");
 
let another_item = pool.try_get();
assert!(another_item.is_some());
let another_item = another_item.unwrap();
assert_eq!(another_item.item(), &"hello");
 
// The pool is now empty.
let empty_item = pool.try_get();
assert!(empty_item.is_none());
 
drop(another_item); // Return the item back to the pool by dropping it.
let hello = pool.try_get();
assert!(hello.is_some());
assert_eq!(hello.unwrap().item(), &"hello");

Async example:

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 1);
pool.put("world", 2); // Larger value means higher priority.
 
futures::executor::block_on(async {
    // Get the highest priority item.
    let world = pool.get().await;
    assert_eq!(world.item(), &"world"); 

    let hello = pool.get().await;
    assert_eq!(hello.item(), &"hello");
 
    // The pool is now empty.
    drop(hello); // Return the item back to the pool by dropping it.
    let item = pool.get().await;
    assert_eq!(item.item(), &"hello"); 
});

Implementations

impl<T, P> PriorityPool<T, P>where P: Ord,

pub fn new() -> Self

Creates a new PriorityPool.

pub fn with_capacity(capacity: usize) -> Self

Creates a new PriorityPool with the given capacity that is used for both the ready and borrowed queues.

pub fn len(&self) -> usize

Returns the number of items in the pool.

pub fn is_empty(&self) -> bool

Returns true if the pool is empty.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the pool as much as possible.

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

Puts an item T with the given priority P into the pool.

Example

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 1);

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

Tries to get the highest priority item that is immediately available from the PriorityPool. Returns None if the pool is empty.

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

Example

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 1);
let item = pool.try_get();
assert!(item.is_some());

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

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

Example

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 1);
let item = pool.blocking_get();

Panic

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

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

Gets the highest priority item that is available from the PriorityPool. If there is no item immediately available, this will .await until one becomes available.

Example

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

Panic

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

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

Tries to remove the highest priority item that is immediately available from the PriorityPool. Returns None if the pool is empty.

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

Example

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 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, P)

Removes the highest priority item that is available from the PriorityPool. If there is no item immediately available, this will wait in a blocking manner until an item is available.

Example

use piscina::PriorityPool;
 
let mut pool = PriorityPool::new();
pool.put("hello", 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 returning the item to the pool, which should never happen.

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

Removes the highest priority item that is available from the PriorityPool. If there is no item immediately available, this will .await until one becomes available.

Example

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

Trait Implementations

impl<T: Debug, P> Debug for PriorityPool<T, P>where P: Ord + Debug,

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

Formats the value using the given formatter.