Struct tokio::sync::watch::Receiver

source ·
pub struct Receiver<T> { /* private fields */ }
Expand description

Receives values from the associated Sender.

Instances are created by the channel function.

To turn this receiver into a Stream, you can use the WatchStream wrapper.

Implementations§

source§

impl<T> Receiver<T>

source

pub fn borrow(&self) -> Ref<'_, T>

Returns a reference to the most recently sent value.

This method does not mark the returned value as seen, so future calls to changed may return immediately even if you have already seen the value with a call to borrow.

Outstanding borrows hold a read lock on the inner value. This means that long-lived borrows could cause the producer half to block. It is recommended to keep the borrow as short-lived as possible. Additionally, if you are running in an environment that allows !Send futures, you must ensure that the returned Ref type is never held alive across an .await point, otherwise, it can lead to a deadlock.

The priority policy of the lock is dependent on the underlying lock implementation, and this type does not guarantee that any particular policy will be used. In particular, a producer which is waiting to acquire the lock in send might or might not block concurrent calls to borrow, e.g.:

Potential deadlock example
// Task 1 (on thread A)    |  // Task 2 (on thread B)
let _ref1 = rx.borrow();   |
                           |  // will block
                           |  let _ = tx.send(());
// may deadlock            |
let _ref2 = rx.borrow();   |
Examples
use tokio::sync::watch;

let (_, rx) = watch::channel("hello");
assert_eq!(*rx.borrow(), "hello");
source

pub fn borrow_and_update(&mut self) -> Ref<'_, T>

Returns a reference to the most recently sent value and marks that value as seen.

This method marks the current value as seen. Subsequent calls to changed will not return immediately until the Sender has modified the shared value again.

Outstanding borrows hold a read lock on the inner value. This means that long-lived borrows could cause the producer half to block. It is recommended to keep the borrow as short-lived as possible. Additionally, if you are running in an environment that allows !Send futures, you must ensure that the returned Ref type is never held alive across an .await point, otherwise, it can lead to a deadlock.

The priority policy of the lock is dependent on the underlying lock implementation, and this type does not guarantee that any particular policy will be used. In particular, a producer which is waiting to acquire the lock in send might or might not block concurrent calls to borrow, e.g.:

Potential deadlock example
// Task 1 (on thread A)                |  // Task 2 (on thread B)
let _ref1 = rx1.borrow_and_update();   |
                                       |  // will block
                                       |  let _ = tx.send(());
// may deadlock                        |
let _ref2 = rx2.borrow_and_update();   |
source

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

Checks if this channel contains a message that this receiver has not yet seen. The new value is not marked as seen.

Although this method is called has_changed, it does not check new messages for equality, so this call will return true even if the new message is equal to the old message.

Returns an error if the channel has been closed.

Examples
use tokio::sync::watch;

#[tokio::main]
async fn main() {
    let (tx, mut rx) = watch::channel("hello");

    tx.send("goodbye").unwrap();

    assert!(rx.has_changed().unwrap());
    assert_eq!(*rx.borrow_and_update(), "goodbye");

    // The value has been marked as seen
    assert!(!rx.has_changed().unwrap());

    drop(tx);
    // The `tx` handle has been dropped
    assert!(rx.has_changed().is_err());
}
source

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

Waits for a change notification, then marks the newest value as seen.

If the newest value in the channel has not yet been marked seen when this method is called, the method marks that value seen and returns immediately. If the newest value has already been marked seen, then the method sleeps until a new message is sent by the Sender connected to this Receiver, or until the Sender is dropped.

This method returns an error if and only if the Sender is dropped.

Cancel safety

This method is cancel safe. If you use it as the event in a tokio::select! statement and some other branch completes first, then it is guaranteed that no values have been marked seen by this call to changed.

Examples
use tokio::sync::watch;

#[tokio::main]
async fn main() {
    let (tx, mut rx) = watch::channel("hello");

    tokio::spawn(async move {
        tx.send("goodbye").unwrap();
    });

    assert!(rx.changed().await.is_ok());
    assert_eq!(*rx.borrow(), "goodbye");

    // The `tx` handle has been dropped
    assert!(rx.changed().await.is_err());
}
source

pub fn same_channel(&self, other: &Self) -> bool

Returns true if receivers belong to the same channel.

Examples
let (tx, rx) = tokio::sync::watch::channel(true);
let rx2 = rx.clone();
assert!(rx.same_channel(&rx2));

let (tx3, rx3) = tokio::sync::watch::channel(true);
assert!(!rx3.same_channel(&rx2));

Trait Implementations§

source§

impl<T> Clone for Receiver<T>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl<T: Debug> Debug for Receiver<T>

source§

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

Formats the value using the given formatter. Read more
source§

impl<T> Drop for Receiver<T>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<T> !RefUnwindSafe for Receiver<T>

§

impl<T> Send for Receiver<T>where T: Send + Sync,

§

impl<T> Sync for Receiver<T>where T: Send + Sync,

§

impl<T> Unpin for Receiver<T>

§

impl<T> !UnwindSafe for Receiver<T>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.