Struct Registry

Source

pub struct Registry<T, ID: IdTrait = Id<T>> { /* private fields */ }

Expand description

A container that issues IDs and maps them to stored values, also called a “slot map” or an “arena”.

Implementations§

Source §

impl<T> Registry<T, Id<T>>

Source

pub fn new() -> Self

Construct a new, empty Registry<T> with the default Id type.

The Registry will not allocate until elements are inserted into it.

Examples found in repository ?

examples/alice_bob.rs (line 25)

24fn main() {
25    let mut people = People::new();
26    let alice_id = new_person(&mut people, "Alice");
27    let bob_id = new_person(&mut people, "Bob");
28    add_friend(&mut people, alice_id, bob_id);
29    add_friend(&mut people, bob_id, alice_id);
30    add_friend(&mut people, alice_id, alice_id); // no-op
31}

More examples

Hide additional examples

examples/player_resource.rs (line 39)

37fn main() {
38    let mut state = GameState {
39        players: Registry::new(),
40        resources: Registry::new(),
41    };
42    let player_id = new_player(&mut state);
43    let resource_id = new_resource(&mut state, player_id);
44    assert_eq!(state.resources[resource_id].owner_id, player_id);
45    assert!(state.players[player_id].resource_ids.contains(&resource_id));
46}

Source

pub fn with_capacity(capacity: usize) -> Self

Construct a new, empty Registry<T> with the default Id type and with at least the specified capacity.

Source §

impl<T, ID: IdTrait> Registry<T, ID>

Source

pub fn with_id_type() -> Self

Construct a new, empty Registry<T> with a custom ID type.

The Registry will not allocate until elements are inserted into it.

§Example

use riddance::{Id, Registry};

type TypeErasedId = Id<()>;

let mut registry: Registry::<String, TypeErasedId> = Registry::with_id_type();
let id: TypeErasedId = registry.insert(String::from("foo"));

Source

pub fn with_id_type_and_capacity(capacity: usize) -> Self

Construct a new, empty Registry<T> with a custom ID type and with at least the specified capacity.

Source

pub fn len(&self) -> usize

Returns the number of elements in the Registry.

Source

pub fn contains_id(&self, id: ID) -> bool

Returns true if the Registry contains the given id. If remove has been called on id, contains_id will return false.

Source

pub fn get(&self, id: ID) -> Option<&T>

Get a reference to an element. If remove has been called on id, get will return None.

Source

pub fn get_mut(&mut self, id: ID) -> Option<&mut T>

Get a mutable reference to an element. If remove has been called on id, get_mut will return None.

Source

pub unsafe fn get_unchecked(&self, id: ID) -> &T

Get a reference to an element without checking the size of the Registry or the generation of the ID.

This function is safe if and only if self.contains_id(id) is true.

Source

pub unsafe fn get_unchecked_mut(&mut self, id: ID) -> &mut T

Get a mutable reference to an element without checking the size of the Registry or the generation of the ID.

This function is safe if and only if self.contains_id(id) is true.

Source

pub fn insert(&mut self, value: T) -> ID

Adds a value to the Registry and returns an ID that can be used to access that element.

Examples found in repository ?

examples/player_resource.rs (lines 24-27)

23fn new_player(state: &mut GameState) -> PlayerId {
24    state.players.insert(Player {
25        points: 0,
26        resource_ids: Vec::new(),
27    })
28}
29
30fn new_resource(state: &mut GameState, owner_id: PlayerId) -> ResourceId {
31    let new_id = state.resources.insert(Resource { owner_id });
32    state.players[owner_id].resource_ids.push(new_id);
33    state.players[owner_id].points += 30;
34    new_id
35}

More examples

Hide additional examples

examples/alice_bob.rs (lines 12-15)

11fn new_person(people: &mut People, name: &str) -> PersonId {
12    people.insert(Person {
13        name: name.into(),
14        friends: Vec::new(),
15    })
16}

Source

pub fn remove(&mut self, id: ID) -> Option<T>

If id refers to an element in the Registry, remove the element and return it.

This method returns Some if any only if contains_id would have returned true. After calling remove on an ID, that ID and any copies of it become “dangling”. contains_id will return false, and get, get_mut, and any further calls to remove will return None.

Calling remove on an ID that has been reserved with reserve_id or reserve_ids but not yet given a value with insert_reserved, will free the reserved slot and return None.

pub fn reserve_id(&self) -> ID

Reserve an ID that you can insert a value for later.

Note that this method doesn’t require mutable access to the Registry. It uses an atomic cursor internally, and you can reserve an ID while other threads are e.g. reading existing elements.

Until you call insert_reserved, the reserved slot is empty, and contains_id will report false for the reserved ID. Similarly, get and get_mut will return None. If a reservation is no longer needed, you can remove it without inserting a value.

Whenever you call a &mut self method that might change the size of the Registry or its free list (insert, insert_reserved, remove, or recycle_retired), the Registry will automatically allocate space for any pending reservations. You can optionally call allocate_reservations to do this work in advance.

To reserve many IDs at once, see reserve_ids.

Source

pub fn reserve_ids(&self, count: usize) -> ReservationIter<'_, T, ID> ⓘ

Reserve a range of IDs that you can insert values for later.

See reserve_id.

Note that unconsumed IDs in this iterator are not returned to the Registry when you drop it, and the slots they refer to are effectively leaked. If you reserved more IDs than you need, you can save them for later, or you can remove them when you have mutable access to the Registry.

Source

pub fn allocate_reservations(&mut self)

Allocate space for reserved slots.

See reserve_id and reserve_ids. This method is called internally by any method that might change the size of the Registry or its free list (insert, insert_reserved, remove, or recycle_retired), so you don’t need to call it explicitly unless you want to force the allocation to happen sooner.

Source

pub fn insert_reserved( &mut self, id: ID, value: T, ) -> Result<(), InsertReservedError<T>>

Insert a value for a reserved ID.

See reserve_id and reserve_ids. Empty reservations can be filled in any order. If you try to fill a reservation multiple times, or if you call this method with IDs that aren’t reserved, it will return an error.

Source

pub fn recycle_retired(&mut self)

Mark all retired slots as free, making them available for future insertions and reservations.

Callers using Registry with the default Id type shouldn’t need this method. Id has 31 generation bits, so the retirement rate is one slot per ~2 billion removals, too slow to matter in almost any practical case. This method is intended for callers using Id32.

Dangling IDs (that is, IDs passed to remove) from before the call to recycle_retired must not be used again with any method on this Registry. Generally callers should delete all dangling IDs (or replace them with null) before calling recycle_retired. If you retain dangling IDs across a call to recycle_retired, they can collide with newly issued IDs, and calls to get, get_mut, and contains_id can return confusing results. Calling insert_reserved on these IDs can also lead to memory leaks. This behavior is memory-safe, but these are logic bugs, similar to the logic bugs that can arise if you modify a key after it’s been inserted into a HashMap.

§Panics

Registry makes a best effort to detect violations of this rule. Any method on Registry may panic if it sees an ID generation that’s newer than the corresponding slot. These checks are currently only done in debug mode, but this is not guaranteed.

Source