intid_allocator/
lib.rs

1//! Allocates integer ids which implement [`intid::IntegerIdCounter`].
2//!
3//! Use [`IdAllocator`] if you want to be able to [free](IdAllocator::free) existing ids for reuse.
4//! This will minimize the integer value of the keys, reducing memory needed for lookup tables.
5//!
6//! Use [`UniqueIdAllocator`] or [`UniqueIdAllocatorAtomic`] if you don't care about reusing existing keys.
7//! These are more efficient and never require any allocation.
8#![cfg_attr(not(feature = "std"), no_std)]
9#![deny(unsafe_code)] // not needed yet
10
11#[cfg(feature = "alloc")]
12extern crate alloc;
13
14use core::fmt::{Debug, Display, Formatter};
15use core::marker::PhantomData;
16use intid::IntegerId;
17
18#[cfg(feature = "alloc")]
19mod reusing;
20mod unique;
21
22#[cfg(feature = "alloc")]
23pub use self::reusing::IdAllocator;
24#[cfg(feature = "atomic")]
25pub use self::unique::atomic::UniqueIdAllocatorAtomic;
26pub use self::unique::UniqueIdAllocator;
27
28/// Indicates that available ids have been exhausted,
29/// and can no longer be allocated.
30#[derive(Clone)]
31pub struct IdExhaustedError<T: IntegerId> {
32    marker: PhantomData<T>,
33}
34impl<T: IntegerId> IdExhaustedError<T> {
35    /// Indicate that ids have been exhausted for the type `T`,
36    /// without giving any additional information.
37    #[inline]
38    #[cold]
39    #[allow(clippy::new_without_default)] // doesn't make much sense for an error
40    pub fn new() -> Self {
41        IdExhaustedError {
42            marker: PhantomData,
43        }
44    }
45
46    /// Trigger a descriptive panic due to this error.
47    ///
48    /// This gives a better panic message than calling [`Result::unwrap`].
49    #[track_caller]
50    #[cold]
51    pub fn panic(self) -> ! {
52        panic!("{self}")
53    }
54}
55impl<T: IntegerId> Display for IdExhaustedError<T> {
56    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
57        write!(f, "Ran out of ids for {}", core::any::type_name::<T>())
58    }
59}
60impl<T: IntegerId> Debug for IdExhaustedError<T> {
61    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
62        f.debug_struct("IdExhaustedError")
63            .field("type_name", &core::any::type_name::<T>())
64            .finish_non_exhaustive()
65    }
66}
67
68#[rustversion::since(1.81)]
69impl<T: IntegerId> core::error::Error for IdExhaustedError<T> {}
70
71#[rustversion::before(1.81)]
72#[cfg(feature = "std")]
73impl<T: IntegerId> std::error::Error for IdExhaustedError<T> {}
intid_allocator/lib.rs

intid_allocator/
lib.rs
