Struct Pool

Source

pub struct Pool { /* private fields */ }

Expand description

A pool that allows storing abritrary objects.

This version is not thread-safe. For the thread-safe version take a look at SyncPool.

Implementations§

Source §

impl Pool

Source

pub fn new() -> Self

Creates a new Pool with the default fallback configuration.

§Example

use generic_pool::{Pool, Config};

fn main() {
    let pool = Pool::new();
    // Equivalent:
    // let pool = Pool::default();

    assert_eq!(pool.fallback_config(), Config::default());
}

Source

pub fn with_fallback_config(config: Config) -> Self

Create a new Pool with the provided Config as the fallback configuration.

§Example

use generic_pool::{Pool, Config};

fn main() {
    // Use a non-default config.
    let config = Config {
        max: 1_000,
        step: 100,
        start: 500,
    };

    assert_ne!(config, Config::default());

    let mut pool = Pool::with_fallback_config(config); // NOTE Config implements Copy.

    assert_eq!(config, pool.fallback_config());
}

Source

pub fn get_config<T: Any>(&self) -> Config

Retrieve the currently active Config for the provided object type.

If you have not manually set a Config for the provided object type, this method will return the fallback configuration.

§Example

use generic_pool::{Pool, Config};

fn main() {
    let mut pool = Pool::new();

    let config = Config {
        max: 1_000,
        step: 100,
        start: 500,
    };

    // Set the config for `Vec<u8>`.
    pool.set_config::<Vec<u8>>(config); // NOTE: Config implements Copy.

    // Retrieve the config for `Vec<u8>`.
    // We would get back the fallback config without the line above.
    let config_compare = pool.get_config::<Vec<u8>>();

    assert_eq!(config_compare, config);
    assert_ne!(config_compare, pool.fallback_config());
}

Source

pub fn fallback_config(&self) -> Config

Retrieve the fallback Config for all object types which do not have a specific Config set.

§Example

use generic_pool::{Pool, Config};

fn main() {
    // Use a non-default config.
    let config = Config {
        max: 1_000,
        step: 100,
        start: 500,
    };

    assert_ne!(config, Config::default());

    let mut pool = Pool::with_fallback_config(config); // NOTE Config implements Copy.

    assert_eq!(config, pool.fallback_config());
}

Source

pub fn set_config<T: Any>(&mut self, config: Config)

Update the Config for the provided object type.

§Example

use generic_pool::{Pool, Config};

fn main() {
    let mut pool = Pool::new();

    let config = Config {
        max: 1_000,
        step: 100,
        start: 500,
    };

    // Set the config for `Vec<u8>`.
    pool.set_config::<Vec<u8>>(config); // NOTE: Config implements Copy.

    // Retrieve the config for `Vec<u8>`.
    // We would get back the fallback config without the line above.
    let config_compare = pool.get_config::<Vec<u8>>();

    assert_eq!(config_compare, config);
    assert_ne!(config_compare, pool.fallback_config());
}

Source

pub fn delete_config<T: Any>(&mut self)

Delete the costum Config for the provided object type. Afterwards the fallback config will apply again.

§Example

use generic_pool::{Pool, Config};

fn main() {
    let mut pool = Pool::new();

    let config = Config {
        max: 1_000,
        step: 100,
        start: 500,
    };

    // Set the config for `Vec<u8>`.
    pool.set_config::<Vec<u8>>(config); // NOTE: Config implements Copy.

    assert_eq!(pool.get_config::<Vec<u8>>(), config);

    // Delete the costum config. Afterwards the fallback config will apply.
    pool.delete_config::<Vec<u8>>();

    assert_ne!(pool.get_config::<Vec<u8>>(), config);
    assert_eq!(pool.get_config::<Vec<u8>>(), pool.fallback_config());
}

Source

pub fn set_fallback_config(&mut self, config: Config)

Set the fallback Config for all object types which do not have a specific Config set.

§Example

use generic_pool::{Pool, Config};

fn main() {
    // Start with the default config.
    let mut pool = Pool::new();

    // Create a non-default config.
    let config = Config {
        max: 1_000,
        step: 100,
        start: 500,
    };

    assert_ne!(config, pool.fallback_config());

    pool.set_fallback_config(config);

    assert_eq!(config, pool.fallback_config());
}

Source

pub fn get<T: Any>(&mut self) -> Option<T>

Try to retrieve an object of the specified type. Will give back None if the there are no objects of this type currently stored in the pool.

§Example

use generic_pool::Pool;

fn main() {
    let mut pool = Pool::new();

    let buffer = match pool.get::<Vec<u8>>() {
        Some(mut buffer) => {
            buffer.clear();
            buffer
        }
        None => Vec::new(),
    };

    assert_eq!(buffer.len(), 0);
}

Source

pub fn get_or_default<T: Any + Default>(&mut self) -> T

Retrieve an object of the specified type. If there is no object of this type currently stored in the pool it will create one using its Default implementation.

§Example

use generic_pool::Pool;

fn main() {
    let mut pool = Pool::new();

    let buffer = pool.get_or_default::<Vec<u8>>();

    assert_eq!(buffer.len(), 0);
}

Source

pub fn get_with_guard<T: Any>(&mut self) -> Option<DropGuard<T>>

Try to retrieve an object of the specified type with a drop guard. Will give back None if the there are no objects of this type currently stored in the pool.

Once the returned DropGuard - if any - goes out of scope it will automatically put the contained object pack into the pool. Note that the object might still get dropped by the pool if the corresponding internal buffer is full.

§Example

use generic_pool::{Pool, DropGuard};

fn main() {
    let mut pool = Pool::new();

    let buffer: DropGuard<Vec<u8>> = match pool.get_with_guard::<Vec<u8>>() {
        Some(mut buffer) => {
            // DropGuard is a smart pointer, so we can call Vec.clear() directly.
            buffer.clear();
            buffer
        }
        None => DropGuard::new(Vec::new(), &pool),
    };

    assert_eq!(buffer.len(), 0);

    assert!(pool.get::<Vec<u8>>().is_none());

    // Will put the buffer back into the pool.
    drop(buffer);

    assert!(pool.get::<Vec<u8>>().is_some());
}

Source

pub fn get_or_default_with_guard<T: Any + Default>(&mut self) -> DropGuard<T>

Retrieve an object of the specified type with a drop guard. If there is no object of this type currently stored in the pool it will create one using its Default implementation.

Once the returned DropGuard goes out of scope it will automatically put the contained object pack into the pool. Note that the object might still get dropped by the pool if the corresponding internal buffer is full.

§Example

use generic_pool::{Pool, DropGuard};

fn main() {
    let mut pool = Pool::new();

    let buffer: DropGuard<Vec<u8>> = pool.get_or_default_with_guard::<Vec<u8>>();

    assert_eq!(buffer.len(), 0);

    assert!(pool.get::<Vec<u8>>().is_none());

    // Will put the buffer back into the pool.
    drop(buffer);

    assert!(pool.get::<Vec<u8>>().is_some());
}

Source

pub fn put<T: Any>(&mut self, obj: T)

Add an object to the pool. Unless the corresponding internal buffer is full, you can retrieve it later on by calling Pool.get() or one of its variants.

§Example

use generic_pool::Pool;

fn main() {
    let mut pool = Pool::new();

    assert!(pool.get::<Vec<u8>>().is_none());

    pool.put(vec![0u8; 1024]);

    let buffer = pool.get::<Vec<u8>>().unwrap();

    assert_eq!(buffer.len(), 1024);
}