This crate contains a cross-platform implementation of auto and manual reset events similar to those found in Microsoft Windows, implemented on top of the core parking lot crate.
An event is best compared to a waitable boolean, and can have either of two states: set and unset. Callers may directly wait on the event itself, foregoing the need for an associated condition variable and mutex.
Events come in two flavors, AutoResetEvent and ManualResetEvent, which differ in their behavior
when it comes to setting (aka signalling) an event. An AutoResetEvent, once signalled, permits
exactly one (and only one) past or future caller to unblock while waiting for the same event,
whereas a ManualResetEvent lacks such fine-grained control and is either signalled and unblocked
for all past/future waiters or none (until its state is toggled).
```rust // create a new, initially unset event let event = AutoResetEvent::new(State::Unset);
// and wrap it in an ARC to allow sharing across thread boundaries let event = Arc::new(event);
// create a worker thread to complete some task { let shared = event.clone(); std::thread::spawn(|| { // perform some task ... // and signal to ONE waiting thread that the result is ready shared.set(); }); }
...
// wait for the spawned thread to finish the queued work event.wait();
```
Structs ManualResetEvent and AutoResetEvent, both implementing the trait Event which exposes
an API that permits waiting indefinitely, waiting for zero time, and waiting for a fixed time limit
(Duration) for an event to be triggered.
See the documentation for more info.
Generally speaking, a mutex or condition variable should always be preferred when it comes to protecting a critical section and ensuring exclusive access due to their well-understood synchronization paradigms and wide support. However, there are other times when a synchronization primitve not coupled to an explicit critical section or protected data is required, in which case it similarly does not make sense to use a mutex and a critical section when a single alternative synchronization primitive is what is actually required.
Any time you find yourself needing a Mutex<bool> and an associated condition variable to
set/test/clear a boolean flag to synchronize state across threads, you should reach for either a
manual- or auto-reset event instead.
rsevents is written and maintained by Mahmoud Al-Qudsi \