Trait otter_nodejs_tests::async_condvar_fair::RelockMutexGuard

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

    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 dpendencies 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 convvenient for the wait futures to produce just the mutex guard.

That is what this type is.

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

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.

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, Global>>

fn unlock_for_relock(
    self
) -> <(MutexGuard<'i, T>, &'o Mutex<T>) as RelockMutexGuard>::MutexRef

fn lock(
    l: <(MutexGuard<'i, T>, &'o Mutex<T>) as RelockMutexGuard>::MutexRef
) -> <(MutexGuard<'i, T>, &'o Mutex<T>) as RelockMutexGuard>::LockFuture

Implementors

impl<'l, T> RelockMutexGuard for MutexGuard<'l, RawFairMutex, T> where
    T: Send, 

type MutexRef = &'l Mutex<RawFairMutex, T>

type JustGuard = MutexGuard<'l, RawFairMutex, T>

type LockFuture = Pin<Box<dyn Future<Output = <MutexGuard<'l, RawFairMutex, T> as RelockMutexGuard>::JustGuard> + Send + 'l, Global>>

impl<'l, T> RelockMutexGuard for MutexGuard<'l, RawMutex, T> where
    T: Send, 

type MutexRef = &'l Mutex<RawMutex, T>

type JustGuard = MutexGuard<'l, RawMutex, T>

type LockFuture = Pin<Box<dyn Future<Output = <MutexGuard<'l, RawMutex, T> as RelockMutexGuard>::JustGuard> + Send + 'l, Global>>