Struct Pool 

pub struct Pool<T, P = Option<T>>
where
    T: Sized,
    P: PayloadContainer<Element = T>,
{ /* private fields */ }

Pool allows to create as many objects as you want in contiguous memory block. It allows to create and delete objects much faster than if they’ll be allocated on heap. Also since objects stored in contiguous memory block they can be effectively accessed because such memory layout is cache-friendly.

Implementations

impl<T, P> Pool<T, P>

where P: PayloadContainer<Element = T> + 'static,

pub fn new() -> Self

pub fn with_capacity(capacity: u32) -> Self

pub fn spawn(&mut self, payload: T) -> Handle<T>

pub fn spawn_at(&mut self, index: u32, payload: T) -> Result<Handle<T>, T>

Tries to put an object in the pool at given position. Returns Err(payload) if a corresponding entry is occupied.

Performance

The method has O(n) complexity in worst case, where n - amount of free records in the pool. In typical uses cases n is very low. It should be noted that if a pool is filled entirely and you trying to put an object at the end of pool, the method will have O(1) complexity.

Panics

Panics if the index is occupied or reserved (e.g. by take_reserve).

pub fn spawn_at_handle( &mut self, handle: Handle<T>, payload: T, ) -> Result<Handle<T>, T>

Tries to put an object in the pool at given handle. Returns Err(payload) if a corresponding entry is occupied.

Performance

The method has O(n) complexity in worst case, where n - amount of free records in the pool. In typical uses cases n is very low. It should be noted that if a pool is filled entirely and you trying to put an object at the end of pool, the method will have O(1) complexity.

Panics

Panics if the index is occupied or reserved (e.g. by take_reserve).

pub fn spawn_with<F: FnOnce(Handle<T>) -> T>( &mut self, callback: F, ) -> Handle<T>

Construct a value with the handle it would be given. Note: Handle is not valid until function has finished executing.

pub async fn spawn_with_async<F, Fut>(&mut self, callback: F) -> Handle<T>

where F: FnOnce(Handle<T>) -> Fut, Fut: Future<Output = T>,

Asynchronously construct a value with the handle it would be given. Note: Handle is not valid until function has finished executing.

pub fn generate_free_handles(&self, amount: usize) -> Vec<Handle<T>>

Generates a set of handles that could be used to spawn a set of objects. This method does not modify the pool and the generated handles could be used together with Self::spawn_at_handle method.

pub fn borrow(&self, handle: Handle<T>) -> &T

Borrows shared reference to an object by its handle.

Panics

Panics if handle is out of bounds or generation of handle does not match with generation of pool record at handle index (in other words it means that object at handle’s index is different than the object was there before).

pub fn borrow_mut(&mut self, handle: Handle<T>) -> &mut T

Borrows mutable reference to an object by its handle.

Panics

Panics if handle is out of bounds or generation of handle does not match with generation of pool record at handle index (in other words it means that object at handle’s index is different than the object was there before).

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
let a = pool.spawn(1);
let a = pool.borrow_mut(a);
*a = 11;

pub fn try_borrow(&self, handle: Handle<T>) -> Option<&T>

Borrows shared reference to an object by its handle.

Returns None if handle is out of bounds or generation of handle does not match with generation of pool record at handle index (in other words it means that object at handle’s index is different than the object was there before).

pub fn try_borrow_mut(&mut self, handle: Handle<T>) -> Option<&mut T>

Borrows mutable reference to an object by its handle.

Returns None if handle is out of bounds or generation of handle does not match with generation of pool record at handle index (in other words it means that object at handle’s index is different than the object was there before).

pub fn borrow_two_mut( &mut self, handles: (Handle<T>, Handle<T>), ) -> (&mut T, &mut T)

Borrows mutable references of objects at the same time. This method will succeed only if handles are unique (not equal). Borrowing multiple mutable references at the same time is useful in case if you need to mutate some objects at the same time.

Panics

See borrow_mut.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
let a = pool.spawn(1);
let b = pool.spawn(2);
let (a, b) = pool.borrow_two_mut((a, b));
*a = 11;
*b = 22;

pub fn borrow_three_mut( &mut self, handles: (Handle<T>, Handle<T>, Handle<T>), ) -> (&mut T, &mut T, &mut T)

Borrows mutable references of objects at the same time. This method will succeed only if handles are unique (not equal). Borrowing multiple mutable references at the same time is useful in case if you need to mutate some objects at the same time.

Panics

See borrow_mut.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
let a = pool.spawn(1);
let b = pool.spawn(2);
let c = pool.spawn(3);
let (a, b, c) = pool.borrow_three_mut((a, b, c));
*a = 11;
*b = 22;
*c = 33;

pub fn borrow_four_mut( &mut self, handles: (Handle<T>, Handle<T>, Handle<T>, Handle<T>), ) -> (&mut T, &mut T, &mut T, &mut T)

Borrows mutable references of objects at the same time. This method will succeed only if handles are unique (not equal). Borrowing multiple mutable references at the same time is useful in case if you need to mutate some objects at the same time.

Panics

See borrow_mut.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
let a = pool.spawn(1);
let b = pool.spawn(2);
let c = pool.spawn(3);
let d = pool.spawn(4);
let (a, b, c, d) = pool.borrow_four_mut((a, b, c, d));
*a = 11;
*b = 22;
*c = 33;
*d = 44;

pub fn try_borrow_dependant_mut<F>( &mut self, handle: Handle<T>, func: F, ) -> (Option<&mut T>, Option<&mut T>)

where F: FnOnce(&T) -> Handle<T>,

Tries to borrow two objects when a handle to the second object stored in the first object.

pub fn free(&mut self, handle: Handle<T>) -> T

Moves object out of the pool using the given handle. All handles to the object will become invalid.

Panics

Panics if the given handle is invalid.

pub fn try_free(&mut self, handle: Handle<T>) -> Option<T>

Tries to move object out of the pool using the given handle. Returns None if given handle is invalid. After object is moved out if the pool, all handles to the object will become invalid.

pub fn take_reserve(&mut self, handle: Handle<T>) -> (Ticket<T>, T)

Moves an object out of the pool using the given handle with a promise that the object will be returned back. Returns pair (ticket, value). The ticket must be used to put the value back!

Motivation

This method is useful when you need to take temporary ownership of an object, do something with it and then put it back while preserving all handles to it and being able to put new objects into the pool without overriding the payload at its handle.

Notes

All handles to the object will be temporarily invalid until the object is returned to the pool! The pool record will be reserved for a further put_back call, which means if you lose the ticket you will have an empty “unusable” pool record forever.

Panics

Panics if the given handle is invalid.

pub fn try_take_reserve(&mut self, handle: Handle<T>) -> Option<(Ticket<T>, T)>

Does the same as take_reserve but returns an option, instead of panicking.

pub fn put_back(&mut self, ticket: Ticket<T>, value: T) -> Handle<T>

Returns the value back into the pool using the given ticket. See take_reserve for more information.

pub fn forget_ticket(&mut self, ticket: Ticket<T>)

Forgets that value at ticket was reserved and makes it usable again. Useful when you don’t need to put value back by ticket, but just make pool record usable again.

pub fn get_capacity(&self) -> u32

Returns total capacity of pool. Capacity has nothing about real amount of objects in pool!

pub fn clear(&mut self)

Destroys all objects in pool. All handles to objects will become invalid.

Remarks

Use this method cautiously if objects in pool have cross “references” (handles) to each other. This method will make all produced handles invalid and any further calls for borrow or borrow_mut will raise panic.

pub fn at_mut(&mut self, n: u32) -> Option<&mut T>

pub fn at(&self, n: u32) -> Option<&T>

pub fn handle_from_index(&self, n: u32) -> Handle<T>

pub fn alive_count(&self) -> u32

Returns the exact number of “alive” objects in the pool.

Records that have been reserved (e.g. by take_reserve) are not counted.

It iterates through the entire pool to count the live objects so the complexity is O(n).

See also total_count.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
pool.spawn(123);
pool.spawn(321);
assert_eq!(pool.alive_count(), 2);

pub fn total_count(&self) -> u32

Returns the number of allocated objects in the pool.

It also counts records that have been reserved (e.g. by take_reserve).

This method is O(1).

See also alive_count.

pub fn replace(&mut self, handle: Handle<T>, payload: T) -> Option<T>

pub fn first_ref(&self) -> Option<&T>

Returns a reference to the first element in the pool (if any).

pub fn first_mut(&mut self) -> Option<&mut T>

Returns a reference to the first element in the pool (if any).

pub fn is_valid_handle(&self, handle: Handle<T>) -> bool

Checks if given handle “points” to some object.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
let handle = pool.spawn(123);
assert_eq!(pool.is_valid_handle(handle), true)

pub fn iter(&self) -> PoolIterator<'_, T, P>

Creates new pool iterator that iterates over filled records in pool.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
pool.spawn(123);
pool.spawn(321);
let mut iter = pool.iter();
assert_eq!(*iter.next().unwrap(), 123);
assert_eq!(*iter.next().unwrap(), 321);

pub fn pair_iter(&self) -> PoolPairIterator<'_, T, P>

Creates new pair iterator that iterates over filled records using pair (handle, payload) Can be useful when there is a need to iterate over pool records and know a handle of that record.

pub fn iter_mut(&mut self) -> PoolIteratorMut<'_, T, P>

Creates new pool iterator that iterates over filled records in pool allowing to modify record payload.

Example

use fyrox_core::pool::Pool;
let mut pool = Pool::<u32>::new();
pool.spawn(123);
pool.spawn(321);
let mut iter = pool.iter_mut();
assert_eq!(*iter.next().unwrap(), 123);
assert_eq!(*iter.next().unwrap(), 321);

pub fn pair_iter_mut(&mut self) -> PoolPairIteratorMut<'_, T, P>

Creates new pair iterator that iterates over filled records using pair (handle, payload) Can be useful when there is a need to iterate over pool records and know a handle of that record.

pub fn retain<F>(&mut self, pred: F)

where F: FnMut(&T) -> bool,

Retains pool records selected by pred. Useful when you need to remove all pool records by some criteria.

pub fn begin_multi_borrow(&mut self) -> MultiBorrowContext<'_, T, P>

Begins multi-borrow that allows you to borrow as many (N) unique references to the pool elements as you need. See MultiBorrowContext::try_get for more info.

pub fn drain(&mut self) -> impl Iterator<Item = T> + '_

Removes all elements from the pool.

pub fn handle_of(&self, ptr: &T) -> Handle<T>

impl<T, P> Pool<T, P>

where T: ComponentProvider, P: PayloadContainer<Element = T> + 'static,

pub fn try_get_component_of_type<C>(&self, handle: Handle<T>) -> Option<&C>

where C: 'static,

Tries to mutably borrow an object and fetch its component of specified type.

pub fn try_get_component_of_type_mut<C>( &mut self, handle: Handle<T>, ) -> Option<&mut C>

where C: 'static,

Tries to mutably borrow an object and fetch its component of specified type.

Trait Implementations

impl<T: Clone> Clone for Pool<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, P> Debug for Pool<T, P>

where T: Sized + Debug, P: PayloadContainer<Element = T> + Debug,

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

Formats the value using the given formatter.

impl<T, P> Default for Pool<T, P>

where T: 'static, P: PayloadContainer<Element = T> + 'static,

fn default() -> Self

Returns the “default value” for a type.

impl<T> FromIterator<T> for Pool<T>

where T: 'static,

fn from_iter<C: IntoIterator<Item = T>>(iter: C) -> Self

Creates a value from an iterator.

impl<T, P> Index<Handle<T>> for Pool<T, P>

where T: 'static, P: PayloadContainer<Element = T> + 'static,

type Output = T

The returned type after indexing.

fn index(&self, index: Handle<T>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, P> IndexMut<Handle<T>> for Pool<T, P>

where T: 'static, P: PayloadContainer<Element = T> + 'static,

fn index_mut(&mut self, index: Handle<T>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T, P> IntoIterator for &'a Pool<T, P>

where P: PayloadContainer<Element = T> + 'static,

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = PoolIterator<'a, T, P>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, P> IntoIterator for &'a mut Pool<T, P>

where P: PayloadContainer<Element = T> + 'static,

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = PoolIteratorMut<'a, T, P>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, P> PartialEq for Pool<T, P>

where T: PartialEq, P: PayloadContainer<Element = T> + PartialEq,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, P> Reflect for Pool<T, P>

where T: Reflect, P: PayloadContainer<Element = T> + Reflect,

fn source_path() -> &'static str

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

fn into_any(self: Box<Self>) -> Box<dyn Any>

fn as_any(&self, func: &mut dyn FnMut(&dyn Any))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut dyn Any))

fn as_reflect(&self, func: &mut dyn FnMut(&dyn Reflect))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut dyn Reflect))

fn set( &mut self, value: Box<dyn Reflect>, ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>

fn assembly_name(&self) -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn type_assembly_name() -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn as_array(&self, func: &mut dyn FnMut(Option<&dyn ReflectArray>))

fn as_array_mut(&mut self, func: &mut dyn FnMut(Option<&mut dyn ReflectArray>))

fn set_field( &mut self, field: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>), )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn fields(&self, func: &mut dyn FnMut(&[&dyn Reflect]))

fn fields_mut(&mut self, func: &mut dyn FnMut(&mut [&mut dyn Reflect]))

fn field(&self, name: &str, func: &mut dyn FnMut(Option<&dyn Reflect>))

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut dyn Reflect>), )

fn as_list(&self, func: &mut dyn FnMut(Option<&dyn ReflectList>))

fn as_list_mut(&mut self, func: &mut dyn FnMut(Option<&mut dyn ReflectList>))

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&dyn ReflectInheritableVariable>), )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut dyn ReflectInheritableVariable>), )

fn as_hash_map(&self, func: &mut dyn FnMut(Option<&dyn ReflectHashMap>))

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut dyn ReflectHashMap>), )

impl<T, P> ReflectArray for Pool<T, P>

where T: Reflect, P: PayloadContainer<Element = T> + Reflect,

fn reflect_index(&self, index: usize) -> Option<&dyn Reflect>

fn reflect_index_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>

fn reflect_len(&self) -> usize

impl<T, P> Visit for Pool<T, P>

where T: Visit + 'static, P: PayloadContainer<Element = T> + Default + Visit + 'static,

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> VisitResult

Read or write this value, depending on whether Visitor::is_reading() is true or false.