Struct synchronoise::CountdownEvent

pub struct CountdownEvent { /* fields omitted */ }

A synchronization primitive that signals when its count reaches zero.

With a CountdownEvent, it's possible to cause one thread to wait on a set of computations occurring in other threads by making the other threads interact with the counter as they perform their work.

The main limitation of a CountdownEvent is that once its counter reaches zero (even by starting there), any attempts to update the counter will return CountdownError::AlreadySet until the counter is reset by calling reset or reset_to_count.

CountdownEvent is a port of System.Threading.CountdownEvent from .NET.

Example

use synchronoise::CountdownEvent;
use std::sync::Arc;
use std::thread;
use std::time::Duration;

let counter = Arc::new(CountdownEvent::new(5));

for i in 0..5 {
    let signal = counter.clone();
    thread::spawn(move || {
        thread::sleep(Duration::from_secs(3));
        println!("thread {} activated!", i);
        signal.decrement();
    });
}

counter.wait();

println!("all done!");

Methods

impl CountdownEvent

fn new(count: isize) -> CountdownEvent

Creates a new CountdownEvent, initialized to the given count.

fn reset(&mut self)

Resets the counter to the count given to new.

This function is safe because the &mut self enforces that no other references or locks exist.

fn reset_to_count(&mut self, count: isize)

Resets the counter to the given count.

This function is safe because the &mut self enforces that no other references or locks exist.

fn count(&self) -> isize

Returns the current counter value.

fn add(&self, count: isize) -> Result<(), CountdownError>

Adds the given count to the counter.

Errors

If the counter is already at or below zero, this function will return an error.

If the given count would overflow an isize, this function will return an error.

fn signal(&self, count: isize) -> Result<bool, CountdownError>

Subtracts the given count to the counter, and returns whether this caused any waiting threads to wake up.

Errors

If the counter was already at or below zero, this function will return an error.

If the given count is greater than the current counter, this function will return an error.

fn increment(&self) -> Result<(), CountdownError>

Adds one to the count.

Errors

See add for the situations where this function will return an error.

fn decrement(&self) -> Result<bool, CountdownError>

Subtracts one from the counter, and returns whether this caused any waiting threads to wake up.

Errors

See signal for the situations where this function will return an error.

fn guard(&self) -> Result<CountdownGuard, CountdownError>

Increments the counter, then returns a guard object that will decrement the counter upon drop.

Errors

This function will return the same errors as add. If the event has already signaled by the time the guard is dropped (and would cause its decrement call to return an error), then the error will be silently ignored.

fn wait(&self)

Blocks the current thread until the counter reaches zero.

This function will block indefinitely until the counter reaches zero. It will return immediately if it is already at zero.

fn wait_timeout(&self, timeout: Duration) -> (isize, bool)

Blocks the current thread until the timer reaches zero, or until the given timeout elapses, returning the count at the time of wakeup and whether the timeout is known to have elapsed.

This function will return immediately if the counter was already at zero. Otherwise, it will block for roughly no longer than timeout. Due to limitations in the platform specific implementation of std::sync::Condvar, this method could spuriously wake up both before the timeout elapsed and without the count being zero.