Struct Condvar 

pub struct Condvar(/* private fields */);

Condition variable (for async)

For background information about of the semantics of a condition variable, see Wikipedia and/or std::sync::Condvar.

Unlike std’s condition variables, async-condvar-fair’s do not block the current thread, only the current async task. Also, multiple condition variables may be freely used with multiple different mutexes.

Like all condition variables, async-condvar-wait’s may generate spurious wakeups. After completing a wait, you must re-check the actual condition in your data structure, not simply assume that it must be ready for you.

Implementations

impl Condvar

pub fn new() -> Condvar

impl Condvar

pub fn wait_baton<'c, G>(&'c self, guard: G) -> Waiter<'c, G>

where G: RelockMutexGuard,

Wait for someone to call notify_one or notify_all

Atomically unlocks the mutex corresponding to guard and starts waiting for notify.

This is a future producing (G, Option< Baton <'c>>).

G is a fresh guard for the mutex, which has been unlocked and relocked.

baton is a token representing an possible obligation to either perform the actions that the caller of notify_one is expecting, or re-notify the condvar. See Baton. baton will be None if the wakeup was the result of notify_all.

pub async fn wait<'c, G>( &'c self, guard: G, ) -> <G as RelockMutexGuard>::JustGuard

where G: RelockMutexGuard,

Wait for a notification; caller must worry about cancellation

Like wait_baton but disposes of the baton right away on return.

Beware task cancellation when using with notify_one and an async mutex

When wait, notify_one, and an async mutex, are combined, notifications can easily be lost: perhaps a task calling wait could be cancelled after being woken up by notify_one, but before doing the actual work. If that happens, probably no other task will be signaled and the work would go undone.

So when using notify_one, with an async mutex, it is probably best to use wait_baton.

async-condvar-fair does guarantee that notify_one will ensure that at least one wait call returns to its caller, (In particular, if the wait task is cancelled after being selected by notify_one, but before it manages to acquire the mutex, the condvar will be re-notified.)

But, in async code it is difficult and error-prone to try to avoid waiting. Any await might result in task cancellaton, and then if you’re not using wait_baton, the notification will be lost.

wait_baton avoids this problem. notify_all doesn’t suffer from it because everyone is woken up anyway. If you are using a sync mutex, there is no problem either, because you won’t be awaiting while processing (ie, while holding the mutex) anyway.

pub async fn wait_no_relock<'c, G>(&'c self, guard: G) -> Option<Baton<'c>>

Wait for notification; caller will have to relock the mutex

Like wait_baton but does not relock the mutex.

This can be used with any mutex guard type, even one for which no impl of RelockMutexGuard is available.

wait_no_relock will first start waiting for notifications, and then drop guard (which, with a mutex guard, will unlock the mutex). When wait_no_relock completes, you will very probably want to acquire the mutex again: with wait_no_relock this must be done separately.

Be sure to dispose of the Option<Baton> exactly iff that is appropriate.

Deadlock hazard

There is no type restricton on guard. It is important that you pass the ownership of the actual mutex guard. There is no way for the compiler to spot if you don’t. If (for example) you pass &mut MutexGuard, you will fail to unlock the mutex, usually resulting in deadlock.

impl Condvar

pub fn notify_one(&self)

Notify a waiting task (aka “signal”)

If there are any tasks in wait_baton (or wait_no_relock), at least one of them will wake up and get Some(Baton) from wait_baton.

Likewise, if there are any tasks in wait, at least one of them will wake up and return. But if that task is cancelled after wait completss, the notification may be lost. See wait and Baton for a discussion of the interaction between task cancellation and notify_one.

Notifications do not “stack” or “count”. Calling notify_one several times might still wake up only one task.

impl Condvar

pub fn notify_all(&self)

Notify all waiting tasks (aka “broadcast”)

Wake up all tasks currently in wait, wait_baton, and wait_no_relock,

Each the tasks in wait and wait_baton will start to try to reacquire the mutex; they will then (in general) take turns to return from wait/wait_baton with the mutex held.

All tasks will get None rather than Some( Baton ), from wait_baton or wait_no_relock - even possibly tasks which are in the process of waking up because of a previous call to notify_one.

impl Condvar

pub fn make_baton<'c>(&'c self) -> Baton<'c>

Make a baton directly, without waiting

This may be useful in unusual situations.

If the returned Baton is simply dropped, this is the same as notify_one.

Trait Implementations

impl Debug for Condvar

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

Formats the value using the given formatter.

impl Default for Condvar

fn default() -> Condvar

Returns the “default value” for a type.