Crate flaque 

The almighty pool!

Quick Overview

A pool is a collection of objects of limited size. When an object is fetched from the pool, the number of available objects decreases by one. Once the fetched object is dropped, it goes back into the pool, and the number of available objects is increased by one.

All objects are lazily created with a builder. Objects are recycled, i.e. when an object has been built and fetched once, it can be mutated, and when it goes back in the pool, it stays as is, untouched.

use flaque::Pool;

// Let's define what the pool will hold.
struct T {
    x: u8,
}

// Let's create the pool: capacity of 8, and the builder for the `T`s.
let pool = Pool::new(8, || T { x: 0 });

// Let's get an object from the pool.
let object_0 = pool.try_get().unwrap();

The main methods are:

• Pool::try_get if one wants to synchronously get an object from the pool,
• Pool::get if one wants to asynchronously get an object from the pool.

An object is represented by the Object type. When it drops, the value returns to the pool.

Features

Lock- and wait-free

This pool implementation is lock-free and sometimes wait-free. It is designed to be fast and consistent.

Operation	Lock-free	Wait-free
Pool::try_get	yes	yes
Pool::get	yes	no
Object::drop	yes	yes
Pool::close	yes	no
Pool::reopen	yes	yes

If you’re not familiar with these definitions, please read Non-blocking algorithm.

Get and Close futures

Pool::get returns a Get future. It resolves to Some(object) once one is available in the pool, otherwise it returns to None if the pool is closed.

Pool::close returns a Close future. It resolves once all Objects are back into the pool, i.e. when they are all dropped. Pool::close takes self, i.e. it takes ownership of the pool. It will be returned back once the future resolves. This guarantees that it is impossible to reopen the pool, and to fetch new Objects, while waiting for all Objects to return back into the pool. Thus, this is not unusual to see:

let pool = pool.close().await;

Structs

Close

The future returned by Pool::close.

Get

The future returned by Pool::get.

Object

An Object acquired from a Pool with Pool::try_get or Pool::get.

Pool

The almighty pool!

Enums

AcquireError

Error returned by Pool::try_get.