1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

//! Event handler, pull based, that uses shred to synchronize access, and ringbuffers for internal
//! storage, to make it possible to do immutable reads.
//!
//! See examples directory for examples.

#![deny(missing_docs)]

extern crate shred;

pub use storage::ReaderId;

use std::fmt::Debug;

use storage::{RBError, RingBufferStorage};

mod storage;

/// Marker trait for data to use with the EventHandler.
///
/// Has an implementation for all types where its bounds are satisfied.
pub trait Event: Send + Sync + Clone + 'static {}
impl<T> Event for T
where
    T: Send + Sync + Clone + 'static,
{
}

const DEFAULT_MAX_SIZE: usize = 200;

/// Event handler for managing many separate event types.
pub struct EventHandler {
    res: shred::Resources,
}

/// Possible errors returned by the EventHandler
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EventError<E: Debug + Clone + PartialEq> {
    /// If a writer tries to write more data than the max size of the ringbuffer, in a single call
    TooLargeWrite,
    /// If a reader is more than the entire ringbuffer behind in reading, this will be returned.
    /// Contains the data that could be salvaged
    LostData(Vec<E>, usize),
    /// If attempting to use a reader for a different data type than the storage contains.
    InvalidReader,
    /// If attempting to read/write events or register a reader for an event type that has not been
    /// registered.
    InvalidEventType,
}

impl<E: Debug + Clone + PartialEq> Into<EventError<E>> for RBError<E> {
    fn into(self) -> EventError<E> {
        match self {
            RBError::TooLargeWrite => EventError::TooLargeWrite,
            RBError::InvalidReader => EventError::InvalidReader,
            RBError::LostData(retained, missed_num) => EventError::LostData(retained, missed_num),
        }
    }
}

impl EventHandler {
    /// Create a new EventHandler
    pub fn new() -> EventHandler {
        EventHandler { res: shred::Resources::new() }
    }

    /// Register an event type.
    ///
    /// This will register the event type and allocate ringbuffer storage for the event type with
    /// a default max size of 200 events. Once the 200 mark is reached, and a reader has still not
    /// read the events, the buffer will overflow, and the reader will get an error on the next
    /// read.
    pub fn register<E: Event + Debug + Clone + PartialEq>(&mut self) {
        self.register_with_size::<E>(DEFAULT_MAX_SIZE);
    }

    /// Register an event type, with a given maximum number of events before overflowing.
    ///
    /// This will register the event type and allocate ringbuffer storage for the event type with
    /// the given size. Once that size mark is reached, and a reader has still not read the events,
    /// the buffer will overflow, and the reader will get an error on the next read.
    pub fn register_with_size<E: Event + Debug + Clone + PartialEq>(&mut self, max_size: usize) {
        use shred::ResourceId;

        if self.res.has_value(
            ResourceId::new::<RingBufferStorage<E>>(),
        )
        {
            return;
        }

        self.res.add(RingBufferStorage::<E>::new(max_size));
    }

    /// Register a reader of an event type.
    ///
    /// To be able to read events, a reader id is required. This is because otherwise the handler
    /// wouldn't know where in the ringbuffer the reader has read to earlier. This information is
    /// stored in the reader id.
    pub fn register_reader<E: Event + Debug + Clone + PartialEq>(
        &mut self,
    ) -> Result<ReaderId, EventError<E>> {
        match self.res.try_fetch_mut::<RingBufferStorage<E>>(0) {
            Some(ref mut storage) => Ok(storage.new_reader_id()),
            None => Err(EventError::InvalidEventType),
        }
    }

    /// Write a number of events into its storage.
    pub fn write<E: Event + Debug + Clone + PartialEq>(
        &mut self,
        events: &mut Vec<E>,
    ) -> Result<(), EventError<E>> {
        if events.len() == 0 {
            return Ok(());
        }
        match self.res.try_fetch_mut::<RingBufferStorage<E>>(0) {
            Some(ref mut storage) => {
                match storage.write(events) {
                    Ok(_) => Ok(()),
                    Err(err) => Err(err.into()),
                }
            }
            None => Err(EventError::InvalidEventType),
        }
    }

    /// Write a single event into its storage.
    pub fn write_single<E: Event + Debug + Clone + PartialEq>(
        &mut self,
        event: E,
    ) -> Result<(), EventError<E>> {
        match self.res.try_fetch_mut::<RingBufferStorage<E>>(0) {
            Some(ref mut storage) => {
                storage.write_single(event);
                Ok(())
            }
            None => Err(EventError::InvalidEventType),
        }
    }

    /// Read any events that have been written to storage since the readers last read.
    pub fn read<E: Event + Debug + Clone + PartialEq>(
        &self,
        reader_id: &mut ReaderId,
    ) -> Result<Vec<E>, EventError<E>> {
        match self.res.try_fetch::<RingBufferStorage<E>>(0) {
            Some(ref storage) => {
                match storage.read(reader_id) {
                    Ok(data) => Ok(data),
                    Err(err) => Err(err.into()),
                }
            }
            None => Err(EventError::InvalidEventType),
        }
    }
}