thread-checked-lock 0.1.1

Gracefully error when a thread attempts to acquire the same lock twice
Documentation
  • Coverage
  • 100%
    22 out of 22 items documented1 out of 1 items with examples
  • Size
  • Source code size: 58.24 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.03 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 10s Average build duration of successful builds.
  • all releases: 11s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • robofinch/generic-container
    1 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • robofinch

Latest version Documentation Apache 2.0 or MIT license.

This crate slightly strengthens the information returned by a mutex's try_lock method, and ensures that calling lock in a thread which has already acquired the mutex is not a fatal error.

The provided ThreadCheckedMutex struct gracefully errors (instead of panicking or deadlocking) when a thread attempts to acquire a ThreadCheckedMutex that it already holds.

Motivation

The standard Mutex does provide Mutex::try_lock, which doesn't panic or deadlock, but it cannot distinguish between the current thread holding the lock and a different thread holding the lock; it only indicates that attempting to acquire the lock would not immediately succeed.

Comparing Mutex::try_lock with RefCell::try_borrow, the return value of try_borrow is less ambiguous, because there's only one way for it to fail: the current thread must have mutably borrowed the RefCell. When implementing the generic-container crate's traits for various types, this felt like a gap; the standard mutex type can easily be implemented as a "fragile" container (which places greater responsibilities on the caller), but not even a spinlock approach with try_lock could make it non-fragile. ThreadCheckedMutex fills out a niche in the container traits that did not seem to be met by an existing crate.

Example

use thread_checked_lock::{ThreadCheckedMutex, LockError};

let mutex = ThreadCheckedMutex::new(0_u8);

let guard = mutex.lock().expect("Locking a new mutex succeeds");

// An additional attempt to lock should fail.
assert!(matches!(
    mutex.lock(),
    Err(LockError::LockedByCurrentThread),
));

drop(guard);

// Now it should succeed. The mutex is unlocked, and not poisoned.
let _guard = mutex.lock().unwrap();

Features

  • serde: derives Serialize and Deserialize for ThreadCheckedMutex.

Minimum supported Rust Version (MSRV)

Rust 1.85, the earliest version of the 2024 edition, is supported.

License

Licensed under either of

at your option.