Struct Condvar 

pub struct Condvar<C> { /* private fields */ }

A condition variable.

Condition variables represent the ability to block a thread such that it consumes no CPU time while waiting for an event to occur. Condition variables are typically associated with a boolean predicate (a condition) and a mutex. The predicate is always verified inside of the mutex before determining that thread must block.

If the underlying RawCondvar guarantees no spurious wakeups, notification return values are exact. Otherwise, they are always false or 0. Consult the documentation of C for whether it provides this guarantee.

Implementations

impl<C: RawCondvar> Condvar<C>

pub const fn new() -> Condvar<C>

Creates a new condition variable which is ready to be waited on and notified.

pub fn raw(&self) -> &C

Returns the underlying raw condvar object.

Note that you will most likely need to import the RawCondvar trait from lock_api to be able to call functions on the raw condvar.

pub fn notify_one(&self) -> bool

Wakes up one blocked thread on this condvar.

If C guarantees no spurious wakeups, returns whether this call notified a waiting thread. Otherwise, always returns false. Threads whose waits end because of a timeout are not counted. Consult the documentation of C for whether it provides this guarantee.

If there is a blocked thread on this condition variable, then it will be woken up from its call to wait, wait_for, or wait_until. Calls to notify_one are not buffered in any way.

To wake up all threads, see notify_all.

pub fn notify_all(&self) -> usize

Wakes up all blocked threads on this condvar.

If C guarantees no spurious wakeups, returns the exact number of waiting threads this call notified. Otherwise, always returns 0. Threads whose waits end because of a timeout are not counted. Consult the documentation of C for whether it provides this guarantee.

This method will ensure that any current waiters on the condition variable are awoken. Calls to notify_all are not buffered in any way.

To wake up only one thread, see notify_one.

pub fn wait<T: ?Sized>(&self, mutex_guard: &mut MutexGuard<'_, C::RawMutex, T>)

Blocks the current thread until this condition variable receives a notification.

This function will atomically unlock the mutex specified (represented by mutex_guard) and block the current thread. This means that calls to notify_one or notify_all which happen logically after the mutex is unlocked are candidates to wake this thread. When this function returns, the lock will have been re-acquired.

This function may return spuriously depending on the underlying RawCondvar. Consult the documentation of C for its guarantees.

Panics

The underlying RawCondvar implementation may panic if another thread is waiting on this condition variable with a different mutex.

pub fn wait_while<T, F>( &self, mutex_guard: &mut MutexGuard<'_, C::RawMutex, T>, condition: F, )

where T: ?Sized, F: FnMut(&mut T) -> bool,

Blocks the current thread until the provided condition becomes false.

condition is checked immediately. If it returns true, this function waits and checks the condition again whenever the wait returns. This repeats until condition returns false.

This function will atomically unlock the mutex specified (represented by mutex_guard) and block the current thread. This means that any calls to notify_*() which happen logically after the mutex is unlocked are candidates to wake this thread up. When this function call returns, the lock specified will have been re-acquired.

Panics

The underlying RawCondvar implementation may panic if another thread is waiting on this condition variable with a different mutex.

impl<R: RawMutexTimed, C: RawCondvarTimed<RawMutex = R>> Condvar<C>

pub fn wait_until<T: ?Sized>( &self, mutex_guard: &mut MutexGuard<'_, C::RawMutex, T>, timeout: <C::RawMutex as RawMutexTimed>::Instant, ) -> WaitTimeoutResult

Waits on this condition variable for a notification, timing out after the specified time instant.

The semantics of this function are equivalent to wait, except that it stops waiting after timeout is reached. A notification or spurious wakeup may make the function return earlier. If the operation times out, it will not return before timeout, but it may return later because of scheduling or platform-specific behavior.

Note that the best effort is made to ensure that the time waited is measured with a monotonic clock, and not affected by the changes made to the system time.

The returned WaitTimeoutResult indicates whether the wait is known to have timed out. Consult the documentation of C for whether a result which is not timed out guarantees that a notification was received.

Like wait, the lock will be re-acquired before this function returns, regardless of whether the timeout elapsed.

Panics

The underlying RawCondvar implementation may panic if another thread is waiting on this condition variable with a different mutex.

pub fn wait_for<T: ?Sized>( &self, mutex_guard: &mut MutexGuard<'_, C::RawMutex, T>, timeout: <C::RawMutex as RawMutexTimed>::Duration, ) -> WaitTimeoutResult

Waits on this condition variable for a notification, timing out after a specified duration.

The semantics of this function are equivalent to wait, except that it stops waiting after the specified duration. A notification or spurious wakeup may make the function return earlier. If the operation times out, it will not return before timeout has elapsed, but it may return later because of scheduling or platform-specific behavior.

Note that the best effort is made to ensure that the time waited is measured with a monotonic clock, and not affected by the changes made to the system time.

The returned WaitTimeoutResult indicates whether the wait is known to have timed out. Consult the documentation of C for whether a result which is not timed out guarantees that a notification was received.

Like wait, the lock will be re-acquired before this function returns, regardless of whether the timeout elapsed.

Panics

The underlying RawCondvar implementation may panic if another thread is waiting on this condition variable with a different mutex.

pub fn wait_while_until<T, F>( &self, mutex_guard: &mut MutexGuard<'_, C::RawMutex, T>, condition: F, timeout: <C::RawMutex as RawMutexTimed>::Instant, ) -> WaitTimeoutResult

where T: ?Sized, F: FnMut(&mut T) -> bool,

Waits on this condition variable for the provided condition to become false, timing out after the specified time instant.

The semantics of this function are equivalent to wait_while, except that it stops waiting after timeout is reached. If the operation times out, it will not return before timeout, but it may return later because of scheduling or platform-specific behavior.

Note that the best effort is made to ensure that the time waited is measured with a monotonic clock, and not affected by the changes made to the system time.

The returned WaitTimeoutResult indicates whether the wait timed out while the condition remained true.

Like wait_while, the lock will be re-acquired before this function returns, regardless of whether the timeout elapsed.

Panics

The underlying RawCondvar implementation may panic if another thread is waiting on this condition variable with a different mutex.

pub fn wait_while_for<T: ?Sized, F>( &self, mutex_guard: &mut MutexGuard<'_, C::RawMutex, T>, condition: F, timeout: <C::RawMutex as RawMutexTimed>::Duration, ) -> WaitTimeoutResult

where F: FnMut(&mut T) -> bool,

Waits on this condition variable for the provided condition to become false, timing out after a specified duration.

The semantics of this function are equivalent to wait_while, except that it stops waiting after the specified duration. If the operation times out, it will not return before timeout has elapsed, but it may return later because of scheduling or platform-specific behavior.

Note that the best effort is made to ensure that the time waited is measured with a monotonic clock, and not affected by the changes made to the system time.

The returned WaitTimeoutResult indicates whether the wait timed out while the condition remained true.

Like wait_while, the lock will be re-acquired before this function returns, regardless of whether the timeout elapsed.

Panics

The underlying RawCondvar implementation may panic if another thread is waiting on this condition variable with a different mutex.

Trait Implementations

impl<C> Debug for Condvar<C>

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

Formats the value using the given formatter.

impl<C: RawCondvar> Default for Condvar<C>

fn default() -> Condvar<C>

Returns the “default value” for a type.