Struct genmap::Handle

pub struct Handle { /* fields omitted */ }

A Rust crate for a generational map, handle map, whatever you want to call it. Whatever it is, this is a random-access data structure that stores an unordered bag of items and gives you a handle for each specific item you insert. Looking things up by handle is O(1) -- the backing storage is just a Vec -- and items can be removed as well, which is also O(1). Handles are small (two usize's) and easy to copy, similar to a slice. The trick is that there is a generation number stored with each item, so that a "dangling" handle that refers to an item that has been removed is invalid. Unlike array indices, if you remove an item from the array and a new one gets put in its place, the old stale handle does not refer to the new one and trying to use it will fail at runtime.

This is useful for various things: managing lots of uniform things with shared ownership (such as video game resources), interning strings, that sort of thing. Essentially by using handles to items you have runtime-checked memory safety: you can get an item from the map using the handle, since it's basically just an array index.

In practice this is not unrelated to Rc, it's just that Rc does the accounting of memory on cloning the Rc, and this does it on "dereferencing" by looking up an object's handle. Referencing counting, threading garbage collection and this sort of map are all different methods of achieving the same thing (checking for memory safety at runtime) with different tradeoffs. With a reference count you don't have to explicitly free items and can't have stale handles, but loops require special handling and you pay for the accounting cost on cloning a handle. With this you have to free items explicitly, but stale handles can be safely detected and the accounting happens when you look the item up. You can also use it as a slab allocator type thing, where you pre-allocate a large amount of storage and free it all at once. A small, easy-to-copy handle referring to a location in a particular GenMap.

Handles from one GenMap are not valid to use in a different GenMap, and this can not be detected at runtime. It is recommended to wrap handles in a newtype struct to make sure at compile-time that you have the right one. Support for this may become built in to the API, but for the moment it's unclear how to do it best.

Trait Implementations

impl Ord for Handle

fn cmp(&self, other: &Handle) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialOrd<Handle> for Handle

fn partial_cmp(&self, other: &Handle) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Handle) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Handle) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Handle) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Handle) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialEq<Handle> for Handle

fn eq(&self, other: &Handle) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Handle) -> bool

This method tests for !=.

impl Clone for Handle

fn clone(&self) -> Handle

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Eq for Handle

impl Copy for Handle

impl Debug for Handle

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for Handle

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].