Struct EventChannel

Source
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§

Source§

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

Source

pub fn new() -> Self

Create a new EventChannel with a default size of 64.

Examples found in repository?
examples/basic.rs (line 11)
10fn main() {
11    let mut channel = EventChannel::new();
12
13    let mut reader1 = channel.register_reader();
14    let mut reader2 = channel.register_reader();
15
16    channel.single_write(TestEvent { data: 1 });
17
18    // Prints one event
19    println!("reader1 read: {:#?}", collect(channel.read(&mut reader1)));
20    channel.single_write(TestEvent { data: 32 });
21
22    // Prints two events
23    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
24    // Prints no events
25    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
26}
Source

pub fn with_capacity(size: usize) -> Self

Create a new EventChannel with the given starting capacity.

Source

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.

Source

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.

Examples found in repository?
examples/basic.rs (line 13)
10fn main() {
11    let mut channel = EventChannel::new();
12
13    let mut reader1 = channel.register_reader();
14    let mut reader2 = channel.register_reader();
15
16    channel.single_write(TestEvent { data: 1 });
17
18    // Prints one event
19    println!("reader1 read: {:#?}", collect(channel.read(&mut reader1)));
20    channel.single_write(TestEvent { data: 32 });
21
22    // Prints two events
23    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
24    // Prints no events
25    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
26}
Source

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

👎Deprecated: please use iter_write instead

Write a slice of events into storage

Source

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

Write an iterator of events into storage

Source

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

Drain a vector of events into storage.

Source

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

Write a single event into storage.

Examples found in repository?
examples/basic.rs (line 16)
10fn main() {
11    let mut channel = EventChannel::new();
12
13    let mut reader1 = channel.register_reader();
14    let mut reader2 = channel.register_reader();
15
16    channel.single_write(TestEvent { data: 1 });
17
18    // Prints one event
19    println!("reader1 read: {:#?}", collect(channel.read(&mut reader1)));
20    channel.single_write(TestEvent { data: 32 });
21
22    // Prints two events
23    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
24    // Prints no events
25    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
26}
Source

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.

Examples found in repository?
examples/basic.rs (line 19)
10fn main() {
11    let mut channel = EventChannel::new();
12
13    let mut reader1 = channel.register_reader();
14    let mut reader2 = channel.register_reader();
15
16    channel.single_write(TestEvent { data: 1 });
17
18    // Prints one event
19    println!("reader1 read: {:#?}", collect(channel.read(&mut reader1)));
20    channel.single_write(TestEvent { data: 32 });
21
22    // Prints two events
23    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
24    // Prints no events
25    println!("reader2 read: {:#?}", collect(channel.read(&mut reader2)));
26}

Trait Implementations§

Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

fn default() -> Self

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

Auto Trait Implementations§

§

impl<E> Freeze for EventChannel<E>

§

impl<E> !RefUnwindSafe for EventChannel<E>

§

impl<E> Send for EventChannel<E>
where E: Send,

§

impl<E> Sync for EventChannel<E>
where E: Sync,

§

impl<E> Unpin for EventChannel<E>
where E: Unpin,

§

impl<E> UnwindSafe for EventChannel<E>
where E: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

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

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> Event for T
where T: Send + Sync + 'static,