Struct SecretPool 

pub struct SecretPool<const N: usize, const SLOTS: usize> { /* private fields */ }

Fixed-slot arena for many same-size secrets inside one locked mapping.

SecretPool<N, SLOTS> amortizes platform memory-locking overhead when an application needs many fixed-size secrets at once. Instead of using one locked page-backed mapping per secret, the pool creates one private locked mapping large enough for SLOTS slots of N bytes and hands out lifetime-bound SecretPoolSlot handles.

Slots borrow the pool, so Rust prevents the pool from being dropped while a slot is still live. Dropping a slot volatile-clears exactly that slot and returns it to the pool. Dropping the pool volatile-clears the full mapping before unlocking and releasing it.

Implementations

impl<const N: usize, const SLOTS: usize> SecretPool<N, SLOTS>

pub fn new() -> Result<Self, MemoryLockError>

Create a locked pool with SLOTS fixed-size slots of N bytes.

This performs one platform mapping and one platform lock operation for the whole arena. The requested mapping length is rounded to the platform page granule, so the pool also clears padding bytes on drop.

pub const fn slot_size(&self) -> usize

Number of bytes in each slot.

pub const fn capacity_slots(&self) -> usize

Number of slots in the pool.

pub const fn is_empty(&self) -> bool

Returns true when the pool cannot hold any secret bytes.

pub const fn locked_len(&self) -> usize

Rounded platform mapping length locked by this pool.

pub fn available_slots(&self) -> usize

Count slots that are currently available.

This is a point-in-time observation. Other threads may allocate or release slots immediately after this method returns.

pub fn allocate(&self) -> Option<SecretPoolSlot<'_, N, SLOTS>>

Allocate one unused slot from the pool.

Returns None when every slot is currently allocated. The returned slot starts zeroed if it has never been used before, or freshly zeroed from the previous slot drop.

With random-canary, operating-system CSPRNG failure is also reported as None. Use SecretPool::try_allocate when the caller needs to distinguish pool exhaustion from random-canary setup failure.

pub fn try_allocate( &self, ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, MemoryLockError>

Allocate one unused slot from the pool and report random-canary setup errors explicitly.

This is equivalent to SecretPool::allocate unless the random-canary feature is enabled. With random-canary, operating system CSPRNG failure is returned as MemoryLockError instead of panicking.

pub fn allocate_from_slice( &self, source: &[u8], ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, LengthError>

Allocate a slot and copy bytes from a same-length slice.

Returns Ok(None) when the pool is full. A length mismatch returns an error without allocating a slot.

pub fn allocate_from_array( &self, bytes: [u8; N], ) -> Option<SecretPoolSlot<'_, N, SLOTS>>

Allocate a slot, copy an owned array into it, then clear the input array with the crate’s volatile wipe backend.

pub fn allocate_from_fn( &self, make_byte: impl FnMut(usize) -> u8, ) -> Option<SecretPoolSlot<'_, N, SLOTS>>

Allocate a slot and generate each byte directly inside it.

pub fn try_allocate_from_fn<E>( &self, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, E>

Allocate a slot and fallibly generate each byte directly inside it.

If generation fails, the partially initialized slot is volatile-cleared and returned to the pool before the error is returned.

pub fn secure_clear(&mut self)

Clear the full locked mapping and mark every slot available.

This requires &mut self, so Rust prevents it while any live slot handle still borrows the pool.

pub fn secure_clear_and_flush(&mut self)

Trait Implementations

impl<const N: usize, const SLOTS: usize> Debug for SecretPool<N, SLOTS>

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

Formats the value using the given formatter.

impl<const N: usize, const SLOTS: usize> Drop for SecretPool<N, SLOTS>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<const N: usize, const SLOTS: usize> SecureSanitize for SecretPool<N, SLOTS>

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

impl<const N: usize, const SLOTS: usize> Send for SecretPool<N, SLOTS>

impl<const N: usize, const SLOTS: usize> Sync for SecretPool<N, SLOTS>