piscina

A simple generic pool that supports both sync and async.

Two types of pools are provided:

• [Pool]: A simple pool that supports both sync and async.
• [PriorityPool]: A pool of items with priorities and supports both sync and async.

This crate internally utilizes futures_channel::oneshot and is thus lock-free.

Features

toml default = []

The features below are related to logging errors, which should be unreachable.

• log: Enables logging using the log crate.
• tracing: Enables logging using the tracing crate.

Examples

Non-async [Pool] example:

```rust use piscina::Pool;

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

let item1 = pool.tryget(); assert!(item1.issome());

let item2 = pool.blocking_get();

let none = pool.tryget(); assert!(none.isnone());

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

Async [Pool] example:

```rust 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;

}); ```

Non-async [PriorityPool] example:

```rust 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.tryget(); assert!(item.issome()); let item = item.unwrap(); assert_eq!(item.item(), &"world");

let anotheritem = pool.tryget(); assert!(anotheritem.issome()); let anotheritem = anotheritem.unwrap(); asserteq!(anotheritem.item(), &"hello");

// The pool is now empty. let emptyitem = pool.tryget(); assert!(emptyitem.isnone());

drop(anotheritem); // Return the item back to the pool by dropping it. let hello = pool.tryget(); assert!(hello.issome()); asserteq!(hello.unwrap().item(), &"hello"); ```

Async [PriorityPool] example:

```rust use piscina::PriorityPool;

let mut pool = PriorityPool::new(); pool.put("hello", 1); pool.put("world", 2); // Larger value means higher priority.

futures::executor::blockon(async { // Get the highest priority item. let world = pool.get().await; asserteq!(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");

}); ```

Safety

Instead of using an Option, this crate uses unsafe code ManuallyDrop in PooledItem. And the only use of unsafe code ManuallyDrop::take() occurs when PooledItem is dropped.

License: MIT/Apache-2.0