Struct tokio::sync::watch::Ref

source ·
pub struct Ref<'a, T> { /* private fields */ }
Expand description

Returns a reference to the inner value.

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();   |

Implementations§

source§

impl<'a, T> Ref<'a, T>

source

pub fn has_changed(&self) -> bool

Indicates if the borrowed value is considered as changed since the last time it has been marked as seen.

Unlike Receiver::has_changed(), this method does not fail if the channel is closed.

When borrowed from the Sender this function will always return false.

Examples
use tokio::sync::watch;

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

    tx.send("goodbye").unwrap();
    // The sender does never consider the value as changed.
    assert!(!tx.borrow().has_changed());

    // Drop the sender immediately, just for testing purposes.
    drop(tx);

    // Even if the sender has already been dropped...
    assert!(rx.has_changed().is_err());
    // ...the modified value is still readable and detected as changed.
    assert_eq!(*rx.borrow(), "goodbye");
    assert!(rx.borrow().has_changed());

    // Read the changed value and mark it as seen.
    {
        let received = rx.borrow_and_update();
        assert_eq!(*received, "goodbye");
        assert!(received.has_changed());
        // Release the read lock when leaving this scope.
    }

    // Now the value has already been marked as seen and could
    // never be modified again (after the sender has been dropped).
    assert!(!rx.borrow().has_changed());
}

Trait Implementations§

source§

impl<'a, T: Debug> Debug for Ref<'a, T>

source§

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

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

impl<T> Deref for Ref<'_, T>

§

type Target = T

The resulting type after dereferencing.
source§

fn deref(&self) -> &T

Dereferences the value.

Auto Trait Implementations§

§

impl<'a, T> !RefUnwindSafe for Ref<'a, T>

§

impl<'a, T> !Send for Ref<'a, T>

§

impl<'a, T> Sync for Ref<'a, T>where T: Send + Sync,

§

impl<'a, T> Unpin for Ref<'a, T>

§

impl<'a, T> !UnwindSafe for Ref<'a, 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, 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.