Struct LockManager 

pub struct LockManager { /* private fields */ }

Lock manager for stripe locking during preflight phase

Provides per-key locking with configurable number of stripes. Non-conflicting keys map to different stripes and can be locked concurrently.

Deadlock Prevention

This implementation prevents deadlocks through two mechanisms:

1. Automatic Sorting: When acquiring multiple locks via acquire_keys(), stripes are always acquired in ascending index order. This prevents the classic A-B/B-A deadlock scenario.

2. Timeout-Based Acquisition: Uses try_lock_for() with a configurable timeout instead of blocking indefinitely. If a lock cannot be acquired within the timeout, returns LockTimeout error.

Example

let lm = LockManager::new(256, Duration::from_secs(5));

// Acquire locks on multiple keys - automatically sorted to prevent deadlock
let _guard = lm.acquire_keys(&[b"key_b", b"key_a"])?;
// Locks acquired in stripe order, not key order

Implementations

impl LockManager

pub fn new(num_stripes: usize, default_timeout: Duration) -> Self

Create a new lock manager with the specified number of stripes

Arguments

• num_stripes - Number of lock stripes (common values: 256, 512, 1024). More stripes = less contention but more memory.
• default_timeout - Default timeout for lock acquisition.

Panics

Panics if num_stripes is 0.

pub fn with_stripes(num_stripes: usize) -> Self

Create a lock manager with default timeout

pub fn acquire_keys<K: AsRef<[u8]>>( &self, keys: &[K], ) -> Result<MultiLockGuard<'_>>

Acquire exclusive locks on all keys in a deadlock-free manner

This method:

1. Computes stripe indices for all keys
2. Deduplicates stripes (multiple keys may map to same stripe)
3. Sorts stripe indices for consistent global ordering
4. Acquires locks in sorted order with timeout

Arguments

• keys - Keys to acquire locks for

Returns

A MultiLockGuard that holds all acquired locks. Locks are released when the guard is dropped.

Errors

Returns LockTimeout if any lock cannot be acquired within the timeout.

Deadlock Safety

Because locks are always acquired in sorted stripe order, two threads acquiring locks on keys [A, B] and [B, A] will both attempt to acquire locks in the same order, preventing deadlock.

pub fn acquire_keys_with_timeout<K: AsRef<[u8]>>( &self, keys: &[K], timeout: Duration, ) -> Result<MultiLockGuard<'_>>

Acquire exclusive locks with a custom timeout

pub fn lock(&self, key: &[u8]) -> Result<MutexGuard<'_, ()>>

Acquire a single lock (convenience method)

Prefer acquire_keys() for multiple keys to ensure deadlock safety.

pub fn num_stripes(&self) -> usize

Get the number of stripes

pub fn default_timeout(&self) -> Duration

Get the default timeout