Struct WatchReceiver

pub struct WatchReceiver<T> {
    receiver: Receiver<T>,
}

Efficient access to state data via a [tokio] [watch::Receiver] channel, while avoiding deadlocks.

Returns data from the most recent state, regardless of how many times you call its methods.

Cloned instances provide identical state data.

Correctness

To avoid deadlocks, see the correctness note on WatchReceiver::with_watch_data.

Note

If a lot of blocks are committed at the same time, the watch channel will skip some block updates, even though those updates were committed to the state.

Fields

receiver: Receiver<T>

The receiver for the current state data.

Implementations

impl<T> WatchReceiver<T>

pub fn new(receiver: Receiver<T>) -> Self

Create a new WatchReceiver from a watch channel receiver.

impl<T> WatchReceiver<T>

where T: Clone,

pub fn with_watch_data<U, F>(&self, f: F) -> U

where F: FnOnce(T) -> U,

Maps the current data T to U by applying a function to the watched value, while holding the receiver lock as briefly as possible.

This helper method is a shorter way to borrow the value from the [watch::Receiver] and extract some information from it.

Does not mark the watched data as seen.

Performance

A single read lock is acquired to clone T, and then released after the clone. To make this clone efficient, large or expensive T can be wrapped in an std::sync::Arc. (Or individual fields can be wrapped in an std::sync::Arc.)

Correctness

To prevent deadlocks:

• receiver.borrow() should not be called before this method while in the same scope.

It is important to avoid calling borrow more than once in the same scope, which effectively tries to acquire two read locks to the shared data in the watch channel. If that is done, there’s a chance that the [watch::Sender] tries to send a value, which starts acquiring a write-lock, and prevents further read-locks from being acquired until the update is finished.

What can happen in that scenario is:

1. The receiver manages to acquire a read-lock for the first borrow
2. The sender starts acquiring the write-lock
3. The receiver fails to acquire a read-lock for the second borrow

Now both the sender and the receivers hang, because the sender won’t release the lock until it can update the value, and the receiver won’t release its first read-lock until it acquires the second read-lock and finishes what it’s doing.

pub fn cloned_watch_data(&self) -> T

Returns a clone of the watch data in the channel. Cloning the watched data helps avoid deadlocks.

Does not mark the watched data as seen.

See with_watch_data() for details.

pub async fn changed(&mut self) -> Result<(), RecvError>

Calls [watch::Receiver::changed()] and returns the result. Returns when the inner value has been updated, even if the old and new values are equal.

Marks the watched data as seen.

pub fn has_changed(&self) -> Result<bool, RecvError>

Calls [watch::Receiver::has_changed()] and returns the result. Returns true when the inner value has been updated, even if the old and new values are equal.

Does not mark the watched data as seen.

pub fn mark_as_seen(&mut self)

Marks the watched data as seen.

pub fn mark_changed(&mut self)

Marks the watched data as unseen. Calls [watch::Receiver::mark_changed()].

Trait Implementations

impl<T: Clone> Clone for WatchReceiver<T>

fn clone(&self) -> WatchReceiver<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for WatchReceiver<T>

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

Formats the value using the given formatter.