Struct DynamicPool

pub struct DynamicPool<T: DynamicReset> { /* private fields */ }

a lock-free, thread-safe, dynamically-sized object pool.

this pool begins with an initial capacity and will continue creating new objects on request when none are available. pooled objects are returned to the pool on destruction (with an extra provision to optionally “reset” the state of an object for re-use).

if, during an attempted return, a pool already has maximum_capacity objects in the pool, the pool will throw away that object.

Implementations

impl<T: DynamicReset> DynamicPool<T>

pub fn new<F: Fn() -> T + Sync + Send + 'static>( initial_capacity: usize, maximum_capacity: usize, create: F, ) -> DynamicPool<T>

creates a new DynamicPool<T>. this pool will create initial_capacity objects, and retain up to maximum_capacity objects.

panics.

panics if initial_capacity > maximum_capacity.

Examples found in repository

examples/simple.rs (line 18)

fn main() {
    // Creates a new pool that will hold at most 10 items, starting with 1 item by default.
    let pool = DynamicPool::new(1, 10, Person::default);
    // Assert we have one item in the pool.
    assert_eq!(pool.available(), 1);

    // Take an item from the pool.
    let mut person = pool.take();
    person.name = "jake".into();
    person.age = 99;

    // Assert the pool is empty since we took the person above.
    assert_eq!(pool.available(), 0);
    // Dropping returns the item to the pool.
    drop(person);
    // We now have stuff available in the pool to take.
    assert_eq!(pool.available(), 1);

    // Take person from the pool again, it should be reset.
    let person = pool.take();
    assert_eq!(person.name, "");
    assert_eq!(person.age, 0);

    // Nothing is in the queue.
    assert_eq!(pool.available(), 0);
    // try_take returns an Option. Since the pool is empty, nothing will be created.
    assert!(pool.try_take().is_none());
    // Dropping again returns the person to the pool.
    drop(person);
    // We have stuff in the pool now!
    assert_eq!(pool.available(), 1);

    // try_take would succeed here!
    let person = pool.try_take().unwrap();

    // We can also then detach the `person` from the pool, meaning it won't get
    // recycled.
    let person = person.detach();
    // We can then drop that person, and see that it's not returned to the pool.
    drop(person);
    assert_eq!(pool.available(), 0);
}

pub fn take(&self) -> DynamicPoolItem<T>

takes an item from the pool, creating one if none are available.

Examples found in repository

examples/simple.rs (line 23)

fn main() {
    // Creates a new pool that will hold at most 10 items, starting with 1 item by default.
    let pool = DynamicPool::new(1, 10, Person::default);
    // Assert we have one item in the pool.
    assert_eq!(pool.available(), 1);

    // Take an item from the pool.
    let mut person = pool.take();
    person.name = "jake".into();
    person.age = 99;

    // Assert the pool is empty since we took the person above.
    assert_eq!(pool.available(), 0);
    // Dropping returns the item to the pool.
    drop(person);
    // We now have stuff available in the pool to take.
    assert_eq!(pool.available(), 1);

    // Take person from the pool again, it should be reset.
    let person = pool.take();
    assert_eq!(person.name, "");
    assert_eq!(person.age, 0);

    // Nothing is in the queue.
    assert_eq!(pool.available(), 0);
    // try_take returns an Option. Since the pool is empty, nothing will be created.
    assert!(pool.try_take().is_none());
    // Dropping again returns the person to the pool.
    drop(person);
    // We have stuff in the pool now!
    assert_eq!(pool.available(), 1);

    // try_take would succeed here!
    let person = pool.try_take().unwrap();

    // We can also then detach the `person` from the pool, meaning it won't get
    // recycled.
    let person = person.detach();
    // We can then drop that person, and see that it's not returned to the pool.
    drop(person);
    assert_eq!(pool.available(), 0);
}

pub fn try_take(&self) -> Option<DynamicPoolItem<T>>

attempts to take an item from the pool, returning none if none is available. will never allocate.

Examples found in repository

examples/simple.rs (line 42)

fn main() {
    // Creates a new pool that will hold at most 10 items, starting with 1 item by default.
    let pool = DynamicPool::new(1, 10, Person::default);
    // Assert we have one item in the pool.
    assert_eq!(pool.available(), 1);

    // Take an item from the pool.
    let mut person = pool.take();
    person.name = "jake".into();
    person.age = 99;

    // Assert the pool is empty since we took the person above.
    assert_eq!(pool.available(), 0);
    // Dropping returns the item to the pool.
    drop(person);
    // We now have stuff available in the pool to take.
    assert_eq!(pool.available(), 1);

    // Take person from the pool again, it should be reset.
    let person = pool.take();
    assert_eq!(person.name, "");
    assert_eq!(person.age, 0);

    // Nothing is in the queue.
    assert_eq!(pool.available(), 0);
    // try_take returns an Option. Since the pool is empty, nothing will be created.
    assert!(pool.try_take().is_none());
    // Dropping again returns the person to the pool.
    drop(person);
    // We have stuff in the pool now!
    assert_eq!(pool.available(), 1);

    // try_take would succeed here!
    let person = pool.try_take().unwrap();

    // We can also then detach the `person` from the pool, meaning it won't get
    // recycled.
    let person = person.detach();
    // We can then drop that person, and see that it's not returned to the pool.
    drop(person);
    assert_eq!(pool.available(), 0);
}

pub fn available(&self) -> usize

returns the number of free objects in the pool.

Examples found in repository

examples/simple.rs (line 20)

fn main() {
    // Creates a new pool that will hold at most 10 items, starting with 1 item by default.
    let pool = DynamicPool::new(1, 10, Person::default);
    // Assert we have one item in the pool.
    assert_eq!(pool.available(), 1);

    // Take an item from the pool.
    let mut person = pool.take();
    person.name = "jake".into();
    person.age = 99;

    // Assert the pool is empty since we took the person above.
    assert_eq!(pool.available(), 0);
    // Dropping returns the item to the pool.
    drop(person);
    // We now have stuff available in the pool to take.
    assert_eq!(pool.available(), 1);

    // Take person from the pool again, it should be reset.
    let person = pool.take();
    assert_eq!(person.name, "");
    assert_eq!(person.age, 0);

    // Nothing is in the queue.
    assert_eq!(pool.available(), 0);
    // try_take returns an Option. Since the pool is empty, nothing will be created.
    assert!(pool.try_take().is_none());
    // Dropping again returns the person to the pool.
    drop(person);
    // We have stuff in the pool now!
    assert_eq!(pool.available(), 1);

    // try_take would succeed here!
    let person = pool.try_take().unwrap();

    // We can also then detach the `person` from the pool, meaning it won't get
    // recycled.
    let person = person.detach();
    // We can then drop that person, and see that it's not returned to the pool.
    drop(person);
    assert_eq!(pool.available(), 0);
}

pub fn used(&self) -> usize

returns the number of objects currently in use. does not include objects that have been detached.

pub fn capacity(&self) -> usize

Trait Implementations

impl<T: DynamicReset> Clone for DynamicPool<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + DynamicReset> Debug for DynamicPool<T>

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

Formats the value using the given formatter.