Struct fyrox_core::pool::Pool

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

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§

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).

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).

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

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

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).

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;

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).

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).

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;

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;

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;

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

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.

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.

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.

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

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

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.

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

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.

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);

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.

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)

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);

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.

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);

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.

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

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

Removes all elements from the pool.

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
Creates a value from an iterator. Read more
The returned type after indexing.
Performs the indexing (container[index]) operation. Read more
Performs the mutable indexing (container[index]) operation. Read more
The type of the elements being iterated over.
Which kind of iterator are we turning this into?
Creates an iterator from a value. Read more
The type of the elements being iterated over.
Which kind of iterator are we turning this into?
Creates an iterator from a value. Read more
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Casts self to a &dyn Any

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self
The inverse inclusion map: attempts to construct self from the equivalent element of its superset. Read more
Checks if self is actually part of its subset T (and can be converted to it).
Use with care! Same as self.to_subset but without any property checks. Always succeeds.
The inclusion map: converts self to the equivalent element of its superset.
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.