Struct shrev::EventChannel

pub struct EventChannel<E> { /* fields omitted */ }

The EventChannel, which is the central component of shrev.

How it works

This channel has a ring buffer, which it allocates with an initial capacity. Once allocated, it writes new events into the buffer, wrapping around when it reaches the "end" of the buffer.

However, before an event gets written into the buffer, the channel checks if all readers have read the event which is about to be overwritten. In case the answer is "No", it will grow the buffer so no events get overwritten.

Readers are stores in the EventChannel itself, because we need to access their position in a write, so we can check what's described above. Thus, you only get a ReaderId as a handle.

What do I use it for?

The EventChannel is basically a single producer, multiple consumer ("SPMC") channel. That is, a write to the channel requires mutable access, while reading can be done with just an immutable reference. All readers (consumers) will always get all the events since their last read (or when they were created, if there was no read yet).

Examples

use std::mem::drop;

use shrev::{EventChannel, ReaderId};

// The buffer will initially be 16 events big
let mut channel = EventChannel::with_capacity(16);

// This is basically with no effect; no reader can possibly observe it
channel.single_write(42i32);

let mut first_reader = channel.register_reader();

// What's interesting here is that we don't check the readers' positions _yet_
// That is because the size of 16 allows us to write 16 events before we need to perform
// such a check.
channel.iter_write(0..4);

// Now, we read 4 events (0, 1, 2, 3)
// Notice how we borrow the ID mutably; this is because logically we modify the reader,
// and we shall not read with the same ID concurrently
let _events = channel.read(&mut first_reader);

// Let's create a second reader; this one will not receive any of the previous events
let mut second_reader = channel.register_reader();

// No event returned
let _events = channel.read(&mut second_reader);

channel.iter_write(4..6);

// Both now get the same two events
let _events = channel.read(&mut first_reader);
let _events = channel.read(&mut second_reader);

// We no longer need our second reader, so we drop it
// This is important, since otherwise the buffer would keep growing if our reader doesn't read
// any events
drop(second_reader);

Methods

impl<E> EventChannel<E> where
    E: Event, 

pub fn new() -> Self

Create a new EventChannel with a default size of 64.

pub fn with_capacity(size: usize) -> Self

Create a new EventChannel with the given starting capacity.

pub fn would_write(&mut self) -> bool

Returns true if any reader would observe an additional event.

This can be used to skip calls to iter_write in case the event construction is expensive.

pub fn register_reader(&mut self) -> ReaderId<E>

Register a new reader.

To be able to read events, a reader id is required. This is because otherwise the channel wouldn't know where in the ring buffer the reader has read to earlier. This information is stored in the channel, associated with the returned ReaderId.

A newly created ReaderId will only receive the events written after its creation.

Once you no longer perform reads with your ReaderId, you should drop it so the channel can safely overwrite events not read by it.

pub fn slice_write(&mut self, events: &[E]) where
    E: Clone, 

Deprecated:

please use iter_write instead

Write a slice of events into storage

pub fn iter_write<I>(&mut self, iter: I) where
    I: IntoIterator<Item = E>,
    I::IntoIter: ExactSizeIterator, 

Write an iterator of events into storage

pub fn drain_vec_write(&mut self, events: &mut Vec<E>)

Drain a vector of events into storage.

pub fn single_write(&mut self, event: E)

Write a single event into storage.

Important traits for StorageIterator<'a, T>

impl<'a, T> Iterator for StorageIterator<'a, T> type Item = &'a T;

pub fn read(&self, reader_id: &mut ReaderId<E>) -> EventIterator<E>

Read any events that have been written to storage since the last read with reader_id (or the creation of the ReaderId, if it hasn't read yet).

Note that this will advance the position of the reader regardless of what you do with the iterator. In other words, calling read without iterating the result won't preserve the events returned. You need to iterate all the events as soon as you got them from this method. This behavior is equivalent to e.g. Vec::drain.

Trait Implementations

impl<E> Default for EventChannel<E> where
    E: Event, 

fn default() -> Self

Returns the "default value" for a type.

impl<E: Debug> Debug for EventChannel<E>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.