Trait mutex_traits::RawMutex

pub unsafe trait RawMutex {
    type GuardMarker;

    // Required methods
    fn lock(&self);
    fn try_lock(&self) -> bool;
    unsafe fn unlock(&self);
    fn is_locked(&self) -> bool;
}

Raw mutex trait.

This trait represents an implementation of a generic mutual-exclusion lock which may be locked and unlocked freely at any time.

This mutex is “raw”, which means it does not actually contain the protected data, it just implements the mutex mechanism. For most uses you should use BlockingMutex from the mutex crate instead, which is generic over a RawMutex and contains the protected data.

RawMutex and ScopedRawMutex

The RawMutex trait is a superset of the ScopedRawMutex trait. The interface defined in ScopedRawMutex is more restrictive, and only permits the mutex to be locked for the duration of a single FnOnce call and unlocked immediately when that closure exits. RawMutex, on the other hand, permits a much wider range of potential usage patterns: it may be used to implement a RAII-style lock guard like std::sync::Mutex, a “C-style” mutex where explicit lock and unlock calls have to be paired manually, or a scoped closure-based API like ScopedRawMutex. Therefore, there is a blanket implementation of ScopedRawMutex for all types that implement RawMutex.

Some mutex implementations may not be able to implement the full RawMutex trait, and may only be able to implement the closure-based ScopedRawMutex subset. For example, implementations for the [critical-section] crate (in mutex::raw_impls::cs) can only implement the ScopedRawMutex trait. However, in general, mutex implementations that can implement the more general RawMutex trait should prefer to do so, as they will be able to be used in code that requires either interface.

Safety

Implementations of this trait must ensure that the mutex is actually exclusive: a lock can’t be acquired while the mutex is already locked.

Required Associated Types

type GuardMarker

Marker type which determines whether a lock guard should be Send.

Required Methods

fn lock(&self)

Acquires this mutex, blocking the current thread/CPU core until it is able to do so.

fn try_lock(&self) -> bool

Attempts to acquire this mutex without blocking. Returns true if the lock was successfully acquired and false otherwise.

unsafe fn unlock(&self)

Unlocks this mutex.

Safety

This method may only be called if the mutex is held in the current context, i.e. it must be paired with a successful call to lock or try_lock.

fn is_locked(&self) -> bool

Returns true if the mutex is currently locked.

Implementors

impl RawMutex for Spinlock