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 use SinkExt::send to notify observers.

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 drop observers if the channel has returned an error, which means it is closed or disconnected. However, we currently don't compact the vector. Slots are reused for new observers, but the vector never shrinks.

Note: we only detect that observers can be removed when SinkExt::send 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.

The Sink impl is not very optimized for the moment. It just loops over all observers in each poll method so it will call poll_ready and poll_flush again for observers that already returned Poll::Ready(Ok(())).

TODO: I will do some benchmarking and see if this can be improved, eg. by keeping a state which tracks which observers we still have to poll.

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 observers, if you know you will a lot of observers it will save allocations by setting this to a higher number.

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

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, 

type Error = Error

The error type that is returned if observing is not possible.

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

Will re-use slots from disconnected observers to avoid growing to much.

TODO: provide API for the client to compact the pharos object after reducing the number of observers.

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.

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

type Error = Error

The type of value produced by the sink when an error occurs.

fn poll_ready(
    self: Pin<&mut Self>,
    cx: &mut Context
) -> Poll<Result<(), Self::Error>>

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, evt: Event) -> Result<(), Self::Error>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

fn poll_flush(
    self: Pin<&mut Self>,
    cx: &mut Context
) -> Poll<Result<(), Self::Error>>

Flush any remaining output from this sink.

fn poll_close(
    self: Pin<&mut Self>,
    cx: &mut Context
) -> Poll<Result<(), Self::Error>>

Will close and drop all observers. The pharos object will remain operational however. The main annoyance would be that we'd have to make