Struct ReentrantMutex 

pub struct ReentrantMutex<R: RawMutex, G, T: ?Sized> { /* private fields */ }

A reentrant mutual exclusion lock.

This lock blocks other threads waiting for it to become available. A thread which already holds the lock can acquire it additional times without blocking.

Unlike Mutex, ReentrantMutexGuard does not provide mutable references to the locked data, because multiple guards can coexist on the same thread. Use interior mutability, such as Cell or RefCell, to mutate the guarded data.

Implementations

impl<R: RawMutex, G: GetThreadId, T> ReentrantMutex<R, G, T>

pub const fn new(val: T) -> ReentrantMutex<R, G, T>

Creates a new reentrant mutex in an unlocked state ready for use.

pub fn into_inner(self) -> T

Consumes this mutex, returning the underlying data.

impl<R: RawMutex, G, T> ReentrantMutex<R, G, T>

pub const fn from_raw( raw_mutex: R, get_thread_id: G, val: T, ) -> ReentrantMutex<R, G, T>

Creates a new reentrant mutex based on a pre-existing raw mutex and a helper to get the thread ID.

pub fn into_inner_with_raw(self) -> (R, G, T)

Consumes this mutex, returning the underlying data, raw mutex and thread ID helper.

impl<R: RawMutex, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T>

pub unsafe fn make_guard_unchecked(&self) -> ReentrantMutexGuard<'_, R, G, T>

Creates a new ReentrantMutexGuard without checking if the lock is held.

Safety

This method must only be called if the thread logically holds the lock.

Calling this function when a guard has already been produced is undefined behavior unless the guard was forgotten with mem::forget.

The caller must ensure that existing references to the protected data remain valid when the returned guard is used or dropped. In particular, the returned guard must not permit accesses that conflict with existing references.

pub fn lock(&self) -> ReentrantMutexGuard<'_, R, G, T>

Acquires a reentrant mutex, blocking the current thread until it is able to do so.

If the mutex is held by another thread then this function will block the local thread until it is available to acquire the mutex. If the mutex is already held by the current thread then this function will increment the lock reference count and return immediately. Upon returning, the thread is the only thread with the mutex held. An RAII guard is returned to allow scoped unlock of the lock. When the guard goes out of scope, the mutex will be unlocked.

Panics

Panics if the recursive lock count overflows.

pub fn try_lock(&self) -> Option<ReentrantMutexGuard<'_, R, G, T>>

Attempts to acquire this lock.

If the lock could not be acquired at this time, then None is returned. Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.

This function does not block.

Panics

Panics if the recursive lock count overflows.

pub const fn get_mut(&mut self) -> &mut T

Returns a mutable reference to the underlying data.

Since this call borrows the ReentrantMutex mutably, no actual locking needs to take place – the mutable borrow statically guarantees no new locks can be acquired while the reference exists. This method does not clear a lock previously abandoned by forgetting a ReentrantMutexGuard.

pub fn is_locked(&self) -> bool

Checks whether the mutex is currently locked.

The result is a momentary snapshot and may be stale by the time it is returned.

pub fn is_owned_by_current_thread(&self) -> bool

Checks whether the mutex is currently held by the current thread.

pub unsafe fn force_unlock(&self)

Forcibly unlocks the mutex.

This is useful when combined with mem::forget to hold a lock without the need to maintain a ReentrantMutexGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a ReentrantMutexGuard but that guard has been discarded using mem::forget. Behavior is undefined if a mutex is unlocked when not locked.

The caller must ensure that releasing the lock does not invalidate any outstanding references to the protected data. Any subsequent access through previously obtained pointers must be properly synchronized.

pub unsafe fn raw(&self) -> &R

Returns the underlying raw mutex object.

Note that you will most likely need to import the RawMutex trait from lock_api to be able to call functions on the raw mutex.

Safety

The caller must ensure that operations on the raw lock preserve the validity of all live guards and references to the protected data. A guard must not be used or dropped while its lock is released, and any access through previously obtained pointers must be properly synchronized. Raw operations must also preserve the reentrant mutex’s owner and recursion count bookkeeping.

pub const fn data_ptr(&self) -> *mut T

Returns a raw pointer to the underlying data.

The returned pointer is always non-null and properly aligned, but the caller must ensure that accesses through it are valid and properly synchronized and that the pointer is not used after the mutex is dropped. In particular, writing requires exclusive access to the data; merely holding the reentrant mutex does not provide that because multiple guards can coexist on the same thread.

impl<R: RawMutexFair, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T>

pub unsafe fn force_unlock_fair(&self)

Forcibly unlocks the mutex using a fair unlock protocol.

This is useful when combined with mem::forget to hold a lock without the need to maintain a ReentrantMutexGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a ReentrantMutexGuard but that guard has been discarded using mem::forget. Behavior is undefined if a mutex is unlocked when not locked.

The caller must ensure that releasing the lock does not invalidate any outstanding references to the protected data. Any subsequent access through previously obtained pointers must be properly synchronized.

impl<R: RawMutexTimed, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T>

pub fn try_lock_for( &self, timeout: R::Duration, ) -> Option<ReentrantMutexGuard<'_, R, G, T>>

Attempts to acquire this lock until a timeout is reached.

If the lock could not be acquired before the timeout expired, then None is returned. Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.

A successful operation may return early. An unsuccessful operation will not return before the timeout, but may return later due to scheduling or platform-specific behavior.

Panics

Panics if the recursive lock count overflows.

pub fn try_lock_until( &self, timeout: R::Instant, ) -> Option<ReentrantMutexGuard<'_, R, G, T>>

Attempts to acquire this lock until a timeout is reached.

If the lock could not be acquired before the timeout expired, then None is returned. Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.

A successful operation may return early. An unsuccessful operation will not return before the timeout, but may return later due to scheduling or platform-specific behavior.

Panics

Panics if the recursive lock count overflows.

Trait Implementations

impl<R: RawMutex, G: GetThreadId, T: ?Sized + Debug> Debug for ReentrantMutex<R, G, T>

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

Formats the value using the given formatter.

impl<R: RawMutex, G: GetThreadId, T: Default> Default for ReentrantMutex<R, G, T>

fn default() -> ReentrantMutex<R, G, T>

Returns the “default value” for a type.

impl<R: RawMutex, G: GetThreadId, T> From<T> for ReentrantMutex<R, G, T>

fn from(t: T) -> ReentrantMutex<R, G, T>

Converts to this type from the input type.

impl<R: RawMutex + Sync, G: GetThreadId + Sync, T: ?Sized + Send> Sync for ReentrantMutex<R, G, T>