Fastpool

https://docs.rs/fastpool/1.1.0/fastpool/
Admin
Fastpool provides fast and runtime-agnostic object pools for Async Rust, offering both bounded and...
Tokens:5,554
Snippets:79
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Retain objects in Pool

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

Example of using the retain method to remove stale objects from the pool via a background task.

```rust
let interval = Duration::from_secs(30);
let max_age = Duration::from_secs(60);

let weak_pool = Arc::downgrade(&pool);
tokio::spawn(async move {
    loop {
        tokio::time::sleep(interval).await;
        if let Some(pool) = weak_pool.upgrade() {
            pool.retain(|_, status| status.last_used().elapsed() < max_age);
        } else {
            break;
        }
    }
});
```

--------------------------------

### fastpool::bounded::Pool

Source: https://docs.rs/fastpool/1.1.0/fastpool/index.html

A bounded object pool that manages object creation and recycling. It blocks get requests when the maximum pool size is reached.

```APIDOC
## Bounded Pool Usage

### Description
Creates a new bounded pool using a manager that implements the `ManageObject` trait. The pool manages objects up to the `max_size` defined in `PoolConfig`.

### Usage
```rust
let pool = Pool::new(PoolConfig::new(16), Manager);
let o = pool.get().await.unwrap();
```

### Key Components
- **PoolConfig**: Configuration struct for setting the maximum pool size.
- **ManageObject**: Trait to define how objects are created and validated for recycling.
- **Pool::get()**: Asynchronously retrieves an object from the pool, blocking if the pool is full.
```

--------------------------------

### Initialize and use an unbounded pool

Source: https://docs.rs/fastpool/1.1.0/fastpool/index.html

Demonstrates creating an unbounded pool with no manager and manually extending it with objects.

```rust
use fastpool::unbounded::Pool;
use fastpool::unbounded::PoolConfig;

let pool = Pool::<Vec<u8>>::never_manage(PoolConfig::default());

let result = pool.get().await;
assert_eq!(result.unwrap_err().to_string(), "unbounded pool is empty");

pool.extend_one(Vec::with_capacity(1024));
let o = pool.get().await.unwrap();
assert_eq!(o.capacity(), 1024);
```

--------------------------------

### Create and use a bounded object pool

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/index.html

Demonstrates implementing the ManageObject trait and initializing a Pool with a specific configuration.

```rust
use std::future::Future;

use fastpool::ManageObject;
use fastpool::ObjectStatus;
use fastpool::bounded::Pool;
use fastpool::bounded::PoolConfig;

struct Compute;
impl Compute {
    async fn do_work(&self) -> i32 {
        42
    }
}

struct Manager;
impl ManageObject for Manager {
    type Object = Compute;
    type Error = ();

    async fn create(&self) -> Result<Self::Object, Self::Error> {
        Ok(Compute)
    }

    async fn is_recyclable(
        &self,
        o: &mut Self::Object,
        status: &ObjectStatus,
    ) -> Result<(), Self::Error> {
        Ok(())
    }
}

let pool = Pool::new(PoolConfig::new(16), Manager);
let o = pool.get().await.unwrap();
assert_eq!(o.do_work().await, 42);
```

--------------------------------

### PoolConfig::new

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.PoolConfig.html

Creates a new instance of PoolConfig with default settings.

```APIDOC
## fn new()

### Description
Creates a new `PoolConfig` instance.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### Pool::new

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

Creates a new instance of a Pool.

```APIDOC
## pub fn new(config: PoolConfig, manager: M) -> Arc<Self>

### Description
Creates a new `Pool` instance with the provided configuration and object manager.
```

--------------------------------

### Pool::new

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Pool.html

Creates a new Pool instance with a custom manager.

```APIDOC
## pub fn new(config: PoolConfig, manager: M) -> Arc<Self>

### Description
Creates a new `Pool` with the provided configuration and a custom `ManageObject` implementation.

### Parameters
- **config** (PoolConfig) - Required - The configuration settings for the pool.
- **manager** (M) - Required - The object manager implementation.
```

--------------------------------

### Create an unbounded pool with NeverManageObject

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/index.html

Demonstrates initializing a pool that does not automatically create new objects, requiring manual extension via extend_one.

```rust
use fastpool::unbounded::Pool;
use fastpool::unbounded::PoolConfig;

let pool = Pool::<Vec<u8>>::never_manage(PoolConfig::default());

let result = pool.get().await;
assert_eq!(result.unwrap_err().to_string(), "unbounded pool is empty");

pool.extend_one(Vec::with_capacity(1024));
let o = pool.get().await.unwrap();
assert_eq!(o.capacity(), 1024);
drop(o);
let o = pool.get().await.unwrap();
assert_eq!(o.capacity(), 1024);
let result = pool.get().await;
assert_eq!(result.unwrap_err().to_string(), "unbounded pool is empty");
```

--------------------------------

### Implement object management hooks

Source: https://docs.rs/fastpool/1.1.0/fastpool/index.html

Demonstrates implementing the ManageObject trait to handle custom logic during object creation and recycling.

```rust
use std::future::Future;

use fastpool::ManageObject;
use fastpool::ObjectStatus;

struct Manager;
impl ManageObject for Manager {
    type Object = i32;
    type Error = std::convert::Infallible;

    async fn create(&self) -> Result<Self::Object, Self::Error> {
        let o = 42;
        // any post-create hooks
        Ok(o)
    }

    async fn is_recyclable(
        &self,
        _o: &mut Self::Object,
        _status: &ObjectStatus,
    ) -> Result<(), Self::Error> {
        // any pre-recycle hooks
        // determinate if is_recyclable
        // any post-recycle hooks
        Ok(())
    }
}
```

--------------------------------

### PoolConfig::new

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.PoolConfig.html

Creates a new instance of PoolConfig with a specified maximum size.

```APIDOC
## fn new(max_size: usize) -> Self

### Description
Creates a new `PoolConfig` instance with the provided maximum size.

### Parameters
- **max_size** (usize) - Required - The maximum size of the `Pool`.
```

--------------------------------

### Create an unbounded pool with a custom ManageObject

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/index.html

Shows how to implement the ManageObject trait to define custom object creation and recycling logic for the pool.

```rust
use std::future::Future;

use fastpool::ManageObject;
use fastpool::ObjectStatus;
use fastpool::unbounded::Pool;
use fastpool::unbounded::PoolConfig;

struct Compute;
impl Compute {
    async fn do_work(&self) -> i32 {
        42
    }
}

struct Manager;
impl ManageObject for Manager {
    type Object = Compute;
    type Error = ();

    async fn create(&self) -> Result<Self::Object, Self::Error> {
        Ok(Compute)
    }

    async fn is_recyclable(
        &self,
        o: &mut Self::Object,
        status: &ObjectStatus,
    ) -> Result<(), Self::Error> {
        Ok(())
    }
}

let pool = Pool::new(PoolConfig::default(), Manager);
let o = pool.get().await.unwrap();
assert_eq!(o.do_work().await, 42);
```

--------------------------------

### Pool::get_or_create

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Pool.html

Retrieves an object from the pool or creates a new one using an async closure.

```APIDOC
## pub async fn get_or_create<E, F>(self: &Arc<Self>, f: F) -> Result<Object<T>, E>

### Description
Retrieves an `Object` from this `Pool`, or creates a new one with the passed-in async closure if the pool is empty. This method is specific to `NeverManageObject` pools.

### Parameters
- **f** (AsyncFnOnce) - Required - An async closure that returns a Result containing the object or an error.
```

--------------------------------

### Pool<T>::new

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/index.html

Creates an unbounded pool with a custom object manager.

```APIDOC
## Pool::<T>::new(config: PoolConfig, manager: M)

### Description
Creates a new unbounded pool that uses the provided `ManageObject` implementation to create new objects automatically when the pool is empty.

### Parameters
- **config** (PoolConfig) - The configuration settings for the pool.
- **manager** (M: ManageObject) - The factory implementation responsible for creating and managing objects.
```

--------------------------------

### PoolConfig::with_queue_strategy

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.PoolConfig.html

Returns a new PoolConfig with the specified queue strategy.

```APIDOC
## fn with_queue_strategy(self, queue_strategy: QueueStrategy) -> Self

### Description
Returns a new `PoolConfig` with the specified queue strategy, which determines the order of objects being queued and dequeued.

### Parameters
- **queue_strategy** (QueueStrategy) - Required - The strategy to be used by the `Pool`.
```

--------------------------------

### PoolConfig::with_queue_strategy

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.PoolConfig.html

Returns a new PoolConfig with the specified queue strategy.

```APIDOC
## fn with_queue_strategy(self, queue_strategy: QueueStrategy) -> Self

### Description
Returns a new `PoolConfig` with the specified queue strategy applied.

### Parameters
- **queue_strategy** (QueueStrategy) - The strategy to determine the order of objects being queued and dequeued.
```

--------------------------------

### PoolConfig::with_recycle_cancelled_strategy

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.PoolConfig.html

Returns a new PoolConfig with the specified recycle cancelled strategy.

```APIDOC
## fn with_recycle_cancelled_strategy(self, recycle_cancelled_strategy: RecycleCancelledStrategy) -> Self

### Description
Returns a new `PoolConfig` with the specified recycle cancelled strategy applied.

### Parameters
- **recycle_cancelled_strategy** (RecycleCancelledStrategy) - The strategy to use when recycling an object has been cancelled.
```

--------------------------------

### PoolConfig::with_recycle_cancelled_strategy

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.PoolConfig.html

Returns a new PoolConfig with the specified recycle cancelled strategy.

```APIDOC
## fn with_recycle_cancelled_strategy(self, recycle_cancelled_strategy: RecycleCancelledStrategy) -> Self

### Description
Returns a new `PoolConfig` with the specified recycle cancelled strategy, which defines behavior when an object recycling process has been cancelled.

### Parameters
- **recycle_cancelled_strategy** (RecycleCancelledStrategy) - Required - The strategy to be used when recycling is cancelled.
```

--------------------------------

### Pool::get

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

Retrieves an object from the pool.

```APIDOC
## pub async fn get(self: &Arc<Self>) -> Result<Object<M>, M::Error>

### Description
Retrieves an `Object` from the pool. If the pool is at maximum capacity, this method blocks until an object is returned or detached.
```

--------------------------------

### Implement caller-side timeout for object acquisition

Source: https://docs.rs/fastpool/1.1.0/fastpool/index.html

Shows how to wrap pool acquisition with a timeout using external timer implementations like tokio.

```rust
use std::sync::Arc;
use std::time::Duration;

use fastpool::bounded::Object;
use fastpool::bounded::Pool;

#[derive(Debug, Clone)]
pub struct ConnectionPool {
    pool: Arc<Pool<ManageConnection>>,
}

impl ConnectionPool {
    pub async fn acquire(&self) -> Result<Object<ManageConnection>, Error> {
        const ACQUIRE_TIMEOUT: Duration = Duration::from_secs(60);

        // note that users can choose any timer implementation here
        let result = tokio::time::timeout(ACQUIRE_TIMEOUT, self.pool.get()).await;

        // ... processing the result
    }
}
```

--------------------------------

### Pool<T>::get

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/index.html

Retrieves an object from the pool.

```APIDOC
## Pool::<T>::get()

### Description
Asynchronously retrieves an object from the pool. If the pool is empty and a manager is configured, it will attempt to create a new object; otherwise, it returns an error.
```

--------------------------------

### Define PoolConfig Structure

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.PoolConfig.html

The internal structure definition for PoolConfig, highlighting its non-exhaustive nature.

```rust
#[non_exhaustive]
pub struct PoolConfig {
    pub max_size: usize,
    pub queue_strategy: QueueStrategy,
    pub recycle_cancelled_strategy: RecycleCancelledStrategy,
}
```

--------------------------------

### Pool::extend

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Pool.html

Adds multiple objects to the pool from an iterator.

```APIDOC
## pub fn extend(&self, iter: impl IntoIterator<Item = T>)

### Description
Extends the pool with a collection of objects provided by an iterator.

### Parameters
- **iter** (IntoIterator) - Required - An iterator yielding objects to add to the pool.
```

--------------------------------

### Pool<T>::never_manage

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/index.html

Creates an unbounded pool that does not automatically create new objects when empty.

```APIDOC
## Pool::<T>::never_manage(config: PoolConfig)

### Description
Creates a new unbounded pool that requires manual object insertion via `extend_one` or similar methods. If the pool is empty when `get()` is called, it returns a `PoolIsEmpty` error.

### Parameters
- **config** (PoolConfig) - The configuration settings for the pool.
```

--------------------------------

### ObjectStatus Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/struct.ObjectStatus.html

The definition of the ObjectStatus struct.

```rust
pub struct ObjectStatus { /* private fields */ }
```

--------------------------------

### Pool::status

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

Returns the current status of the pool.

```APIDOC
## pub fn status(&self) -> PoolStatus

### Description
Returns the current status of the pool, providing eventual consistency for monitoring purposes.
```

--------------------------------

### ManageObject Trait Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/trait.ManageObject.html

The core trait definition for managing object lifecycles, requiring Send and Sync bounds.

```rust
pub trait ManageObject: Send + Sync {
    type Object: Send;
    type Error: Send;

    // Required methods
    fn create(
        &self,
    ) -> impl Future<Output = Result<Self::Object, Self::Error>> + Send;
    fn is_recyclable(
        &self,
        o: &mut Self::Object,
        status: &ObjectStatus,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    // Provided method
    fn on_detached(&self, _o: &mut Self::Object) { ... }
}
```

--------------------------------

### Pool::extend_one

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Pool.html

Adds a single object to the pool.

```APIDOC
## pub fn extend_one(&self, o: T)

### Description
Extends the pool by adding exactly one object.

### Parameters
- **o** (T) - Required - The object to add to the pool.
```

--------------------------------

### Object::status

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Object.html

Retrieves the current status of the pooled object.

```APIDOC
## pub fn status(&self) -> ObjectStatus

### Description
Returns the status of the object.
```

--------------------------------

### Object::status

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Object.html

Retrieves the current status of the pooled object.

```APIDOC
## fn status(&self) -> ObjectStatus

### Description
Returns the status of the object.

### Returns
- **ObjectStatus** - The current status of the pooled object.
```

--------------------------------

### Define QueueStrategy Enum

Source: https://docs.rs/fastpool/1.1.0/fastpool/enum.QueueStrategy.html

The core enum definition for specifying the object pool retrieval strategy.

```rust
pub enum QueueStrategy {
    Fifo,
    Lifo,
}
```

--------------------------------

### Define Pool structure

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

The basic definition of the generic Pool struct.

```rust
pub struct Pool<M: ManageObject> { /* private fields */ }
```

--------------------------------

### Pool::replenish

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

Replenishes the pool with new objects up to a specified limit.

```APIDOC
## pub async fn replenish(&self, most: usize) -> usize

### Description
Replenishes the pool with at most `most` number of new objects. Returns the number of objects actually added to the pool.
```

--------------------------------

### PoolConfig Struct Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.PoolConfig.html

The definition of the PoolConfig struct, which is marked as non-exhaustive.

```rust
#[non_exhaustive]
pub struct PoolConfig {
    pub queue_strategy: QueueStrategy,
    pub recycle_cancelled_strategy: RecycleCancelledStrategy,
}
```

--------------------------------

### Extend Pool with Multiple Objects

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Pool.html

Adds multiple objects to the pool using an iterator with the extend method.

```rust
use fastpool::unbounded::Pool;
use fastpool::unbounded::PoolConfig;

let config = PoolConfig::default();
let pool = Pool::never_manage(config);

pool.extend([
    Vec::<i64>::with_capacity(1024),
    Vec::<i64>::with_capacity(512),
    Vec::<i64>::with_capacity(256),
]);
```

--------------------------------

### Object Struct Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Object.html

The definition of the Object struct within the fastpool::bounded module.

```rust
pub struct Object<M: ManageObject> { /* private fields */ }
```

--------------------------------

### Extend Pool with a Single Object

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Pool.html

Adds a single object to the pool using the extend_one method.

```rust
use fastpool::unbounded::Pool;
use fastpool::unbounded::PoolConfig;

let config = PoolConfig::default();
let pool = Pool::never_manage(config);

pool.extend_one(Vec::<i64>::with_capacity(1024));
```

--------------------------------

### PoolStatus Struct Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.PoolStatus.html

The definition of the PoolStatus struct, which tracks pool metrics.

```rust
#[non_exhaustive]
pub struct PoolStatus {
    pub max_size: usize,
    pub current_size: usize,
    pub idle_count: usize,
    pub wait_count: usize,
}
```

--------------------------------

### Object Struct Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Object.html

The definition of the Object struct within the fastpool::unbounded module.

```rust
pub struct Object<T, M: ManageObject<Object = T> = NeverManageObject<T>> { /* private fields */ }
```

--------------------------------

### Object::detach

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Object.html

Detaches the object from the pool, reducing the pool size by one and returning the underlying object.

```APIDOC
## fn detach(self) -> M::Object

### Description
Detaches the object from the Pool. This reduces the size of the pool by one.

### Returns
- **M::Object** - The underlying object that was previously managed by the pool.
```

--------------------------------

### Define PoolIsEmpty struct

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.PoolIsEmpty.html

The definition of the PoolIsEmpty error struct.

```rust
pub struct PoolIsEmpty(/* private fields */);
```

--------------------------------

### Pool::retain

Source: https://docs.rs/fastpool/1.1.0/fastpool/bounded/struct.Pool.html

Removes objects from the pool based on a predicate.

```APIDOC
## pub fn retain(&self, f: impl FnMut(&mut M::Object, ObjectStatus) -> bool) -> RetainResult<M::Object>

### Description
Retains only the objects that satisfy the provided predicate function. Note that this method blocks the entire pool.
```

--------------------------------

### RetainResult Struct Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/struct.RetainResult.html

The definition of the RetainResult struct, which is marked as non-exhaustive.

```rust
#[non_exhaustive]
pub struct RetainResult<T> {
    pub retained: usize,
    pub removed: Vec<T>,
}
```

--------------------------------

### NeverManageObject Struct Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.NeverManageObject.html

The definition of the NeverManageObject struct, which requires the contained type to be Send and Sync.

```rust
pub struct NeverManageObject<T: Send + Sync> { /* private fields */ }
```

--------------------------------

### Object::detach

Source: https://docs.rs/fastpool/1.1.0/fastpool/unbounded/struct.Object.html

Detaches the object from the pool, preventing it from being returned to the pool when dropped and reducing the pool size by one.

```APIDOC
## pub fn detach(self) -> M::Object

### Description
Detaches the object from the Pool. This reduces the size of the pool by one and returns the underlying object.
```

--------------------------------

### RecycleCancelledStrategy Enum Definition

Source: https://docs.rs/fastpool/1.1.0/fastpool/enum.RecycleCancelledStrategy.html

The definition of the RecycleCancelledStrategy enum showing its available variants.

```rust
pub enum RecycleCancelledStrategy {
    Detach,
    ReturnToPool,
}
```
Tokens:
Raw