pub struct ObjPool<T> { /* private fields */ }
Expand description
An object pool.
ObjPool<T>
holds an array of slots for storing objects.
Every slot is always in one of two states: occupied or vacant.
Essentially, this is equivalent to Vec<Option<T>>
.
Insert and remove
When inserting a new object into object pool, a vacant slot is found and then the object is placed
into the slot. If there are no vacant slots, the array is reallocated with bigger capacity.
The cost of insertion is amortized O(1)
.
When removing an object, the slot containing it is marked as vacant and the object is returned.
The cost of removal is O(1)
.
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let a = obj_pool.insert(10);
assert_eq!(a.into_index(), 0);
let b = obj_pool.insert(20);
assert_eq!(b.into_index(), 1);
assert_ne!(a, b); // ids are not the same
assert_eq!(obj_pool.remove(a), Some(10));
assert_eq!(obj_pool.get(a), None); // there is no object with this `ObjId` anymore
assert_eq!(obj_pool.insert(30), a); // slot is reused, got the same `ObjId`
Indexing
You can also access objects in an object pool by ObjId
.
However, accessing an object with invalid ObjId
will result in panic.
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let a = obj_pool.insert(10);
let b = obj_pool.insert(20);
assert_eq!(obj_pool[a], 10);
assert_eq!(obj_pool[b], 20);
obj_pool[a] += obj_pool[b];
assert_eq!(obj_pool[a], 30);
To access slots without fear of panicking, use get
and get_mut
, which return Option
s.
Implementations
sourceimpl<T> ObjPool<T>
impl<T> ObjPool<T>
sourcepub const fn new() -> Self
pub const fn new() -> Self
Constructs a new, empty object pool.
The object pool will not allocate until objects are inserted into it.
Examples
use obj_pool::ObjPool;
let mut obj_pool: ObjPool<i32> = ObjPool::new();
sourcepub const fn obj_id_to_index(obj_id: ObjId) -> u32
pub const fn obj_id_to_index(obj_id: ObjId) -> u32
Get an index in the ObjPool
for the given ObjId
.
sourcepub fn index_to_obj_id(index: u32) -> ObjId
pub fn index_to_obj_id(index: u32) -> ObjId
Make an ObjId
from an index in this ObjPool
.
sourcepub fn with_capacity(cap: usize) -> Self
pub fn with_capacity(cap: usize) -> Self
Constructs a new, empty object pool with the specified capacity (number of slots).
The object pool will be able to hold exactly capacity
objects without reallocating.
If capacity
is 0, the object pool will not allocate.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::with_capacity(10);
assert_eq!(obj_pool.len(), 0);
assert_eq!(obj_pool.capacity(), 10);
// These inserts are done without reallocating...
for i in 0..10 {
obj_pool.insert(i);
}
assert_eq!(obj_pool.capacity(), 10);
// ... but this one will reallocate.
obj_pool.insert(11);
assert!(obj_pool.capacity() > 10);
sourcepub fn capacity(&self) -> usize
pub fn capacity(&self) -> usize
Returns the number of slots in the object pool.
Examples
use obj_pool::ObjPool;
let obj_pool: ObjPool<i32> = ObjPool::with_capacity(10);
assert_eq!(obj_pool.capacity(), 10);
sourcepub fn len(&self) -> u32
pub fn len(&self) -> u32
Returns the number of occupied slots in the object pool.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
assert_eq!(obj_pool.len(), 0);
for i in 0..10 {
obj_pool.insert(());
assert_eq!(obj_pool.len(), i + 1);
}
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true
if all slots are vacant.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
assert!(obj_pool.is_empty());
obj_pool.insert(1);
assert!(!obj_pool.is_empty());
sourcepub fn next_vacant(&mut self) -> ObjId
pub fn next_vacant(&mut self) -> ObjId
Returns the ObjId
of the next inserted object if no other
mutating calls take place in between.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let a = obj_pool.next_vacant();
let b = obj_pool.insert(1);
assert_eq!(a, b);
let c = obj_pool.next_vacant();
let d = obj_pool.insert(2);
assert_eq!(c, d);
sourcepub fn insert(&mut self, object: T) -> ObjId
pub fn insert(&mut self, object: T) -> ObjId
Inserts an object into the object pool and returns the ObjId
of this object.
The object pool will reallocate if it’s full.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let a = obj_pool.insert(1);
let b = obj_pool.insert(2);
assert!(a != b);
sourcepub fn remove(&mut self, obj_id: ObjId) -> Option<T>
pub fn remove(&mut self, obj_id: ObjId) -> Option<T>
Removes the object stored by ObjId
from the object pool and returns it.
None
is returned in case the there is no object with such an ObjId
.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let a = obj_pool.insert("hello");
assert_eq!(obj_pool.len(), 1);
assert_eq!(obj_pool.remove(a), Some("hello"));
assert_eq!(obj_pool.len(), 0);
assert_eq!(obj_pool.remove(a), None);
sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Clears the object pool, removing and dropping all objects it holds. Keeps the allocated memory for reuse.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
for i in 0..10 {
obj_pool.insert(i);
}
assert_eq!(obj_pool.len(), 10);
obj_pool.clear();
assert_eq!(obj_pool.len(), 0);
sourcepub fn get(&self, obj_id: ObjId) -> Option<&T>
pub fn get(&self, obj_id: ObjId) -> Option<&T>
Returns a reference to the object by its ObjId
.
If object is not found with given obj_id
, None
is returned.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let obj_id = obj_pool.insert("hello");
assert_eq!(obj_pool.get(obj_id), Some(&"hello"));
obj_pool.remove(obj_id);
assert_eq!(obj_pool.get(obj_id), None);
sourcepub fn get_mut(&mut self, obj_id: ObjId) -> Option<&mut T>
pub fn get_mut(&mut self, obj_id: ObjId) -> Option<&mut T>
Returns a mutable reference to the object by its ObjId
.
If object can’t be found, None
is returned.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let obj_id = obj_pool.insert(7);
assert_eq!(obj_pool.get_mut(obj_id), Some(&mut 7));
*obj_pool.get_mut(obj_id).unwrap() *= 10;
assert_eq!(obj_pool.get_mut(obj_id), Some(&mut 70));
sourcepub unsafe fn get_unchecked(&self, obj_id: ObjId) -> &T
pub unsafe fn get_unchecked(&self, obj_id: ObjId) -> &T
sourcepub unsafe fn get_unchecked_mut(&mut self, obj_id: ObjId) -> &mut T
pub unsafe fn get_unchecked_mut(&mut self, obj_id: ObjId) -> &mut T
sourcepub fn swap(&mut self, a: ObjId, b: ObjId)
pub fn swap(&mut self, a: ObjId, b: ObjId)
Swaps two objects in the object pool.
The two ObjId
s are a
and b
.
Panics
Panics if any of the ObjId
s is invalid.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
let a = obj_pool.insert(7);
let b = obj_pool.insert(8);
obj_pool.swap(a, b);
assert_eq!(obj_pool.get(a), Some(&8));
assert_eq!(obj_pool.get(b), Some(&7));
sourcepub fn reserve(&mut self, additional: u32)
pub fn reserve(&mut self, additional: u32)
Reserves capacity for at least additional
more objects to be inserted. The object pool may
reserve more space to avoid frequent reallocations.
Panics
Panics if the new capacity overflows u32
.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
obj_pool.insert("hello");
obj_pool.reserve(10);
assert!(obj_pool.capacity() >= 11);
sourcepub fn reserve_exact(&mut self, additional: u32)
pub fn reserve_exact(&mut self, additional: u32)
Reserves the minimum capacity for exactly additional
more objects to be inserted.
Note that the allocator may give the object pool more space than it requests.
Panics
Panics if the new capacity overflows u32
.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
obj_pool.insert("hello");
obj_pool.reserve_exact(10);
assert!(obj_pool.capacity() >= 11);
sourcepub fn iter(&self) -> Iter<'_, T>ⓘNotable traits for Iter<'a, T>impl<'a, T> Iterator for Iter<'a, T> type Item = (ObjId, &'a T);
pub fn iter(&self) -> Iter<'_, T>ⓘNotable traits for Iter<'a, T>impl<'a, T> Iterator for Iter<'a, T> type Item = (ObjId, &'a T);
Returns an iterator over occupied slots.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
obj_pool.insert(1);
obj_pool.insert(2);
obj_pool.insert(4);
let mut iterator = obj_pool.iter();
assert_eq!(iterator.next(), Some((ObjPool::<usize>::index_to_obj_id(0), &1)));
assert_eq!(iterator.next(), Some((ObjPool::<usize>::index_to_obj_id(1), &2)));
assert_eq!(iterator.next(), Some((ObjPool::<usize>::index_to_obj_id(2), &4)));
sourcepub fn iter_mut(&mut self) -> IterMut<'_, T>ⓘNotable traits for IterMut<'a, T>impl<'a, T> Iterator for IterMut<'a, T> type Item = (ObjId, &'a mut T);
pub fn iter_mut(&mut self) -> IterMut<'_, T>ⓘNotable traits for IterMut<'a, T>impl<'a, T> Iterator for IterMut<'a, T> type Item = (ObjId, &'a mut T);
Returns an iterator that returns mutable references to objects.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::new();
obj_pool.insert("zero".to_string());
obj_pool.insert("one".to_string());
obj_pool.insert("two".to_string());
for (obj_id, object) in obj_pool.iter_mut() {
*object = obj_id.into_index().to_string() + " " + object;
}
let mut iterator = obj_pool.iter();
assert_eq!(iterator.next(), Some((ObjPool::<String>::index_to_obj_id(0), &"0 zero".to_string())));
assert_eq!(iterator.next(), Some((ObjPool::<String>::index_to_obj_id(1), &"1 one".to_string())));
assert_eq!(iterator.next(), Some((ObjPool::<String>::index_to_obj_id(2), &"2 two".to_string())));
sourcepub fn shrink_to_fit(&mut self)
pub fn shrink_to_fit(&mut self)
Shrinks the capacity of the object pool as much as possible.
It will drop down as close as possible to the length but the allocator may still inform the object pool that there is space for a few more elements.
Examples
use obj_pool::ObjPool;
let mut obj_pool = ObjPool::with_capacity(10);
obj_pool.insert("first".to_string());
obj_pool.insert("second".to_string());
obj_pool.insert("third".to_string());
assert_eq!(obj_pool.capacity(), 10);
obj_pool.shrink_to_fit();
assert!(obj_pool.capacity() >= 3);