Struct Locksmith 

pub struct Locksmith { /* private fields */ }

Factory for distributing lock scope capabilities across threads or cores.

Program-wide singleton – only one Locksmith can exist at a time. Created via new (with a limit) or unlimited (no limit). Issues KeyVouchers that can be sent to target threads/cores and redeemed for KeyHandles.

!Send, !Sync – stays on the creating thread/core. Only the vouchers travel.

Caveats

The singleton invariant relies on a global AtomicBool. On Unix, fork() duplicates the parent’s memory – including the flag – into the child process. The child inherits LOCKSMITH_EXISTS = true but has no Locksmith value, so it can never create one and the flag is never cleared. Avoid fork() after creating a Locksmith, or use exec immediately (the standard fork/exec pattern resets the address space).

Implementations

impl Locksmith

pub fn new(limit: usize) -> Option<Self>

Try to create a new Locksmith with the given voucher limit.

Returns None if a Locksmith already exists. Only one can exist at a time (enforced via a global AtomicBool). When the Locksmith is dropped, the slot is released.

pub fn unlimited() -> Option<Self>

Try to create a Locksmith with no voucher limit.

Returns None if a Locksmith already exists. issue() will always succeed (no limit check).

pub fn create(limit: usize) -> Self

Create a Locksmith with the given limit, panicking if one already exists.

Panics

Panics if a Locksmith already exists.

pub fn create_unlimited() -> Self

Create an unlimited Locksmith, panicking if one already exists.

Panics

Panics if a Locksmith already exists.

pub fn issue(&self) -> Option<KeyVoucher>

Issue a KeyVoucher.

Returns None if the limit has been reached. If the Locksmith is unlimited, always returns Some.

The voucher is Send and can be transferred to another thread or core.

The counter only increments – slots are not reclaimed when vouchers or key handles are dropped. For embedded systems with static core counts, issue exactly N vouchers at init.

pub fn issued(&self) -> usize

Number of vouchers issued so far.

pub const fn limit(&self) -> Option<usize>

The configured limit, or None if unlimited.

pub fn remaining(&self) -> Option<usize>

Remaining vouchers that can be issued, or None if unlimited.

Trait Implementations

impl Debug for Locksmith

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

Formats the value using the given formatter.

impl Drop for Locksmith

fn drop(&mut self)

Executes the destructor for this type.