Struct ThreadCheckedMutex

pub struct ThreadCheckedMutex<T: ?Sized> { /* private fields */ }

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

In such a situation, Mutex::lock is guaranteed to either lock or panic, while Mutex::try_lock checks if any thread holds the lock (and cannot distinguish whether the current thread holds the lock). As such, attempting to lock the same Mutex twice on a thread is potentially a fatal error; ThreadCheckedMutex allows for recovery.

Implementations

impl<T> ThreadCheckedMutex<T>

pub fn new(t: T) -> Self

Creates a new mutex in an unlocked state.

impl<T: ?Sized> ThreadCheckedMutex<T>

pub fn lock(&self) -> LockResult<ThreadCheckedMutexGuard<'_, T>>

Attempts to acquire this mutex, blocking the current thread while the mutex is locked in other threads.

If the mutex is acquired (either completely successfully or with a poison error), a ThreadCheckedMutexGuard is returned. Only one thread at a time can hold the lock; at most one ThreadCheckedMutexGuard can exist at a time (across any thread); and the mutex is unlocked when the returned guard is dropped.

Errors

If the mutex was already held by the current thread when this call was made, then a LockedByCurrentThread error is returned.

If another user of this mutex panicked while holding the mutex, then this call will still acquire the mutex but wrap the returned guard in a poison error. See the HandlePoisonResult trait for methods to ignore poison errors and treat them as successful, or to panic if a poison error was returned.

pub fn try_lock(&self) -> TryLockResult<ThreadCheckedMutexGuard<'_, T>>

Attempts to acquire this mutex without blocking.

If the mutex is acquired (either completely successfully or with a poison error), a ThreadCheckedMutexGuard is returned. Only one thread at a time can hold the lock; at most one ThreadCheckedMutexGuard can exist at a time (across any thread); and the mutex is unlocked when the returned guard is dropped.

Errors

If the mutex was already held by the current thread when this call was made, then a LockedByCurrentThread error is returned. If the mutex was held by a different thread, then a WouldBlock error is returned.

If another user of this mutex panicked while holding the mutex, then this call will still acquire the mutex but wrap the returned guard in a poison error. See the HandlePoisonResult trait for methods to ignore poison errors and treat them as successful, or to panic if a poison error was returned.

pub fn locked_by_current_thread(&self) -> bool

Determines whether this mutex is currently held by the current thread.

pub fn is_poisoned(&self) -> bool

Determines whether this mutex is currently poisoned.

If another thread is active, the mutex could become poisoned or have its poison cleared at any time; as such, the return value of this function should generally not be depended on for program correctness.

Read more about poison.

pub fn clear_poison(&self)

Clear any poison from this mutex.

When a ThreadCheckedMutexGuard is dropped in a thread which is panicking, its associated mutex becomes poisoned, and remains poisoned until this function is called (by any thread).

Read more about poison.

pub fn into_inner(self) -> AccessResult<T>

where T: Sized,

Consumes this mutex and returns the underlying data.

Errors

If another user of this mutex panicked while holding the mutex, then the inner data is still returned, but wrapped in a poison error.

Read more about poison.

pub fn get_mut(&mut self) -> AccessResult<&mut T>

Returns a mutable reference to the underlying data, without locking.

Errors

If another user of this mutex panicked while holding the mutex, then a mutable reference is still returned, but wrapped in a poison error.

Read more about poison.

Trait Implementations

impl<T: Debug + ?Sized> Debug for ThreadCheckedMutex<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for ThreadCheckedMutex<T>

fn default() -> Self

Returns the “default value” for a type.