Trait pharos::Observable[−][src]

pub trait Observable<Event> where
    Event: Clone + 'static + Send, {
    type Error: Error;
    fn observe(
        &mut self, 
        options: ObserveConfig<Event>
    ) -> Observe<'_, Event, Self::Error>;
}
Expand description

Indicate that a type is observable. You can call observe to get a stream of events.

Generally used with a Pharos object which manages the observers for you.

use pharos::*;
use futures::stream::StreamExt;

// The event we want to broadcast
//
#[ derive( Debug, Clone ) ]
//
enum Steps
{
  Step1     ,
  Step2     ,
  Done      ,

  // Data is possible, but it has to be clone and will be cloned for each observer
  // except observers that filter this event out.
  //
  Error(u8) ,
}


impl Steps
{
   // We can use this as a predicate to filter events.
   //
   fn is_err( &self ) -> bool
   {
      match self
      {
         Self::Error(_) => true  ,
         _              => false ,
      }
   }
}


// The object we want to be observable.
//
struct Foo { pharos: Pharos<Steps> };

impl Observable<Steps> for Foo
{
   type Error = PharErr;

   // Pharos implements observable, so we just forward the call.
   //
   fn observe( &mut self, options: ObserveConfig<Steps> ) -> Observe< '_, Steps, Self::Error>
   {
      self.pharos.observe( options )
   }
}


// use in async context
//
async fn task()
{
   let mut foo    = Foo { pharos: Pharos::default() };
   let mut errors = foo.observe( Filter::Pointer( Steps::is_err ).into() ).await.expect( "observe" );

   // will only be notified on errors thanks to the filter.
   //
   let next_error = errors.next().await;
}

Associated Types

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

Pharos implements Sink which has a close method, so observing will no longer be possible after close is called.

Other than that, you might want to have moments in your objects lifetime when you don’t want to take any more observers. Returning a result from observe enables that.

You can of course map the error of pharos to your own error type.

Required methods

Add an observer to the observable. Options allow chosing the channel type and to filter events with a predicate.

Implementors

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.