Module coca::collections::pool

Pool-based memory management.

A pool takes ownership of inserted values and returns unique, stable handles that can be used to refer back to those same values later on. While it is safe to index into a pool with a handle obtained from a different one, this is nonsensical; to avoid this mistake, users may define custom handle types using the handle_type! macro.

Each handle contains a generation identifier, so that, should a value be removed and a new one be inserted at the same location, the old handle remains invalid.

Note that the generation count may overflow, so this cannot be strictly guaranteed for arbitrarily long sequences of insertions and deletions. 64-bit handles use 32-bit generation identifiers, making such errors highly unlikely. Care must be taken with 32-bit handles, however, which may use as few as 16 bits:

handle_type! { TinyHandle: 16 / 32; }

let mut pool: coca::collections::DirectArenaPool<&'static str, TinyHandle> = arena.with_capacity(4);
let first = pool.insert("this was first");

let mut last_handle = first;
for _ in 0..0x8000 {
    pool.remove(last_handle);
    last_handle = pool.insert("this is not first");
}

assert_eq!(pool[first], "this is not first");

Modules

direct

Object pools with direct indexing using stable handles.

packed

Densely packed object pools with indirect indexing using stable handles.

Structs

DefaultHandle

The default pool handle type, with 32 bits each for the index and generation count.

Traits

Handle

Stable references to values stored in a pool.