pub struct Heap<T> { /* private fields */ }
Expand description
A heap for storing objects.
Heap
is the centre of broom
’s universe. It’s the singleton through with manipulation of
objects occurs. It can be used to create, access, mutate and garbage-collect objects.
Note that heaps, and the objects associated with them, are not compatible: this means that
you may not create trace routes (see Trace
) that cross the boundary between different heaps.
Implementations
sourceimpl<T: Trace<T>> Heap<T>
impl<T: Trace<T>> Heap<T>
sourcepub fn insert_temp(&mut self, object: T) -> Handle<T>
pub fn insert_temp(&mut self, object: T) -> Handle<T>
Adds a new object to this heap that will be cleared upon the next garbage collection, if not attached to the object tree.
sourcepub fn insert(&mut self, object: T) -> Rooted<T>
pub fn insert(&mut self, object: T) -> Rooted<T>
Adds a new object to this heap that will not be cleared by garbage collection until all rooted handles have been dropped.
sourcepub fn make_rooted(&mut self, handle: impl AsRef<Handle<T>>) -> Rooted<T>
pub fn make_rooted(&mut self, handle: impl AsRef<Handle<T>>) -> Rooted<T>
Upgrade a handle (that will be cleared by the garbage collector) into a rooted handle (that will not).
sourcepub fn contains(&self, handle: impl AsRef<Handle<T>>) -> bool
pub fn contains(&self, handle: impl AsRef<Handle<T>>) -> bool
Return true if the heap contains the specified handle
sourcepub fn get(&self, handle: impl AsRef<Handle<T>>) -> Option<&T>
pub fn get(&self, handle: impl AsRef<Handle<T>>) -> Option<&T>
Get a reference to a heap object if it exists on this heap.
sourcepub unsafe fn get_unchecked(&self, handle: impl AsRef<Handle<T>>) -> &T
pub unsafe fn get_unchecked(&self, handle: impl AsRef<Handle<T>>) -> &T
Get a reference to a heap object without checking whether it is still alive or that it belongs to this heap.
If either invariant is not upheld, calling this function results in undefined behaviour.
sourcepub fn get_mut(&mut self, handle: impl AsRef<Handle<T>>) -> Option<&mut T>
pub fn get_mut(&mut self, handle: impl AsRef<Handle<T>>) -> Option<&mut T>
Get a mutable reference to a heap object
sourcepub unsafe fn get_mut_unchecked(
&mut self,
handle: impl AsRef<Handle<T>>
) -> &mut T
pub unsafe fn get_mut_unchecked(
&mut self,
handle: impl AsRef<Handle<T>>
) -> &mut T
Get a mutable reference to a heap object without first checking that it is still alive or that it belongs to this heap.
If either invariant is not upheld, calling this function results in undefined behaviour. Provided they are upheld, this function provides zero-cost access.
sourcepub fn clean_excluding(&mut self, excluding: impl IntoIterator<Item = Handle<T>>)
pub fn clean_excluding(&mut self, excluding: impl IntoIterator<Item = Handle<T>>)
Clean orphaned objects from the heap, excluding those that can be reached from the given handle iterator.
This function is useful in circumstances in which you wish to keep certain items alive over
a garbage collection without the addition cost of a Rooted
handle. An example of this
might be stack items in a garbage-collected language