Crate thread_checked_lock 

Thread-checked Lock

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

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Structs

AccessError

Returned when a lock’s data was accessed, but the lock was poisoned.

ThreadCheckedMutex

A variant of std::sync::Mutex which gracefully returns an error when a thread attempts to acquire a ThreadCheckedMutex that it already holds.

ThreadCheckedMutexGuard

A RAII scoped lock for a ThreadCheckedMutex, analogous to MutexGuard for Mutex.

Enums

LockError

An error that may be returned by ThreadCheckedMutex::lock.

TryLockError

An error that may be returned by ThreadCheckedMutex::try_lock.

Traits

HandlePoisonResult

Extension trait for Result which adds the ability to more conveniently handle the poison errors returned by this crate’s locks.

Type Aliases

AccessResult

The result type returned by ThreadCheckedMutex::into_inner or ThreadCheckedMutex::get_mut.

LockResult

The result type returned by ThreadCheckedMutex::lock.

PoisonlessAccessResult

A variation of AccessResult<T> which cannot possibly be a poison error.

PoisonlessLockResult

A variation of LockResult<T> which cannot possibly be a poison error.

PoisonlessTryLockResult

A variation of TryLockResult<T> which cannot possibly be a poison error.

TryLockResult

The result type returned by ThreadCheckedMutex::try_lock.