Trait async_condvar_fair::RelockMutexGuard

pub trait RelockMutexGuard {
    type MutexRef: Clone + Send;
    type JustGuard;
    type LockFuture: Future<Output = Self::JustGuard> + Send;

    // Required methods
    fn unlock_for_relock(self) -> Self::MutexRef;
    fn lock(r: Self::MutexRef) -> Self::LockFuture;
}

Lock guards that can be unlocked and relocked

Purpose

Condvar::wait_baton and wait need to unlock and then relock the mutex. So, they need to be able to recover &Mutex from the guard.

Regaining the mutex ref

If the lock in use doesn’t support this (e.g., at the time of writing, std::sync::Mutex, it is usually possible to implement this trait on a tuple struct of guard and lock reference (and, therefore, pass that tuple struct to Condvar::wait.

Provided implementations and support

Implementations are provided for a handful of common MutexGuard types. Contributions of more (with the appropriate optional dependencies in Cargo.toml are welcome.

The RelockMutexGuard! macro can save much boilerplate in the common cases.

Semantics

async-condvar-fair assumes that RelockMutexGuard impl’s are sensible. If they aren’t, malfunctions including deadlocks or livelocks or panics are possible. But memory safety won’t be compromised.

Required Associated Types

type MutexRef: Clone + Send

The reference to the mutex, recovered after unlocking.

type JustGuard

The actual guard type.

Where Self (the argument to wait_baton or wait contains both a guard and a separate mutex reference, it is typically most convenient for the wait futures to produce just the mutex guard.

That is what this type is.

type LockFuture: Future<Output = Self::JustGuard> + Send

The type of the relock future.

Required Methods

fn unlock_for_relock(self) -> Self::MutexRef

Unlock the mutex and return a reference tt.

fn lock(r: Self::MutexRef) -> Self::LockFuture

Relock the mutex, given a reference.

Poisoning (as found in std::sync::Mutedx) will have to propagate poisoning as panics, or or ignore it, since notify_one insists that someone must go and acquire the mutex which they can’t if that always fails due to poisoning.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<'o, 'i, T> RelockMutexGuard for (MutexGuard<'i, T>, &'o Mutex<T>)

where T: Send,

type MutexRef = &'o Mutex<T>

type JustGuard = MutexGuard<'o, T>

type LockFuture = Pin<Box<dyn Future<Output = <(MutexGuard<'i, T>, &'o Mutex<T>) as RelockMutexGuard>::JustGuard> + Send + 'o>>

fn unlock_for_relock(self) -> Self::MutexRef

fn lock(l: Self::MutexRef) -> Self::LockFuture

Implementors