Expand description

rsevents is an implementation of WIN32’s auto- and manual-reset events for the rust world. Events are synchronization primitives (i.e. not implemented atop of mutexes) used to either create other synchronization primitives with or for implementing signalling between threads.

Events come in two different flavors: AutoResetEvent and ManualResetEvent. Internally, both are implemented with the unsafe RawEvent and use the parking_lot_core crate to take care of efficiently suspending (parking) threads while they wait for an event to become signalled, and take care of memory coherence issues between the signalling and signalled threads.

An event is a synchronization primitive that is functionally the equivalent of an awaitable boolean that allows for synchronization between threads. Unlike mutexes and condition variables which are most often used to restrict access to a critical section, events are more appropriate for efficiently signalling remote threads or waiting on a remote thread to change state - or for building your own synchronization types on top of something both light and easy to use.

Structs

An AutoResetEvent is a synchronization primitive that is functionally equivalent to an “awaitable boolean” and can be atomically waited upon and consumed to signal one and only one waiter at a time, thereby guaranteeing exclusive signalling. This is not unlike a multi-producer, multi-consumer non-broadcast Channel<()> with a buffer size of 1, except much more efficient and lightweight.

A ManualResetEvent is an event type best understood as an “awaitable boolean” that efficiently synchronizes thread access to a shared state, allowing one or more threads to wait for a signal from one or more other threads, where the signal could have either occurred in the past or could come at any time in the future.

The default error returned by types implementing Awaitable, with the only possible error being a timeout to a bounded wait() call.

Enums

A representation of the state of an event, which can either be Set (i.e. signalled, ready) or Unset (i.e. not ready).

Traits

The basic interface for waiting on void awaitable types

Denotes the error returned by an Awaitable object for its various wait calls, separating between internal errors preventing the wait from succeeding (e.g. a poison error) and errors due only to a timeout.