pub struct EventChannel<E> { /* private fields */ }
Expand description

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);

Implementations

Create a new EventChannel with a default size of 64.

Create a new EventChannel with the given starting capacity.

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.

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.

👎 Deprecated:

please use iter_write instead

Write a slice of events into storage

Write an iterator of events into storage

Drain a vector of events into storage.

Write a single event into storage.

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

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.