Struct BlockingMutex

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

Blocking mutex (not async)

Provides a blocking mutual exclusion primitive backed by an implementation of ScopedRawMutex.

Which implementation you select depends on the context in which you’re using the mutex, and you can choose which kind of interior mutability fits your use case.

Use CriticalSectionRawMutex when data can be shared between threads and interrupts.

Use LocalRawMutex when data is only shared between tasks running on the same executor.

Use ThreadModeRawMutex when data is shared between tasks running on the same executor but you want a global singleton.

Use LockApiRawMutex if you wish to use a type implementing lock_api::RawMutex as the mutex implementation.

In all cases, the blocking mutex is intended to be short lived and not held across await points.

Unwinding

When the “std” feature is active, calls to BlockingMutex::with_lock() and BlockingMutex::try_with_lock() will attempt to catch_unwind(), allowing the mutex to be unlocked. After the mutex has been unlocked, the unwind will be resumed with resume_unwind(). This comes with all the caveats that normally come with catch_unwind().

Implementations

impl<R: ConstInit, T> BlockingMutex<R, T>

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

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

impl<R: ScopedRawMutex, T: ?Sized> BlockingMutex<R, T>

pub fn with_lock<U>(&self, f: impl FnOnce(&mut T) -> U) -> U

Locks the raw mutex and grants temporary access to the inner data

Behavior when the lock is already locked is dependent on the behavior of the Raw mutex. See ScopedRawMutex::with_lock()’s documentation for more details

pub fn try_with_lock<U>(&self, f: impl FnOnce(&mut T) -> U) -> Option<U>

Locks the raw mutex and grants temporary access to the inner data

Returns Some(U) if the lock was obtained. Returns None if the lock was already locked

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

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

Locks the raw mutex, returning a MutexGuard that grants temporary access to the inner data.

Behavior when the lock is already locked is dependent on the behavior of the raw mutex. See RawMutex::lock()’s documentation for more details

This method is only available when the R type parameter implements the RawMutex trait. If R can only implement the ScopedRawMutex subset, consider BlockingMutex::with_lock() instead.

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

Attempts to lock the raw mutex, returning a MutexGuard that grants temporary access to the inner data if the lock can be acquired.

This method will never block, and instead returns None immediately if the mutex is already locked. To block until the mutex can be acquired, use BlockingMutex::lock() instead.

This method is only available when the R type parameter implements the RawMutex trait. If R can only implement the ScopedRawMutex subset, consider BlockingMutex::try_with_lock() instead.

Returns

• Some(MutexGuard<R, T>) if the mutex was not already locked.
• None if the mutex is already locked.

impl<R, T> BlockingMutex<R, T>

pub const fn const_new(raw_mutex: R, val: T) -> BlockingMutex<R, T>

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

This allows creating a mutex in a constant context on stable Rust.

pub fn into_inner(self) -> T

Consumes this mutex, returning the underlying data.

pub 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 locks exist.

pub unsafe fn get_unchecked(&self) -> *mut T

Returns a pointer to the inner storage

Safety

Must NOT be called when the lock is taken

Trait Implementations

impl<R, T> Debug for BlockingMutex<R, T>

where R: ScopedRawMutex + Debug, T: ?Sized + Debug,

Available on crate feature fmt only.

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

Formats the value using the given formatter.

impl<R: ScopedRawMutex + Send, T: ?Sized + Send> Send for BlockingMutex<R, T>

impl<R: ScopedRawMutex + Sync, T: ?Sized + Send> Sync for BlockingMutex<R, T>