Struct midenc_hir::ArenaMap

pub struct ArenaMap<K: EntityRef, V> { /* private fields */ }

ArenaMap provides similar functionality to other kinds of maps:

Pros

• Once allocated, values stored in the map have a stable location, this can be useful for when you expect to store elements of the map in an intrusive collection.
• Keys can be more efficiently sized, i.e. rather than pointers/usize keys, you can choose arbitrarily small bitwidths, as long as there is sufficient keyspace for your use case.
• Attempt to keep data in the map as contiguous in memory as possible. This is again useful for when the data is also linked into an intrusive collection, like a linked list, where traversing the list will end up visiting many of the nodes in the map. If each node was its own Box, this would cause thrashing of the cache - ArenaMap sidesteps this by allocating values in chunks of memory that are friendlier to the cache.

Cons

• Memory allocated for data stored in the map is not released until the map is dropped. This is a tradeoff made to ensure that the data has a stable location in memory, but the flip side of that is increased memory usage for maps that stick around for a long time. In our case, these maps are relatively short-lived, so it isn’t a problem in practice.
• It doesn’t provide as rich of an API as HashMap and friends

Implementations

impl<K: EntityRef, V> ArenaMap<K, V>

pub fn new() -> Self

Creates a new, empty ArenaMap

pub fn is_empty(&self) -> bool

Returns true if this ArenaMap is empty

pub fn len(&self) -> usize

Returns the total number of actively linked items in the map

pub fn contains(&self, key: K) -> bool

Returns true if this map contains key

pub fn push(&mut self, value: V) -> K

Adds a new entry to the map, returning the key it is associated to

pub fn append(&mut self, key: K, value: V)

Used in conjunction with alloc_key to associate data with the allocated key

pub fn get(&self, key: K) -> Option<&V>

Returns a reference to the value associated with the given key

pub fn get_mut(&mut self, key: K) -> Option<&mut V>

Returns a mutable reference to the value associated with the given key

pub unsafe fn get_raw(&self, key: K) -> Option<NonNull<V>>

Returns a raw pointer to the value associated with the given key

Safety

This function is unsafe, since the resulting pointer could outlive the arena itself, or be used to incorrectly alias a value for which a mutable reference exists.

To safely use this function, callers must never construct a reference from the pointer unless they can guarantee that the data pointed to is immutable, or can be safely accessed using atomic operations. No other uses are permitted, unless you want to shoot yourself in the foot.

pub fn take(&mut self, key: K) -> Option<NonNull<V>>

Takes the value that was stored at the given key

pub fn iter(&self) -> impl Iterator<Item = Option<NonNull<V>>> + '_

pub fn remove(&mut self, key: K)

Removes the value associated with the given key

NOTE: This function will panic if the key is invalid/unbound

pub fn alloc_key(&mut self) -> K

Trait Implementations

impl<K: EntityRef, V: Clone> Clone for ArenaMap<K, V>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: EntityRef, V> Default for ArenaMap<K, V>

fn default() -> Self

Returns the “default value” for a type.

impl<K: EntityRef, V> Drop for ArenaMap<K, V>

fn drop(&mut self)

Executes the destructor for this type.

impl<K: EntityRef, V> Index<K> for ArenaMap<K, V>

type Output = V

The returned type after indexing.

fn index(&self, index: K) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<K: EntityRef, V> IndexMut<K> for ArenaMap<K, V>

fn index_mut(&mut self, index: K) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.