Struct Pool 

pub struct Pool<T> { /* private fields */ }

A slotmap-style arena: values in, Handles out.

Insertion recycles free slots through a free list, so live values stay densely packed near the front of the backing Vec under steady-state churn. Every removal bumps the slot’s generation, so handles issued before the removal stop resolving.

Generation exhaustion

Generations are 32-bit and never wrap. A slot that has been recycled u32::MAX - 1 times is retired: its storage is dropped, the slot is removed from the free list, and it is never handed out again. Wrapping would silently resurrect a >4-billion-removals-old handle as a valid alias for an unrelated value — a bug that would surface as impossible-looking aliasing weeks into a server’s uptime. Retiring instead costs one dead Vec entry (a few bytes) per exhausted slot, and only after ~4.3e9 reuses of that one slot: at 60 Hz, recycling the same slot every tick, that is over two years of continuous churn. See Pool::retired_slots to observe it.

Safety

This module contains no unsafe. The Vec<Slot<T>> + enum payload costs one discriminant per slot versus a hand-rolled MaybeUninit arena; clarity wins at this layer, and the pool is not in any inner loop that measures.

Implementations

impl<T> Pool<T>

pub const fn new() -> Self

Creates an empty pool.

pub fn with_capacity(capacity: usize) -> Self

Creates an empty pool with room for capacity slots.

pub const fn len(&self) -> usize

Number of live values.

pub const fn is_empty(&self) -> bool

Whether the pool holds no live values.

pub const fn retired_slots(&self) -> usize

Number of slots permanently withdrawn by generation exhaustion.

Expected to be zero forever; a non-zero value in a long-running server is worth a metric, not an alarm.

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

Inserts value and returns a handle to it.

Panics

If the pool would exceed u32::MAX + 1 slots — the index is 32-bit by design, and a pool that large is a leak, not a workload.

pub fn get(&self, handle: Handle<T>) -> Option<&T>

Borrows the value handle names, or None if the handle is stale.

pub fn get_mut(&mut self, handle: Handle<T>) -> Option<&mut T>

Mutably borrows the value handle names, or None if the handle is stale.

pub fn contains(&self, handle: Handle<T>) -> bool

Whether handle still resolves.

pub fn remove(&mut self, handle: Handle<T>) -> Option<T>

Removes and returns the value handle names, invalidating every handle to that slot.

Returns None (and changes nothing) if the handle is already stale.

pub fn clear(&mut self)

Removes every value, invalidating all outstanding handles.

Slot storage is kept for reuse; generations continue from where they were, so handles issued before the clear stay dead.

pub fn iter(&self) -> impl Iterator<Item = (Handle<T>, &T)>

Iterates live (handle, &value) pairs in slot order.

pub fn iter_mut(&mut self) -> impl Iterator<Item = (Handle<T>, &mut T)>

Iterates live (handle, &mut value) pairs in slot order.

Trait Implementations

impl<T> Debug for Pool<T>

Deliberately does not print the values: a pool is usually large, and this impl must exist for every T, not just T: Debug.

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

Formats the value using the given formatter.

impl<T> Default for Pool<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Extend<T> for Pool<T>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<T> FromIterator<T> for Pool<T>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.