Struct MutexKey 

pub struct MutexKey<'scope, Lvl: IsLevel> { /* private fields */ }

Scope token for ordered lock acquisition.

Tracks the current lock level as a type parameter Lvl. Consumed by lock and re-emitted at the new level.

• !Send + !Sync — cannot cross thread boundaries.
• Branded lifetime 'scope — cannot escape the lock_scope closure.
• !Clone + !Copy — prevents using the same key twice.

Implementations

impl<'scope, Lvl: IsLevel> MutexKey<'scope, Lvl>

pub fn lock<'a, L: Lockable<'a>>( self, target: &'a L, ) -> (L::Guard, MutexKey<'scope, L::MaxLvl>)

where L::MinLvl: LockAfter<Lvl>,

Lock one or more mutexes, returning the guard(s) directly.

Accepts a single &Mutex or a &LockSet. Consumes the key and returns the guard(s) plus a new key at the target’s level.

For a single mutex this is zero-allocation; for a LockSet the sort was already done at construction time.

Examples

use surelock::{key::lock_scope, level::Level, mutex::Mutex, set::LockSet};

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

lock_scope(|key| {
    // Single mutex
    let (mut guard, key) = key.lock(&a);
    *guard += 10;
    drop(guard);

    // Pre-sorted set
    let set = LockSet::new(&b);
    let (mut guard, _key) = key.lock(&set);
    *guard += 20;
});

pub fn lock_with<'a, L, F, Ret>( self, lockable: &'a L, f: F, ) -> (Ret, MutexKey<'scope, <L as Acquirable<'a>>::MaxLvl>)

where L: Acquirable<'a>, <L as Acquirable<'a>>::MinLvl: LockAfter<Lvl>, F: FnOnce(<L as Acquirable<'a>>::Guard) -> Ret,

Lock one or more mutexes via a closure.

Sorts by LockId and acquires in one call. The guards live inside the closure – no LockSet needed. Convenient for one-shot read-and-release patterns.

For hot paths where the same locks are acquired repeatedly, pre-build a LockSet and use lock instead (sort once, lock many).

Consumes the key. Returns the closure’s result plus a new key at the lock group’s level.

Panics

Panics if the group contains duplicate locks (same LockId appearing more than once).

Examples

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

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

let mut handle = KeyHandle::claim();
handle.scope(|key| {
    let (sum, _key) = key.lock_with(&(&a, &b), |(ga, gb)| *ga + *gb);
    assert_eq!(sum, 3);
});

pub fn subscope<F, Ret>(self, f: F) -> (Ret, MutexKey<'scope, Lvl>)

where F: for<'inner> FnOnce(MutexKey<'inner, Lvl>) -> Ret,

Create a nested scope that inherits the current level.

The inner key starts at the same level as the outer key, so any subsequent lock calls must still be at higher levels. The outer key is consumed for the duration of the subscope.

After the subscope returns, a key at the same level is returned alongside the closure’s return value. The inner key gets its own branded lifetime, so its guards cannot escape the inner closure.

Trait Implementations

impl<Lvl: IsLevel> Debug for MutexKey<'_, Lvl>

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

Formats the value using the given formatter.