A small list of entity references allocated from a pool.
An EntityList<T>
type provides similar functionality to Vec<T>
, but with some important
differences in the implementation:
- Memory is allocated from a
ListPool<T>
instead of the global heap.
- The footprint of an entity list is 4 bytes, compared with the 24 bytes for
Vec<T>
.
- An entity list doesn't implement
Drop
, leaving it to the pool to manage memory.
The list pool is intended to be used as a LIFO allocator. After building up a larger data
structure with many list references, the whole thing can be discarded quickly by clearing the
pool.
Entity lists are not as safe to use as Vec<T>
, but they never jeopardize Rust's memory safety
guarantees. These are the problems to be aware of:
- If you lose track of an entity list, its memory won't be recycled until the pool is cleared.
This can cause the pool to grow very large with leaked lists.
- If entity lists are used after their pool is cleared, they may contain garbage data, and
modifying them may corrupt other lists in the pool.
- If an entity list is used with two different pool instances, both pools are likely to become
corrupted.
Entity lists can be cloned, but that operation should only be used as part of cloning the whole
function they belong to. Cloning an entity list does not allocate new memory for the clone.
It creates an alias of the same memory.
Entity lists cannot be hashed and compared for equality because it's not possible to compare the
contents of the list without the pool reference.
The EntityList
itself is designed to have the smallest possible footprint. This is important
because it is used inside very compact data structures like InstructionData
. The list
contains only a 32-bit index into the pool's memory vector, pointing to the first element of
the list.
The pool is just a single Vec<T>
containing all of the allocated lists. Each list is
represented as three contiguous parts:
- The number of elements in the list.
- The list elements.
- Excess capacity elements.
The total size of the three parts is always a power of two, and the excess capacity is always
as small as possible. This means that shrinking a list may cause the excess capacity to shrink
if a smaller power-of-two size becomes available.
Both growing and shrinking a list may cause it to be reallocated in the pool vector.
The index stored in an EntityList
points to part 2, the list elements. The value 0 is
reserved for the empty list which isn't allocated in the vector.
Create a new list with the contents initialized from a slice.
Returns true
if the list has a length of 0.
Get the number of elements in the list.
Returns true
if the list is valid
Get a single element from the list.
Get the first element from the list.
Get the list as a mutable slice.
Get a mutable reference to a single element from the list.
Removes all elements from the list.
The memory used by the list is put back in the pool.
Take all elements from this list and return them as a new list. Leave this list empty.
This is the equivalent of Option::take()
.
Appends an element to the back of the list.
Returns the index where the element was inserted.
Appends multiple elements to the back of the list.
Inserts an element as position index
in the list, shifting all elements after it to the
right.
Removes the element at position index
from the list. Potentially linear complexity.
Removes the element at index
in constant time by switching it with the last element of
the list.
Grow the list by inserting count
elements at index
.
The new elements are not initialized, they will contain whatever happened to be in memory.
Since the memory comes from the pool, this will be either zero entity references or
whatever where in a previously deallocated list.
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
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static
Creates owned data from borrowed data, usually by cloning. Read more
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more