pub struct SignalEvent { /* private fields */ }
Expand description
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 aSignalEvent
created viaSignalEvent::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 aSignalEvent
created viaSignalEvent::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 SignalEvent
s:
start_signal
is used as a kind ofstd::sync::Barrier
, that keeps all the threads inside the loop from starting until they all have been spawned. All thestart.wait()
calls resume whenstart_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.
- 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
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!");
Implementations§
Source§impl SignalEvent
impl SignalEvent
Sourcepub fn new(init_state: bool, signal_kind: SignalKind) -> 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.
Sourcepub fn auto(init_state: bool) -> SignalEvent
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.
Sourcepub fn manual(init_state: bool) -> SignalEvent
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.
Sourcepub fn signal(&self)
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.
Sourcepub fn reset(&self)
pub fn reset(&self)
Resets the signal on this SignalEvent
, allowing threads that wait on it to block.
Sourcepub fn wait(&self)
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.
Sourcepub fn wait_timeout(&self, timeout: Duration) -> bool
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.
Auto Trait Implementations§
impl !Freeze for SignalEvent
impl RefUnwindSafe for SignalEvent
impl Send for SignalEvent
impl Sync for SignalEvent
impl Unpin for SignalEvent
impl UnwindSafe for SignalEvent
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Layout§
Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...)
attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.
Size: 384 bytes