Struct Mutex 

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

A mutual exclusion primitive useful for protecting shared data.

This mutex will block threads waiting for the lock to become available. The mutex can also be statically initialized or created via a new constructor. Each mutex has a type parameter which represents the data that it is protecting. The data can only be accessed through the RAII guards returned from lock and try_lock, which guarantees that the data is only ever accessed when the mutex is locked.

Implementations

impl<R: RawMutex, T> Mutex<R, T>

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

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

pub fn into_inner(self) -> T

Consumes this mutex, returning the underlying data.

impl<R, T> Mutex<R, T>

pub const fn from_raw(raw_mutex: R, val: T) -> Mutex<R, T>

Creates a new mutex based on a pre-existing raw mutex.

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

Consumes this mutex, returning the underlying data and raw mutex.

impl<R: RawMutex, T: ?Sized> Mutex<R, T>

pub unsafe fn make_guard_unchecked( &self, guard: R::Guard, ) -> MutexGuard<'_, R, T>

Creates a new MutexGuard without checking if the mutex is locked.

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.

guard must be the state for this acquisition of this lock.

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

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

This function will block the local thread until it is available to acquire the mutex. 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.

The exact behavior when the current thread tries to acquire a mutex it already holds is left unspecified. The second call will not return; it may panic or deadlock, for example.

Panics

This function may panic if the lock is already held by the current thread.

pub fn try_lock(&self) -> Option<MutexGuard<'_, R, 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.

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

Returns a mutable reference to the underlying data.

Since this call borrows the Mutex 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 MutexGuard.

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 unsafe fn force_unlock(&self, guard: R::Guard)

Forcibly unlocks the mutex.

This is useful when the raw acquisition state is managed separately, for example when dealing with FFI.

Safety

The current context must hold the lock using the supplied acquisition state, with no live guard responsible for unlocking it. 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.

guard must be the state for this acquisition of this lock.

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.

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 reads and writes through it are properly synchronized and that the pointer is not used after the mutex is dropped.

impl<R: RawMutexFair, T: ?Sized> Mutex<R, T>

pub unsafe fn force_unlock_fair(&self, guard: R::Guard)

Forcibly unlocks the mutex using a fair unlock protocol.

This is useful when the raw acquisition state is managed separately, for example when dealing with FFI.

Safety

The current context must hold the lock using the supplied acquisition state, with no live guard responsible for unlocking it. 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.

guard must be the state for this acquisition of this lock.

impl<R: RawMutexTimed, T: ?Sized> Mutex<R, T>

pub fn try_lock_for(&self, timeout: R::Duration) -> Option<MutexGuard<'_, R, 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.

pub fn try_lock_until( &self, timeout: R::Instant, ) -> Option<MutexGuard<'_, R, 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.

Trait Implementations

impl<R: RawMutex, T: ?Sized + Debug> Debug for Mutex<R, T>

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

Formats the value using the given formatter.

impl<R: RawMutex, T: Default> Default for Mutex<R, T>

fn default() -> Mutex<R, T>

Returns the “default value” for a type.

impl<R: RawMutex, T> From<T> for Mutex<R, T>

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

Converts to this type from the input type.

impl<R: RawMutex + Sync, T: ?Sized + Send> Sync for Mutex<R, T>