Trait Watcher

pub trait Watcher: Clone {
    type Value: Clone + Eq;

    // Required methods
    fn get(&mut self) -> Self::Value;
    fn is_connected(&self) -> bool;
    fn poll_updated(
        &mut self,
        cx: &mut Context<'_>,
    ) -> Poll<Result<Self::Value, Disconnected>>;

    // Provided methods
    fn updated(&mut self) -> NextFut<'_, Self>  { ... }
    fn initialized<T, W>(&mut self) -> InitializedFut<'_, T, W, Self> 
       where W: Nullable<T>,
             Self: Watcher<Value = W> { ... }
    fn stream(self) -> Stream<Self>
       where Self: Unpin { ... }
    fn stream_updates_only(self) -> Stream<Self>
       where Self: Unpin { ... }
    fn map<T: Clone + Eq>(
        self,
        map: impl Fn(Self::Value) -> T + Send + Sync + 'static,
    ) -> Map<Self, T> { ... }
    fn filter<T>(
        self,
        filter: impl Fn(&T) -> bool + Send + Sync + 'static,
    ) -> Filter<Self, T>
       where T: Clone + Eq,
             Self: Watcher<Value = T> { ... }
    fn or<W: Watcher>(self, other: W) -> (Self, W) { ... }
}

A handle to a value that’s represented by one or more underlying Watchables.

A Watcher can get the current value, and will be notified when the value changes. Only the most recent value is accessible, and if the threads with the underlying Watchables change the value faster than the threads with the Watcher can keep up with, then it’ll miss in-between values. When the thread changing the Watchable pauses updating, the Watcher will always end up reporting the most recent state eventually.

Watchers can be modified via Watcher::map to observe a value derived from the original value via a function.

Watchers can be combined via Watcher::or to allow observing multiple values at once and getting an update in case any of the values updates.

One of the underlying Watchables might already be dropped. In that case, the watcher will be “disconnected” and return Err(Disconnected) on some function calls or, when turned into a stream, that stream will end. This property can also be checked with Watcher::is_connected.

Required Associated Types

type Value: Clone + Eq

The type of value that can change.

We require Clone, because we need to be able to make the values have a lifetime that’s detached from the original Watchable’s lifetime.

We require Eq, to be able to check whether the value actually changed or not, so we can notify or not notify accordingly.

Required Methods

fn get(&mut self) -> Self::Value

Returns the current state of the underlying value.

If any of the underlying Watchable values has been dropped, then this might return an outdated value for that watchable, specifically, the latest value that was fetched for that watchable, as opposed to the latest value that was set on the watchable before it was dropped.

fn is_connected(&self) -> bool

Whether this watcher is still connected to all of its underlying Watchables.

Returns false when any of the underlying watchables has been dropped.

fn poll_updated( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<Self::Value, Disconnected>>

Polls for the next value, or returns Disconnected if one of the underlying Watchables has been dropped.

Provided Methods

fn updated(&mut self) -> NextFut<'_, Self>

Returns a future completing with Ok(value) once a new value is set, or with Err(Disconnected) if the connected Watchable was dropped.

Cancel Safety

The returned future is cancel-safe.

fn initialized<T, W>(&mut self) -> InitializedFut<'_, T, W, Self>

where W: Nullable<T>, Self: Watcher<Value = W>,

Returns a future completing once the value is set to Some value.

If the current value is Some value, this future will resolve immediately.

This is a utility for the common case of storing an Option inside a Watchable.

Cancel Safety

The returned future is cancel-safe.

fn stream(self) -> Stream<Self>

where Self: Unpin,

Returns a stream which will yield the most recent values as items.

The first item of the stream is the current value, so that this stream can be easily used to operate on the most recent value.

Note however, that only the last item is stored. If the stream is not polled when an item is available it can be replaced with another item by the time it is polled.

This stream ends once the original Watchable has been dropped.

Cancel Safety

The returned stream is cancel-safe.

fn stream_updates_only(self) -> Stream<Self>

where Self: Unpin,

Returns a stream which will yield the most recent values as items, starting from the next unobserved future value.

This means this stream will only yield values when the watched value changes, the value stored at the time the stream is created is not yielded.

Note however, that only the last item is stored. If the stream is not polled when an item is available it can be replaced with another item by the time it is polled.

This stream ends once the original Watchable has been dropped.

Cancel Safety

The returned stream is cancel-safe.

fn map<T: Clone + Eq>( self, map: impl Fn(Self::Value) -> T + Send + Sync + 'static, ) -> Map<Self, T>

Maps this watcher with a function that transforms the observed values.

The returned watcher will only register updates, when the mapped value observably changes.

fn filter<T>( self, filter: impl Fn(&T) -> bool + Send + Sync + 'static, ) -> Filter<Self, T>

where T: Clone + Eq, Self: Watcher<Value = T>,

fn or<W: Watcher>(self, other: W) -> (Self, W)

Returns a watcher that updates every time this or the other watcher updates, and yields both watcher’s items together when that happens.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<S: Watcher, T: Watcher> Watcher for (S, T)

type Value = (<S as Watcher>::Value, <T as Watcher>::Value)

fn get(&mut self) -> Self::Value

fn is_connected(&self) -> bool

fn poll_updated( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<Self::Value, Disconnected>>

Implementors

impl<T: Clone + Eq> Watcher for Direct<T>

type Value = T

impl<T: Clone + Eq, W: Watcher<Value = T>> Watcher for Join<T, W>

type Value = Vec<T>

impl<W, T> Watcher for Filter<W, T>

where T: Clone + Eq, W: Watcher<Value = T>,

type Value = Option<T>

impl<W: Watcher, T: Clone + Eq> Watcher for Map<W, T>

type Value = T