Struct pharos::Pharos

pub struct Pharos<Event> where
    Event: 'static + Clone + Send,  { /* fields omitted */ }

The Pharos lighthouse. When you implement Observable on your type, you can forward the observe method to Pharos and call notify on it.

You can of course create several Pharos (I know, historical sacrilege) for (different) types of events.

Please see the docs for Observable for an example. Others can be found in the README and the examples directory of the repository.

Implementation.

Currently just holds a Vec<Option<Sender>>. It will stop notifying observers if the channel has returned an error, which usually means it is closed or disconnected. However, we currently don't compact the vector or use a more performant data structure for the observers.

In observe, we do loop the vector to find a free spot to re-use before pushing.

Note: we only detect that observers can be removed when Pharos::notify or Pharos::num_observers is being called. Otherwise, we won't find out about disconnected observers and the vector of observers will not mark deleted observers and thus their slots can not be reused.

Right now, in notify, we use join_all from the futures library to notify all observers concurrently. We take all of our senders out of the options in our vector, operate on them and put them back if they did not generate an error.

join_all will allocate a new vector on every notify from what our concurrent futures return. Ideally we would use a data structure which allows &mut access to individual elements, so we can work on them concurrently in place without reallocating. I am looking into the partitions crate, but that's for the next release ;).

Methods

impl<Event> Pharos<Event> where
    Event: 'static + Clone + Send, 

pub fn new(capacity: usize) -> Self

Create a new Pharos. May it's light guide you to safe harbor.

You can set the initial capacity of the vector of senders, if you know you will a lot of observers it will save allocations by setting this to a higher number.

For pharos 0.3.0 on x64 Linux: std::mem::size_of::<Option<Sender<_>>>() == 56 bytes.

pub async fn notify<'_, '_>(&'_ mut self, evt: &'_ Event)

Notify all observers of Event evt.

Currently allocates a new vector for all observers on every run. That will be fixed in future versions.

pub fn storage_len(&self) -> usize

Returns the size of the vector used to store the observers. Useful for debugging and testing if it seems to get to big.

pub fn num_observers(&mut self) -> usize

Returns the number of actual observers that are still listening (have not closed or dropped the Events). This will loop and it will verify for each if they are closed, clearing them from the internal storage if they are closed. This is similar to what notify does, but without sending an event.

Trait Implementations

impl<Event> Observable<Event> for Pharos<Event> where
    Event: 'static + Clone + Send, 

fn observe(&mut self, options: ObserveConfig<Event>) -> Events<Event>

Add an observer to the observable. Options can be in order to choose channel type and to filter events with a predicate.

impl<Event> Default for Pharos<Event> where
    Event: 'static + Clone + Send, 

Creates a new pharos, using 10 as the initial capacity of the vector used to store observers. If this number does really not fit your use case, call Pharos::new.

fn default() -> Self

Returns the "default value" for a type.

impl<Event> Debug for Pharos<Event> where
    Event: 'static + Clone + Send, 

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

Formats the value using the given formatter.