Surelock

https://docs.rs/surelock/0.1.0
Admin
Surelock is a Rust library that prevents deadlocks through atomic multi-lock acquisition and...
Tokens:79,563
Snippets:683
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Lock a Mutex

Source: https://docs.rs/surelock/0.1.0/index.html

A basic example demonstrating how to initialize a Mutex and increment its value within a lock scope. This is the simplest way to use Surelock.

```rust
use surelock::{key::lock_scope, mutex::Mutex};

let counter: Mutex<u32> = Mutex::new(0);

lock_scope(|key| {
    let (mut guard, _key) = key.lock(&counter);
    *guard += 1;
});
```

--------------------------------

### KeyHandle Example Usage

Source: https://docs.rs/surelock/0.1.0/surelock/key_handle/struct.KeyHandle.html

Demonstrates how to claim a KeyHandle and use its scope to acquire locks.

```APIDOC
## Examples

```rust
use surelock::{key_handle::KeyHandle, mutex::Mutex};

let mut handle = KeyHandle::claim();

handle.scope(|key| {
    let m: Mutex<u32> = Mutex::new(42);
    let (guard, _key) = key.lock(&m);
    assert_eq!(*guard, 42);
});

// Sequential scopes are fine
handle.scope(|key| {
    // fresh scope, new key at Bottom
});

// Nesting is a compile error:
// handle.scope(|key1| {
//     handle.scope(|key2| { ... });
//     ^^^^ error: already mutably borrowed
// });
```
```

--------------------------------

### KeyHandle Usage Example

Source: https://docs.rs/surelock/0.1.0/src/surelock/key_handle.rs.html

Demonstrates the basic usage of KeyHandle for creating lock scopes and acquiring locks within those scopes. Shows sequential scopes and highlights the compile-time error for nested scopes.

```rust
use surelock::{key_handle::KeyHandle, mutex::Mutex};

let mut handle = KeyHandle::claim();

handle.scope(|key| {
    let m: Mutex<u32> = Mutex::new(42);
    let (guard, _key) = key.lock(&m);
    assert_eq!(*guard, 42);
});

// Sequential scopes are fine
handle.scope(|key| {
    // fresh scope, new key at Bottom
});

// Nesting is a compile error:
// handle.scope(|key1| {
//     handle.scope(|key2| { ... });
//     ^^^^ error: already mutably borrowed
// });
```

--------------------------------

### Example Usage of KeyVoucher

Source: https://docs.rs/surelock/0.1.0/src/surelock/key_voucher.rs.html

Demonstrates issuing a KeyVoucher from a Locksmith, sending it to another thread, and redeeming it to obtain a KeyHandle for locking operations.

```rust
#![allow(unsafe_code)]
//! Transferable token redeemable for a [`KeyHandle`].
//!
//! A [`KeyVoucher`] is issued by a [`Locksmith`](crate::locksmith::Locksmith)
//! and can be sent (`Send`) to another thread or core. On arrival,
//! call [`redeem`](KeyVoucher::redeem) to obtain a
//! [`KeyHandle`] for that execution context.
//!
//! `Send`, `!Clone`, `!Copy` -- each voucher is a unique, single-use token.
//!
//! # Examples
//!
//! ```rust
//! use surelock::locksmith::Locksmith;
//!
//! let smith = Locksmith::new(2).unwrap();
//! let voucher = smith.issue().unwrap();
//!
//! // Send voucher to another thread...
//! let handle = std::thread::spawn(move || {
//!     let mut key_handle = voucher.redeem().unwrap();
//!     key_handle.scope(|key| {
//!         // lock things...
//!     });
//! });
//! handle.join().unwrap();
//! ```

```

--------------------------------

### Mutex with Custom Backend Example

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Shows how to define a `Mutex` with a specific backend, `spin::mutex::SpinMutex`, and a base level. This is useful for environments where the standard library's mutex is not available or a different mutex implementation is preferred.

```rust
use surelock::{key::lock_scope, mutex::Mutex};

type M<T> = Mutex<T, surelock::level::Base, spin::mutex::SpinMutex<()>>;
let counter: M<u32> = Mutex::new(0);
```

--------------------------------

### Create and Use Locksmith

Source: https://docs.rs/surelock/0.1.0/src/surelock/locksmith.rs.html

Instantiate a Locksmith with a specified voucher limit and issue vouchers. The example demonstrates reaching the limit.

```rust
use surelock::locksmith::Locksmith;

let smith = Locksmith::new(4).unwrap(); // 4-core system

let _v0 = smith.issue().unwrap();
let _v1 = smith.issue().unwrap();
let _v2 = smith.issue().unwrap();
let _v3 = smith.issue().unwrap();
assert!(smith.issue().is_none()); // limit reached

```

--------------------------------

### Claiming and Using KeyHandle for Lock Scopes

Source: https://docs.rs/surelock/0.1.0/surelock/key_handle/struct.KeyHandle.html

Demonstrates how to claim a KeyHandle for the current thread and use its `scope` method to acquire locks within a closure. This example shows a successful lock acquisition and highlights that sequential scopes are permitted, while nested scopes result in a compile-time error.

```rust
use surelock::{key_handle::KeyHandle, mutex::Mutex};

let mut handle = KeyHandle::claim();

handle.scope(|key| {
    let m: Mutex<u32> = Mutex::new(42);
    let (guard, _key) = key.lock(&m);
    assert_eq!(*guard, 42);
});

// Sequential scopes are fine
handle.scope(|key| {
    // fresh scope, new key at Bottom
});

// Nesting is a compile error:
// handle.scope(|key1| {
//     handle.scope(|key2| {
//         // ... 
//     });
//     // ^^^^ error: already mutably borrowed
// });
```

--------------------------------

### Quick Start: Lock and Increment Mutex

Source: https://docs.rs/surelock/0.1.0/src/surelock/lib.rs.html

Demonstrates the basic usage of Surelock to lock a Mutex and modify its value within a scope.

```rust
use surelock::{key::lock_scope, mutex::Mutex};

let counter: Mutex<u32> = Mutex::new(0);

lock_scope(|key| {
    let (mut guard, _key) = key.lock(&counter);
    *guard += 1;
});

```

--------------------------------

### MaxLevel Implementations

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.MaxLevel.html

Provides examples of MaxLevel trait implementations for various Level types, demonstrating how the Max associated type is determined for different combinations.

```APIDOC
### Implementors

#### impl MaxLevel<Level<0>> for Level<0>
##### type Max = Level<0>

#### impl MaxLevel<Level<0>> for Level<1>
##### type Max = Level<1>

#### impl MaxLevel<Level<0>> for Level<2>
##### type Max = Level<2>

#### impl MaxLevel<Level<0>> for Level<3>
##### type Max = Level<3>

#### impl MaxLevel<Level<0>> for Level<4>
##### type Max = Level<4>

#### impl MaxLevel<Level<0>> for Level<5>
##### type Max = Level<5>

#### impl MaxLevel<Level<0>> for Level<6>
##### type Max = Level<6>

#### impl MaxLevel<Level<0>> for Level<7>
##### type Max = Level<7>

#### impl MaxLevel<Level<0>> for Level<8>
##### type Max = Level<8>

#### impl MaxLevel<Level<0>> for Level<9>
##### type Max = Level<9>

#### impl MaxLevel<Level<0>> for Level<10>
##### type Max = Level<10>

#### impl MaxLevel<Level<0>> for Level<11>
##### type Max = Level<11>

#### impl MaxLevel<Level<0>> for Level<12>
##### type Max = Level<12>

#### impl MaxLevel<Level<0>> for Level<13>
##### type Max = Level<13>

#### impl MaxLevel<Level<0>> for Level<14>
##### type Max = Level<14>

#### impl MaxLevel<Level<0>> for Level<15>
##### type Max = Level<15>

#### impl MaxLevel<Level<1>> for Level<0>
##### type Max = Level<1>

#### impl MaxLevel<Level<1>> for Level<1>
##### type Max = Level<1>

#### impl MaxLevel<Level<1>> for Level<2>
##### type Max = Level<2>

#### impl MaxLevel<Level<1>> for Level<3>
##### type Max = Level<3>

#### impl MaxLevel<Level<1>> for Level<4>
##### type Max = Level<4>

#### impl MaxLevel<Level<1>> for Level<5>
##### type Max = Level<5>

#### impl MaxLevel<Level<1>> for Level<6>
##### type Max = Level<6>

#### impl MaxLevel<Level<1>> for Level<7>
##### type Max = Level<7>

#### impl MaxLevel<Level<1>> for Level<8>
##### type Max = Level<8>

#### impl MaxLevel<Level<1>> for Level<9>
##### type Max = Level<9>

#### impl MaxLevel<Level<1>> for Level<10>
##### type Max = Level<10>

#### impl MaxLevel<Level<1>> for Level<11>
##### type Max = Level<11>

#### impl MaxLevel<Level<1>> for Level<12>
##### type Max = Level<12>

#### impl MaxLevel<Level<1>> for Level<13>
##### type Max = Level<13>

#### impl MaxLevel<Level<1>> for Level<14>
##### type Max = Level<14>

#### impl MaxLevel<Level<1>> for Level<15>
##### type Max = Level<15>

#### impl MaxLevel<Level<2>> for Level<0>
##### type Max = Level<2>

#### impl MaxLevel<Level<2>> for Level<1>
##### type Max = Level<2>

#### impl MaxLevel<Level<2>> for Level<2>
##### type Max = Level<2>

#### impl MaxLevel<Level<2>> for Level<3>
##### type Max = Level<3>

#### impl MaxLevel<Level<2>> for Level<4>
##### type Max = Level<4>

#### impl MaxLevel<Level<2>> for Level<5>
##### type Max = Level<5>

#### impl MaxLevel<Level<2>> for Level<6>
##### type Max = Level<6>

#### impl MaxLevel<Level<2>> for Level<7>
##### type Max = Level<7>

#### impl MaxLevel<Level<2>> for Level<8>
##### type Max = Level<8>

#### impl MaxLevel<Level<2>> for Level<9>
##### type Max = Level<9>

#### impl MaxLevel<Level<2>> for Level<10>
##### type Max = Level<10>

#### impl MaxLevel<Level<2>> for Level<11>
##### type Max = Level<11>

#### impl MaxLevel<Level<2>> for Level<12>
##### type Max = Level<12>

#### impl MaxLevel<Level<2>> for Level<13>
##### type Max = Level<13>

#### impl MaxLevel<Level<2>> for Level<14>
##### type Max = Level<14>

#### impl MaxLevel<Level<2>> for Level<15>
##### type Max = Level<15>

#### impl MaxLevel<Level<3>> for Level<0>
##### type Max = Level<3>

#### impl MaxLevel<Level<3>> for Level<1>
##### type Max = Level<3>

#### impl MaxLevel<Level<3>> for Level<2>
##### type Max = Level<3>

#### impl MaxLevel<Level<3>> for Level<3>
##### type Max = Level<3>

#### impl MaxLevel<Level<3>> for Level<4>
##### type Max = Level<4>

#### impl MaxLevel<Level<3>> for Level<5>
##### type Max = Level<5>
```

--------------------------------

### KeyVoucher::redeem (no_std)

Source: https://docs.rs/surelock/0.1.0/src/surelock/key_voucher.rs.html

Redeems this voucher for a KeyHandle on the current execution context. This is infallible on no_std, as per-context uniqueness is a setup discipline.

```APIDOC
## redeem (no_std)

### Description
Redeems this voucher for a [`KeyHandle`] on the current
execution context.

On `no_std`, this is infallible -- per-context uniqueness is
a setup discipline.

### Method
```rust
#[allow(clippy::expect_used)]
#[cfg(not(feature = "std"))]
pub fn redeem(self) -> KeyHandle
```

### Parameters
None

### Panics
Panics if `KeyHandle::try_claim` returns `None`. This is
unreachable on `no_std` (where `try_claim` always succeeds) but is retained as a defensive assertion.

### Response
#### Success Response
- `KeyHandle`: The redeemed KeyHandle.
```

--------------------------------

### Get Configured Voucher Limit

Source: https://docs.rs/surelock/0.1.0/src/surelock/locksmith.rs.html

Returns the maximum number of vouchers that can be issued. Returns `None` if there is no limit.

```rust
pub const fn limit(&self) -> Option<usize> {
        self.limit
    }
```

--------------------------------

### Get TypeId of KeyVoucher

Source: https://docs.rs/surelock/0.1.0/surelock/key_voucher/struct.KeyVoucher.html

Gets the TypeId of the KeyVoucher. This is part of the Any trait implementation.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Get Mutex ID

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Retrieves the unique `LockId` associated with this mutex instance.

```rust
pub const fn id(&self) -> LockId {
    self.id
}
```

--------------------------------

### Get Locksmith Voucher Limit

Source: https://docs.rs/surelock/0.1.0/surelock/locksmith/struct.Locksmith.html

Returns the configured voucher limit for this Locksmith, or None if it is unlimited.

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

--------------------------------

### Surelock Key Patterns

Source: https://docs.rs/surelock/0.1.0/index.html

Demonstrates common usage patterns for Surelock, including entering scopes, locking single mutexes or lock sets, and using lock closures for one-shot operations. Also shows how to create nested sub-scopes.

```rust
handle.scope(|key| { ... });
```

```rust
let (guard, key) = key.lock(&mutex);
```

```rust
let ((ga, gb), key) = key.lock(&set);
```

```rust
let (val, key) = key.lock_with(&mutex, |guard| *guard);
```

```rust
let (result, key) = key.subscope(|inner_key| { ... });
```

--------------------------------

### MinLevel Implementations for Level<1>

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.MinLevel.html

These implementations demonstrate how Level<1> interacts with other levels, showing the minimum level when Level<1> is involved.

```rust
impl MinLevel<Level<1>> for Level<0> {
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<1>> for Level<1> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<2> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<3> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<4> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<5> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<6> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<7> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<8> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<9> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<10> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<11> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<12> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<13> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<14> {
    type Min = Level<1>;
}
```

```rust
impl MinLevel<Level<1>> for Level<15> {
    type Min = Level<1>;
}
```

--------------------------------

### Get Number of Issued Vouchers

Source: https://docs.rs/surelock/0.1.0/surelock/locksmith/struct.Locksmith.html

Returns the total number of vouchers issued so far by this Locksmith. The counter only increments.

```rust
pub fn issued(&self) -> usize
```

--------------------------------

### Mutex Construction in SureLock

Source: https://docs.rs/surelock/0.1.0/src/surelock/lib.rs.html

Demonstrates different ways to construct Mutex instances, including specifying levels and using method syntax.

```rust
Mutex::new(data)                     // Level<0>, default backend
Mutex::new_higher(data, &parent)      // parent.level + 1
Mutex::new_higher(data, (&a, &b))     // max(levels) + 1
```

```rust
// Method syntax (also works with Arc, Rc, Box)
parent.new_higher(data)               // parent.level + 1, inherits backend
(&a, &b).new_higher(data)             // max(levels) + 1
```

--------------------------------

### Get Remaining Issuable Vouchers

Source: https://docs.rs/surelock/0.1.0/surelock/locksmith/struct.Locksmith.html

Returns the number of vouchers that can still be issued, or None if the Locksmith is unlimited. This accounts for the limit.

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

--------------------------------

### Try to create a LockSet, handling duplicate locks

Source: https://docs.rs/surelock/0.1.0/src/surelock/set.rs.html

Shows how to use `try_new` to create a LockSet, which returns `None` if duplicate locks are detected. This is a non-panicking alternative to `new`.

```rust
use surelock::{mutex::Mutex, set::LockSet};

let a: Mutex<u32> = Mutex::new(1);
let b: Mutex<u32> = Mutex::new(2);

// Distinct locks -- succeeds.
assert!(LockSet::try_new((&a, &b)).is_some());

// Same lock twice -- returns None.
assert!(LockSet::try_new((&a, &a)).is_none());

```

--------------------------------

### StdMutex::new

Source: https://docs.rs/surelock/0.1.0/surelock/raw_mutex/std_mutex/struct.StdMutex.html

Creates a new, unlocked StdMutex instance at runtime.

```APIDOC
## StdMutex::new

### Description
Create a new unlocked instance.

### Signature
```rust
fn new() -> Self
```
```

--------------------------------

### MutexRef Implementations

Source: https://docs.rs/surelock/0.1.0/surelock/mutex/struct.Mutex.html

Provides access to the underlying data, level, and raw mutex, along with methods to get the mutex ID and acquire a lock reference.

```APIDOC
## impl<'a, T: 'a, Lvl: IsLevel, R: RawMutex + 'a> MutexRef<'a> for &'a Box<Mutex<T, Lvl, R>>

### Type Aliases
- **Data**: `T` - The data type guarded by the mutex.
- **Lvl**: `Lvl` - The level of the mutex.
- **RawMtx**: `R` - The raw mutex backend.

### Methods
- **id(&self) -> LockId**: Return this mutex’s `LockId`.
- **lock_ref(&'a self) -> MutexGuard<'a, R, T>**: Lock the mutex and return the guard.

## impl<'a, T: 'a, Lvl: IsLevel, R: RawMutex + 'a> MutexRef<'a> for &'a Mutex<T, Lvl, R>

### Type Aliases
- **Data**: `T` - The data type guarded by the mutex.
- **Lvl**: `Lvl` - The level of the mutex.
- **RawMtx**: `R` - The raw mutex backend.

### Methods
- **id(&self) -> LockId**: Return this mutex’s `LockId`.
- **lock_ref(&'a self) -> MutexGuard<'a, R, T>**: Lock the mutex and return the guard.
```

--------------------------------

### Get Number of Issued Vouchers

Source: https://docs.rs/surelock/0.1.0/src/surelock/locksmith.rs.html

Returns the total number of key vouchers issued so far. This method uses relaxed ordering for atomic operations.

```rust
pub fn issued(&self) -> usize {
        self.issued.load(Ordering::Relaxed)
    }
```

--------------------------------

### Create a LockSet with a tuple of mutexes

Source: https://docs.rs/surelock/0.1.0/src/surelock/set.rs.html

Demonstrates the creation of a LockSet using a tuple of Mutexes. The sorting of locks by LockId happens once at construction time.

```rust
use surelock::{mutex::Mutex, set::LockSet};

let a: Mutex<u32> = Mutex::new(1);
let b: Mutex<u32> = Mutex::new(2);

// Sort happens once at construction time.
let set = LockSet::new((&a, &b));

```

--------------------------------

### Key Patterns in Surelock

Source: https://docs.rs/surelock/0.1.0/surelock/index.html

Demonstrates common patterns for interacting with Surelock mutexes, including entering scopes, locking single mutexes or sets, and using closures for one-shot locking.

```rust
// Enter a scope
handle.scope(|key| { ... });
```

```rust
// Lock (single mutex or LockSet, guards returned)
let (guard, key) = key.lock(&mutex);
let ((ga, gb), key) = key.lock(&set);
```

```rust
// Lock with closure (one-shot, sorts inline)
let (val, key) = key.lock_with(&mutex, |guard| *guard);
```

```rust
// Nested sub-scope
let (result, key) = key.subscope(|inner_key| { ... });
```

--------------------------------

### Redeem KeyVoucher in no_std environment

Source: https://docs.rs/surelock/0.1.0/src/surelock/key_voucher.rs.html

Redeems a KeyVoucher for a KeyHandle in a no_std environment. This is infallible and always returns a KeyHandle. Per-context uniqueness is a setup discipline.

```rust
    #[must_use]
    #[allow(clippy::expect_used)]
    #[cfg(not(feature = "std"))]
    pub fn redeem(self) -> KeyHandle {
        KeyHandle::try_claim().expect("KeyHandle::try_claim always succeeds on no_std")
    }

```

--------------------------------

### Get Mutable Reference to Data

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Provides direct mutable access to the protected data without needing to acquire a lock. This is safe because exclusive ownership implies no other thread can access the data.

```rust
pub const fn get_mut(&mut self) -> &mut T {
    self.data.get_mut()
}
```

--------------------------------

### Create and Issue KeyVouchers with Locksmith

Source: https://docs.rs/surelock/0.1.0/surelock/locksmith/index.html

Instantiate a Locksmith for a given number of cores and issue KeyVouchers. The number of issued vouchers is limited by the initial capacity.

```rust
use surelock::locksmith::Locksmith;

let smith = Locksmith::new(4).unwrap(); // 4-core system

let _v0 = smith.issue().unwrap();
let _v1 = smith.issue().unwrap();
let _v2 = smith.issue().unwrap();
let _v3 = smith.issue().unwrap();
assert!(smith.issue().is_none()); // limit reached
```

--------------------------------

### Implementation for Tuple of Mutexes

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.NewHigher.html

Demonstrates the implementation of NewHigher for a tuple of two mutexes, allowing the creation of a new mutex nested under both.

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Mutex<ParentT1, Lvl1, R>, &Mutex<ParentT2, Lvl2, R>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Mutex<ParentT1, Lvl1, R>, &Box<Mutex<ParentT2, Lvl2, R>>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Mutex<ParentT1, Lvl1, R>, &Rc<Mutex<ParentT2, Lvl2, R>>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Mutex<ParentT1, Lvl1, R>, &Arc<Mutex<ParentT2, Lvl2, R>>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Box<Mutex<ParentT1, Lvl1, R>>, &Mutex<ParentT2, Lvl2, R>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Box<Mutex<ParentT1, Lvl1, R>>, &Box<Mutex<ParentT2, Lvl2, R>>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Box<Mutex<ParentT1, Lvl1, R>>, &Rc<Mutex<ParentT2, Lvl2, R>>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Box<Mutex<ParentT1, Lvl1, R>>, &Arc<Mutex<ParentT2, Lvl2, R>>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

```APIDOC
### impl<ChildT, ParentT1, ParentT2, Lvl1: IsLevel + MaxLevel<Lvl2>, Lvl2: IsLevel, R: RawMutex> NewHigher<ChildT, R> for (&Rc<Mutex<ParentT1, Lvl1, R>>, &Mutex<ParentT2, Lvl2, R>)

#### type NextLvl = <<Lvl1 as MaxLevel<Lvl2>>::Max as NextLevel>::Next

#### fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>
```

--------------------------------

### NewHigher Implementation

Source: https://docs.rs/surelock/0.1.0/surelock/mutex/struct.Mutex.html

Allows the creation of a child mutex at the next security level.

```APIDOC
## impl<ParentT, ChildT, Lvl: IsLevel + NextLevel, R: RawMutex> NewHigher<ChildT, R> for Mutex<ParentT, Lvl, R>

### Type Aliases
- **NextLvl**: `<Lvl as NextLevel>::Next` - The child’s level (parent max + 1).

### Methods
- **new_higher(&self, data: ChildT) -> Mutex<ChildT, Lvl::Next, R>**: Create a child mutex at the next level.
```

--------------------------------

### Lock Single Mutex with Callback

Source: https://docs.rs/surelock/0.1.0/src/surelock/lib.rs.html

Shows how to acquire a single Mutex using a KeyHandle and execute a closure with the locked guard. The closure can return a value.

```rust
use surelock::{key_handle::KeyHandle, mutex::Mutex};

let counter: Mutex<u32> = Mutex::new(0);

let mut handle = KeyHandle::claim();
handle.scope(|key| {
    let (val, _key) = key.lock_with(&counter, |mut guard| {
        *guard += 1;
        *guard
    });
    assert_eq!(val, 1);
});

```

--------------------------------

### Surelock Mutex Construction

Source: https://docs.rs/surelock/0.1.0/index.html

Illustrates different ways to construct a Mutex, including specifying the level and parent for hierarchical locking, and using method syntax for convenience with various smart pointers.

```rust
Mutex::new(data)                     // Level<0>, default backend
```

```rust
Mutex::new_higher(data, &parent)      // parent.level + 1
```

```rust
Mutex::new_higher(data, (&a, &b))     // max(levels) + 1
```

```rust
parent.new_higher(data)               // parent.level + 1, inherits backend
```

```rust
(&a, &b).new_higher(data)             // max(levels) + 1
```

--------------------------------

### limit

Source: https://docs.rs/surelock/0.1.0/src/surelock/locksmith.rs.html

Returns the configured limit for issuing key vouchers. Returns `None` if there is no limit.

```APIDOC
## limit

### Description
Retrieves the maximum number of key vouchers that can be issued. If the locksmith is configured without a limit, this will return `None`.

### Method
`limit()`

### Returns
- `Option<usize>`: The issuance limit, or `None` if unlimited.
```

--------------------------------

### Create Unlimited Locksmith (Panic on Exist)

Source: https://docs.rs/surelock/0.1.0/src/surelock/locksmith.rs.html

Create an unlimited Locksmith, panicking if one already exists. This is useful when the existence of a Locksmith should be guaranteed.

```rust
pub fn create_unlimited() -> Self {
    Self::unlimited().expect("surelock: a Locksmith already exists")
}

```

--------------------------------

### LockSet::new

Source: https://docs.rs/surelock/0.1.0/src/surelock/set.rs.html

Creates a new LockSet, pre-sorting the locks by LockId. This method will panic if duplicate locks are detected.

```APIDOC
## LockSet::new

### Description
Creates a new `LockSet`, pre-sorting by [`LockId`].

Construction allocates a small index vector proportional to
the number of locks. For hot loops acquiring the same set
repeatedly, construct the `LockSet` once outside the loop
and reuse it.

An empty group (e.g., an empty slice) is valid. Locking an
empty set is a no-op that still advances the key's level to
the group's `MaxLvl`.

See [`try_new`](LockSet::try_new) for a non-panicking
alternative that returns `None` on duplicates.

### Method
`pub fn new<'a>(group: L) -> Self`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use surelock::{mutex::Mutex, set::LockSet};

let a: Mutex<u32> = Mutex::new(1);
let b: Mutex<u32> = Mutex::new(2);

// Sort happens once at construction time.
let set = LockSet::new((&a, &b));
```

### Response
#### Success Response (200)
`LockSet<L>`

#### Response Example
None provided.

### Panics
Panics if any two locks in the group share the same
[`LockId`] (i.e., the same `&Mutex` appears
more than once).
```

--------------------------------

### Create a LockSet

Source: https://docs.rs/surelock/0.1.0/surelock/set/struct.LockSet.html

Construct a new LockSet by providing a group of acquirable locks. The locks are pre-sorted by LockId during construction. For performance, create the LockSet once outside of hot loops.

```rust
use surelock::{mutex::Mutex, set::LockSet};

let a: Mutex<u32> = Mutex::new(1);
let b: Mutex<u32> = Mutex::new(2);

// Sort happens once at construction time.
let set = LockSet::new((&a, &b));
```

--------------------------------

### LockSet::try_new

Source: https://docs.rs/surelock/0.1.0/src/surelock/set.rs.html

Attempts to create a new LockSet, returning None if duplicate locks are found. This is a non-panicking alternative to LockSet::new.

```APIDOC
## LockSet::try_new

### Description
Try to create a new `LockSet`, returning `None` if any locks
are duplicated.

Same as [`new`](LockSet::new) but returns `None` instead of
panicking when two locks share the same
[`LockId`]. An empty group always returns
`Some`.

### Method
`pub fn try_new<'a>(group: L) -> Option<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use surelock::{mutex::Mutex, set::LockSet};

let a: Mutex<u32> = Mutex::new(1);
let b: Mutex<u32> = Mutex::new(2);

// Distinct locks -- succeeds.
assert!(LockSet::try_new((&a, &b)).is_some());

// Same lock twice -- returns None.
assert!(LockSet::try_new((&a, &a)).is_none());
```

### Response
#### Success Response (200)
`Option<LockSet<L>>`

#### Response Example
None provided.
```

--------------------------------

### Locksmith::create

Source: https://docs.rs/surelock/0.1.0/src/surelock/locksmith.rs.html

Creates a Locksmith with a specified limit, panicking if one already exists.

```APIDOC
## Locksmith::create

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

### Signature
```rust
#[must_use]
#[allow(clippy::expect_used)]
pub fn create(limit: usize) -> Self
```

### Parameters
#### Path Parameters
- **limit** (usize) - Required - The maximum number of vouchers the Locksmith can issue.

### Panics
Panics if a `Locksmith` already exists.
```

--------------------------------

### NewHigher for (Box<Mutex>, Mutex)

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Implements `NewHigher` for a tuple with a `Box<Mutex>` reference and a bare mutex reference. This is the reverse of the (Mutex, Box<Mutex>) case.

```rust
impl_new_higher_tuple!(alloc::boxed::Box<Mutex<ParentT1, Lvl1, R>>, Mutex<ParentT2, Lvl2, R>);
```

--------------------------------

### Creating Mutexes with Higher Levels

Source: https://docs.rs/surelock/0.1.0/surelock/mutex/struct.Mutex.html

Shows how to create new mutexes that are ordered after existing ones, using the default StdMutex backend. The new mutex's level is determined by the maximum level of its parents plus one. Accepts single mutex references or tuples of references.

```rust
use surelock::mutex::Mutex;

let config: Mutex<u32> = Mutex::new(10);
let account = Mutex::new_higher(20u32, &config);  // Level<1>
let txn = Mutex::new_higher(30u32, &account);      // Level<2>

// Siblings: same parent, same level
let acct_a = Mutex::new_higher(1u32, &config);  // Level<1>
let acct_b = Mutex::new_higher(2u32, &config);  // Level<1>

// Multi-parent: after both config and account
let reconciler = Mutex::new_higher(0u32, (&config, &account));
// Level = max(Level<0>, Level<1>) + 1 = Level<2>
```

--------------------------------

### Create a Child Mutex with NewHigher

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.NewHigher.html

Demonstrates how to create a child mutex with an increased level using the `new_higher` method. The child's level increments sequentially.

```rust
use surelock::{level::NewHigher, mutex::Mutex};

let config: Mutex<u32> = Mutex::new(10);
let account = config.new_higher(20u32);     // Level<1>
let txn = account.new_higher(30u32);        // Level<2>
```

--------------------------------

### NewHigher for (Rc<Mutex>, Box<Mutex>)

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Implements `NewHigher` for a tuple containing an `Rc<Mutex>` reference and a `Box<Mutex>` reference. This allows combining different smart pointer wrappers for nested mutexes.

```rust
impl_new_higher_tuple!(
    alloc::rc::Rc<Mutex<ParentT1, Lvl1, R>>,
    alloc::boxed::Box<Mutex<ParentT2, Lvl2, R>>
);
```

--------------------------------

### Create a New StdMutex Instance

Source: https://docs.rs/surelock/0.1.0/surelock/raw_mutex/std_mutex/struct.StdMutex.html

Creates a new, unlocked StdMutex instance. This can be done at compile time.

```rust
pub const fn const_new() -> Self
```

--------------------------------

### Locksmith::new

Source: https://docs.rs/surelock/0.1.0/surelock/locksmith/struct.Locksmith.html

Attempts to create a new Locksmith with a specified voucher limit. Returns None if a Locksmith already exists.

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

### Description
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.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Response
#### Success Response (Some(Locksmith))
- Returns `Some(Locksmith)` if successful.

#### Error Response (None)
- Returns `None` if a Locksmith already exists.

### Request Example
```rust
let locksmith = Locksmith::new(10);
```

### Response Example
```rust
// If successful
Some(Locksmith { ... })

// If a Locksmith already exists
None
```
```

--------------------------------

### NextLevel Implementations

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.NextLevel.html

Shows the implementations of the NextLevel trait for various Level types, indicating the successor level for each.

```APIDOC
### impl NextLevel for Level<0>
#### type Next = Level<1>

### impl NextLevel for Level<1>
#### type Next = Level<2>

### impl NextLevel for Level<2>
#### type Next = Level<3>

### impl NextLevel for Level<3>
#### type Next = Level<4>

### impl NextLevel for Level<4>
#### type Next = Level<5>

### impl NextLevel for Level<5>
#### type Next = Level<6>

### impl NextLevel for Level<6>
#### type Next = Level<7>

### impl NextLevel for Level<7>
#### type Next = Level<8>

### impl NextLevel for Level<8>
#### type Next = Level<9>

### impl NextLevel for Level<9>
#### type Next = Level<10>

### impl NextLevel for Level<10>
#### type Next = Level<11>

### impl NextLevel for Level<11>
#### type Next = Level<12>

### impl NextLevel for Level<12>
#### type Next = Level<13>

### impl NextLevel for Level<13>
#### type Next = Level<14>

### impl NextLevel for Level<14>
#### type Next = Level<15>
```

--------------------------------

### NewHigher for (&Rc<Mutex<ParentT1, Lvl1, R>>, &Box<Mutex<ParentT2, Lvl2, R>>)

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.NewHigher.html

Implements NewHigher for a tuple of references to an Rc-wrapped Mutex and a Box-wrapped Mutex. This allows creating a new Mutex with a child type and a next level derived from the parent levels.

```APIDOC
## fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>

### Description
Creates a new Mutex with the provided data, where the level is determined by the `NextLvl` associated type, derived from the parent Mutex levels.

### Method
new_higher

### Parameters
- `data`: ChildT - The data to be contained within the new Mutex.
```

--------------------------------

### MinLevel Implementation for Level<0> and Level<N>

Source: https://docs.rs/surelock/0.1.0/surelock/level/type.Base.html

Demonstrates the MinLevel trait implementation for Level<0> with various other Level<N> types, showing the lower of the two levels.

```rust
impl MinLevel<Level<0>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<1>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<10>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<11>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<12>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<13>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<14>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<15>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<2>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<3>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<4>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<5>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<6>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<7>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<8>> for Level<0>
{
    type Min = Level<0>;
}
```

```rust
impl MinLevel<Level<9>> for Level<0>
{
    type Min = Level<0>;
}
```

--------------------------------

### NewHigher for (Box<Mutex>, Rc<Mutex>)

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Implements `NewHigher` for a tuple containing a `Box<Mutex>` reference and an `Rc<Mutex>` reference. This allows nesting mutexes wrapped in `Box` and `Rc`.

```rust
impl_new_higher_tuple!(
    alloc::boxed::Box<Mutex<ParentT1, Lvl1, R>>,
    alloc::rc::Rc<Mutex<ParentT2, Lvl2, R>>
);
```

--------------------------------

### NewHigher for (&Rc<Mutex<ParentT1, Lvl1, R>>, &Rc<Mutex<ParentT2, Lvl2, R>>)

Source: https://docs.rs/surelock/0.1.0/surelock/level/trait.NewHigher.html

Implements NewHigher for a tuple of references to two Rc-wrapped Mutexes. This enables the creation of a new Mutex with a child type and a next level derived from the parent levels.

```APIDOC
## fn new_higher(&self, data: ChildT) -> Mutex<ChildT, Self::NextLvl, R>

### Description
Creates a new Mutex with the provided data. The level of the new Mutex is determined by the `NextLvl` associated type, which is computed from the levels of the two parent Mutexes.

### Method
new_higher

### Parameters
- `data`: ChildT - The data to be encapsulated in the new Mutex.
```

--------------------------------

### Debug Implementation for KeyHandle

Source: https://docs.rs/surelock/0.1.0/src/surelock/key_handle.rs.html

Provides a basic `Debug` implementation for `KeyHandle`, indicating it's a `KeyHandle` without exposing internal details.

```rust
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("KeyHandle").finish_non_exhaustive()
    }
```

--------------------------------

### Taking KeyHandleSlot from Thread-local Storage

Source: https://docs.rs/surelock/0.1.0/src/surelock/key_handle.rs.html

Provides a function to take the KeyHandleSlot from thread-local storage. Returns `Some` if the slot was available (first claim), and `None` if it was already taken.

```rust
pub(crate) fn take() -> Option<KeyHandleSlot> {
    SLOT.with(Cell::take)
}
```

--------------------------------

### NewHigher for (Box<Mutex>, Box<Mutex>)

Source: https://docs.rs/surelock/0.1.0/src/surelock/mutex.rs.html

Implements `NewHigher` for a tuple of two `Box<Mutex>` references. This is useful for heap-allocated nested mutexes.

```rust
impl_new_higher_tuple!(
    alloc::boxed::Box<Mutex<ParentT1, Lvl1, R>>,
    alloc::boxed::Box<Mutex<ParentT2, Lvl2, R>>
);
```

--------------------------------

### Cross-Level Incremental Acquisition

Source: https://docs.rs/surelock/0.1.0/index.html

Shows how to create mutexes at different levels using `Mutex::new_higher` and acquire them in the correct order. The `MutexKey` type parameter enforces compile-time ordering.

```rust
use surelock::{key_handle::KeyHandle, level::Level, mutex::Mutex};

let config: Mutex<u32> = Mutex::new(42);
let account: Mutex<u32, Level<1>> = Mutex::new_higher(100u32, &config);

let mut handle = KeyHandle::claim();
handle.scope(|key| {
    // Read config first (Level<0>)
    let (cfg_val, key) = key.lock_with(&config, |g| *g);

    // Then lock account (Level<1>)
    let ((), _key) = key.lock_with(&account, |mut acct| {
        *acct += cfg_val;
    });
});
```
Tokens:
Raw