Crate eventador[−][src]
This crate provides a lock-free Pub/Sub event-bus based on the eventador pattern from LMAX.
Both sync and async APIs are available.
Examples
Basic sync usage:
use eventador::Eventador; let eventbus = Eventador::new(4).unwrap(); let subscriber = eventbus.subscribe::<usize>(); let i: usize = 1234; eventbus.publish(i); let mut publisher = eventbus.publisher(); publisher.send(i + 1111); let mut msg = subscriber.recv(); assert_eq!(i, *msg); msg = subscriber.recv(); assert_eq!(i + 1111, *msg);
Basic async usage:
use eventador::{Eventador, SinkExt}; let eventbus = Eventador::new(4).unwrap(); let subscriber = eventbus.async_subscriber::<usize>(); let mut publisher = eventbus.async_publisher(4); let i: usize = 1234; publisher.send(i).await.expect("could not publish event"); let mut msg = subscriber.recv().await.unwrap(); assert_eq!(i, *msg);
Please use the provided example programs for a more thorough approach on how to use this crate.
Why?
Event-buses ease the development burden of concurrent programs by enabling concurrent application subroutines to interact and affect other subroutines through events. Of course, a poor implementation can become a serious bottleneck depending on the application's needs.
Eventador embraces the Rust model of Choose Your Guarantees ™ by offering different policies for publishing when subscribers are lagging. These are represented as WaitStrategies, with the default being to wait for all subscribers to read an event before it is overwritten.
Design Considerations
Ring Buffer
Like Eventador, most event-bus implementations use some form of ring buffer for the underlying
data structure to store published events. As such, an Eventador instance cannot indefinitely
grow to accommodate events, unlike a Vec
. In the strictest model (and Eventador's default
approach), new events must overwrite the oldest event that has already been read by all its
subscribers. In other words, publishers cannot publish an event to the ring buffer until all
subscribers for the next overwrite-able event have consumed it. This model favors the
subscribers so that no event is lost or overwritten without first being handled by every
concerned party.
Other implementations, like bus-queue, solve this problem by ignoring lagging subscribers, and treating publishers as first-class operators. This is the opposite extreme to Eventador's default.
Ultimately, there should not have to be a compromise between what a user wants to prioritize. How an event-bus handles the lagging-consumer problem should be left to the user to decide through configuration.
LMAX Disruptor
The LMAX Disruptor serves as a basis for a lot of event-bus implementations, though the contemporary architecture of the Disruptor looks very different from the one presented in the outdated LMAX white-paper. Eventador draws from the principles of the current Disruptor architecture, but the similarities stop there.
A sequencer atomically assigns an event to an index in the ring buffer on publishing of an event.
Subscribers internally have their own sequencer to determine their last read event in the ring buffer. On receiving a subscribed message, the sequencer is atomically updated to reflect that it can now receive the next event.
Lock-free
Eventador has the potential to be a high-contention (aka bottle-necking) structure to a given concurrent program, so the implementation needs to handle contention as effectively as possible. Atomic CAS operations are generally faster than locking, and is the preferred approach to handle contention in this implementation.
TypeId
This crate relies on the use of TypeId
to determine what type an event is, and what types of
events a subscriber is subscribed to.
Unfortunately, due to the limitations of Rust reflection tools, an Enum will have a different TypeId than an Enum variant. This means that a subscriber must subscribe to the Enum type and ignore any variants it's not interested in that it receives. Likewise, the publisher must publish events as the Enum type and not the variant in order to maintain that consistency.
Structs
AsyncPublisher | A handle to asynchronously publish to the event-bus. |
AsyncSubscriber | A handle to subscribe to events and receive them asynchronously. |
EventRead | A wrapper that can be de-referenced to access and read the event. |
Eventador | A lock-free and thread-safe event-bus implementation. |
PublishError | An error thrown by the |
Publisher | A handle to publish events to the event-bus. |
Subscriber | A handle to receive events that were subscribed to from the event-bus. |
Enums
WaitStrategy | Declares the policy for what producers should do when consumers are lagging. |
Traits
SinkExt | async An extension trait for |
StreamExt | async An extension trait for |