pub struct Arena<K, T, const N: usize>where
K: Kind,{ /* private fields */ }Expand description
N slots of T, addressed by generational Handle<K>.
Implementations§
Source§impl<K, T, const N: usize> Arena<K, T, N>
impl<K, T, const N: usize> Arena<K, T, N>
Sourcepub fn new() -> Arena<K, T, N>
pub fn new() -> Arena<K, T, N>
An empty arena.
Not const: a free slot holds T::default() and Default is not a
const trait. Nothing built one in a const context — only size_of
names the type there, which needs no value.
Sourcepub fn insert(&mut self, value: T) -> Result<Handle<K>, Error>
pub fn insert(&mut self, value: T) -> Result<Handle<K>, Error>
Place value in a free slot and return its handle.
§Errors
Error::NoMemory when every slot is occupied; the value is
returned to the caller inside the error’s companion so nothing is
lost — see Arena::try_insert.
Sourcepub fn try_insert(&mut self, value: T) -> Result<Handle<K>, T>
pub fn try_insert(&mut self, value: T) -> Result<Handle<K>, T>
Like Arena::insert, but hands the value back when there is no room.
§Errors
The value itself, when every slot is occupied.
Sourcepub fn get_mut(&mut self, handle: Handle<K>) -> Option<&mut T>
pub fn get_mut(&mut self, handle: Handle<K>) -> Option<&mut T>
The object handle names, mutably.
Sourcepub fn resolve(&self, handle: Handle<K>) -> Result<&T, Error>
pub fn resolve(&self, handle: Handle<K>) -> Result<&T, Error>
Like Arena::get, but says why: Error::InvalidHandle for the
null handle or an index beyond the arena, Error::Gone for a
generation that has been reused or freed.
§Errors
As above.
Sourcepub fn discard(&mut self, handle: Handle<K>) -> bool
pub fn discard(&mut self, handle: Handle<K>) -> bool
Remove the object handle names, invalidating the handle and every
copy of it.
Free the slot handle names without handing the value back.
Same state change as Arena::remove – FREE set, len
decremented, the old handle dead – but it does not MOVE the value out,
and that is the whole point. remove answers Option<T>, which for a
Tcb is over a hundred bytes returned THROUGH MEMORY: the caller gets a
stack buffer, mem::take copies the value into it, and T::default()
is written over the slot with a memset CALL. Every arena removal in
this kernel is spelled let _ = ...remove(x) – not one reads the value
– so all of that filled a buffer that is dropped on the next line.
Leaving the old value in the slot is sound because nothing can reach it:
the slot’s generation now carries [FREE], which no handle can equal,
and try_insert overwrites the value before handing out a new handle.
It is the same argument Arena::remove’s own doc makes about the
generation bump, applied to the value as well.
Drop is the one thing that cannot be left to chance, so it is not:
needs_drop is a const fn, so for a T that owns something this
still writes the default and runs the old value’s destructor exactly
where remove ran it, and for plain data the whole branch folds away.
Returns whether a live object was there.
Sourcepub fn remove(&mut self, handle: Handle<K>) -> Option<T>
pub fn remove(&mut self, handle: Handle<K>) -> Option<T>
Take the value out and free its slot, if handle still names it.
None for a handle that is stale, forged or already removed – and the
slot’s generation moves on, so no copy of this handle resolves again.
Sourcepub fn iter(&self) -> impl Iterator<Item = (Handle<K>, &T)>
pub fn iter(&self) -> impl Iterator<Item = (Handle<K>, &T)>
Every live (handle, object) in slot order.