Struct synchronoise::event::SignalEvent

pub struct SignalEvent { /* fields omitted */ }

A synchronization primitive that allows one or more threads to wait on a signal from another thread.

With a SignalEvent, it's possible to have one or more threads gate on a signal from another thread. The behavior for what happens when an event is signaled depends on the value of the signal_kind parameter given to new, or whether auto or manual is used to construct the SignalEvent:

• A value of SignalKind::Auto (or a SignalEvent created via SignalEvent::auto()) will automatically reset the signal when a thread is resumed by this event. If more than one thread is waiting on the event when it is signaled, only one will be resumed.
• A value of SignalKind::Manual (or a SignalEvent created via SignalEvent::manual()) will remain signaled until it is manually reset. If more than one thread is waiting on the event when it is signaled, all of them will be resumed. Any other thread that tries to wait on the signal before it is reset will not be blocked at all.

SignalEvent is a port of System.Threading.EventWaitHandle from .NET.

Example

The following example uses two SignalEvents:

• start_signal is used as a kind of std::sync::Barrier, that keeps all the threads inside the loop from starting until they all have been spawned. All the start.wait() calls resume when start_signal.signal() is called after the initial loop.
  • Note that because the "coordinator" doesn't wait for each thread to be scheduled before signaling, it's possible that some later threads may not have had a chance to enter start.wait() before the signal is set. In this case they won't block in the first place, and immediately return.
• stop_signal is used to wake up the "coordinator" thread when each "worker" thread is finished with its work. This allows it to keep a count of the number of threads yet to finish, so it can exit its final loop when all the threads have stopped.

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

let start_signal = Arc::new(SignalEvent::manual(false));
let stop_signal = Arc::new(SignalEvent::auto(false));
let mut thread_count = 5;

for i in 0..thread_count {
    let start = start_signal.clone();
    let stop = stop_signal.clone();
    thread::spawn(move || {
        // as a Manual-reset signal, all the threads will start at the same time
        start.wait();
        thread::sleep(Duration::from_secs(i));
        println!("thread {} activated!", i);
        stop.signal();
    });
}

start_signal.signal();

while thread_count > 0 {
    // as an Auto-reset signal, this will automatically reset when resuming
    // so when the loop comes back, we don't have to reset before blocking again
    stop_signal.wait();
    thread_count -= 1;
}

println!("all done!");

Methods

impl SignalEvent

pub fn new(init_state: bool, signal_kind: SignalKind) -> SignalEvent

Creates a new SignalEvent with the given starting state and reset behavior.

If init_state is true, then this SignalEvent will start with the signal already set, so that threads that wait will immediately unblock.

pub fn auto(init_state: bool) -> SignalEvent

Creates a new automatically-resetting SignalEvent with the given starting state.

If init_state is true, then this SignalEvent will start with the signal already set, so that the first thread that tries to wait will immediately unblock.

pub fn manual(init_state: bool) -> SignalEvent

Creates a new manually-resetting SignalEvent with the given starting state.

If init_state is true, then this SignalEvent will start with the signal alraedy set, so that threads that wait will immediately unblock until reset is called.

pub fn status(&self) -> bool

Returns the current signal status of the SignalEvent.

pub fn signal(&self)

Sets the signal on this SignalEvent, potentially waking up one or all threads waiting on it.

If more than one thread is waiting on the event, the behavior is different depending on the SignalKind passed to the event when it was created. For a value of Auto, one thread will be resumed. For a value of Manual, all waiting threads will be resumed.

If no thread is currently waiting on the event, its state will be set regardless. Any future attempts to wait on the event will unblock immediately, except for a SignalKind of Auto, which will immediately unblock the first thread only.

pub fn reset(&self)

Resets the signal on this SignalEvent, allowing threads that wait on it to block.

pub fn wait(&self)

Blocks this thread until another thread calls signal.

If this event is already set, then this function will immediately return without blocking. For events with a SignalKind of Auto, this will reset the signal so that the next thread to wait will block.

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

Blocks this thread until either another thread calls signal, or until the timeout elapses.

This function returns the status of the signal when it woke up. If this function exits because the signal was set, and this event has a SignalKind of Auto, the signal will be reset so that the next thread to wait will block.