Struct broom::Heap

pub struct Heap<T> { /* private fields */ }

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

impl<T: Trace<T>> Heap<T>

pub fn new() -> Self

Create an empty heap.

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.

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.

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

pub fn len(&self) -> usize

Count the number of heap-allocated objects in this heap

pub fn contains(&self, handle: impl AsRef<Handle<T>>) -> bool

Return true if the heap contains the specified handle

pub fn get(&self, handle: impl AsRef<Handle<T>>) -> Option<&T>

Get a reference to a heap object if it exists on this heap.

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.

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

Get a mutable reference to a heap object

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.

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

pub fn clean(&mut self)

Clean orphaned objects from the heap.

Trait Implementations

impl<T> Default for Heap<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for Heap<T>

fn drop(&mut self)

Executes the destructor for this type.