Trait KeyConfig

Source

pub unsafe trait KeyConfig:
    Copy
    + Eq
    + Hash
    + Send
    + Sync
    + 'static {
    type Idx: KeyPiece;
    type Gen: KeyPiece;

    // Required methods
    fn max_idx() -> Self::Idx;
    fn max_generation() -> Odd<Self::Gen>;
    unsafe fn pack_unchecked(idx: Self::Idx, generation: Odd<Self::Gen>) -> Self;
    fn idx(self) -> Self::Idx;
    fn generation(self) -> Odd<Self::Gen>;

    // Provided method
    fn pack(idx: Self::Idx, generation: Odd<Self::Gen>) -> Option<Self> { ... }
}

Expand description

Chooses the index and generation types of a Key, and how the key stores the two. A Key<K> holds a value of its key config K, and that value holds the index and the generation.

Split<Idx, Gen> keeps the index and the generation as two fields, and Packed<R, GEN_BITS> puts them in the bits of one integer. Either one can be the KeyConfig of a MapConfig.

§Examples

use gen_map::{Key, Packed, Split};

// These keys keep a `u16` index and a `u16` generation as two fields.
assert_eq!(core::mem::size_of::<Key<Split<u16, u16>>>(), 4);

// These keys keep 24 bits of index and 8 bits of generation in one `u32`.
assert_eq!(core::mem::size_of::<Key<Packed<u32, 8>>>(), 4);

§Safety

The maps’ unsafe code relies on what a key config returns. For a value that pack_unchecked made, idx and generation must return exactly the index and the generation that pack_unchecked was given, and two values must be equal only if they unpack to the same parts. max_idx and max_generation must return the same value every time, because the maps pack parts again long after they first checked them against those limits.

Safe code can make a key from any value of the key config it can build, with Key::from_repr, and read the key’s parts through the safe idx and generation methods. So every value that safe code can build must unpack to an odd generation, since generation returns an Odd. It must also unpack to an index of at most max_idx and a generation of at most max_generation. A key config whose fields are private and whose values only come from pack_unchecked, like Split and Packed, meets these rules.