Struct lock_api::MappedMutexGuard

#[must_use]
pub struct MappedMutexGuard<'a, R: RawMutex + 'a, T: ?Sized + 'a> { /* fields omitted */ }

An RAII mutex guard returned by MutexGuard::map, which can point to a subfield of the protected data.

The main difference between MappedMutexGuard and MutexGuard is that the former doesn't support temporarily unlocking and re-locking, since that could introduce soundness issues if the locked object is modified by another thread.

Methods

impl<'a, R: RawMutex + 'a, T: ?Sized + 'a> MappedMutexGuard<'a, R, T>

pub fn map<U: ?Sized, F>(s: Self, f: F) -> MappedMutexGuard<'a, R, U> where     F: FnOnce(&mut T) -> &mut U,

Makes a new MappedMutexGuard for a component of the locked data.

This operation cannot fail as the MutexGuard passed in already locked the mutex.

This is an associated function that needs to be used as MutexGuard::map(...). A method would interfere with methods of the same name on the contents of the locked data.

impl<'a, R: RawMutexFair + 'a, T: ?Sized + 'a> MappedMutexGuard<'a, R, T>

pub fn unlock_fair(s: Self)

Unlocks the mutex using a fair unlock protocol.

By default, mutexes are unfair and allow the current thread to re-lock the mutex before another has the chance to acquire the lock, even if that thread has been blocked on the mutex for a long time. This is the default because it allows much higher throughput as it avoids forcing a context switch on every mutex unlock. This can result in one thread acquiring a mutex many more times than other threads.

However in some cases it can be beneficial to ensure fairness by forcing the lock to pass on to a waiting thread if there is one. This is done by using this method instead of dropping the MutexGuard normally.

Trait Implementations

impl<'a, R: RawMutex + Sync + 'a, T: ?Sized + Sync + 'a> Sync for MappedMutexGuard<'a, R, T>

impl<'a, R: RawMutex + 'a, T: ?Sized + 'a> Send for MappedMutexGuard<'a, R, T> where     R::GuardMarker: Send,

impl<'a, R: RawMutex + 'a, T: ?Sized + 'a> Deref for MappedMutexGuard<'a, R, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, R: RawMutex + 'a, T: ?Sized + 'a> DerefMut for MappedMutexGuard<'a, R, T>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<'a, R: RawMutex + 'a, T: ?Sized + 'a> Drop for MappedMutexGuard<'a, R, T>

fn drop(&mut self)

Executes the destructor for this type.