sync::watch: Add has_changed flag and method to Ref

tokio/src/sync/watch.rs

@@ -112,6 +112,20 @@ pub struct Sender<T> {
 #[derive(Debug)]
 pub struct Ref<'a, T> {
     inner: RwLockReadGuard<'a, T>,
+    updated: bool,
+}
+
+impl<'a, T> Ref<'a, T> {
+    /// Indicates if the shared value has been detected as _changed_
+    /// **and** marked as seen.
+    ///
+    /// The result is `true` only if this reference has been obtained
+    /// from [`Receiver::borrow_and_update()`] in case changes have been
+    /// detected and marked as seen. In all other cases the result will
+    /// be `false`.
+    pub fn updated(&self) -> bool {
+        self.updated
+    }
 }
 
 #[derive(Debug)]
@@ -332,15 +346,17 @@ impl<T> Receiver<T> {
     /// ```
     pub fn borrow(&self) -> Ref<'_, T> {
         let inner = self.shared.value.read().unwrap();
-        Ref { inner }
+        // Changes are neither detected nor marked as seen by this function
+        let updated = false;
+        Ref { inner, updated }
     }
 
-    /// Returns a reference to the most recently sent value and mark that value
+    /// Returns a reference to the most recently sent value and marks that value
     /// as seen.
     ///
-    /// This method marks the value as seen, so [`changed`] will not return
-    /// immediately if the newest value is one previously returned by
-    /// `borrow_and_update`.
+    /// This method marks the current value as seen as indicated by [`Ref::updated`].
+    /// Subsequent calls to [`changed`] will not return immediately until the
+    /// [`Sender`] has modified the shared value again.
     ///
     /// Outstanding borrows hold a read lock. This means that long lived borrows
     /// could cause the send half to block. It is recommended to keep the borrow
@@ -366,8 +382,16 @@ impl<T> Receiver<T> {
     /// [`changed`]: Receiver::changed
     pub fn borrow_and_update(&mut self) -> Ref<'_, T> {
         let inner = self.shared.value.read().unwrap();
-        self.version = self.shared.state.load().version();
-        Ref { inner }
+        // After obtaining a read-lock no concurrent writes could occur
+        // and the loaded version matches that of the borrowed reference.
+        let new_version = self.shared.state.load().version();
+        let updated = if self.version != new_version {
+            self.version = new_version;
+            true
+        } else {
+            false
+        };
+        Ref { inner, updated }
     }
 
     /// Checks if this channel contains a message that this receiver has not yet
@@ -725,7 +749,9 @@ impl<T> Sender<T> {
     /// ```
     pub fn borrow(&self) -> Ref<'_, T> {
         let inner = self.shared.value.read().unwrap();
-        Ref { inner }
+        // The sender/producer always sees the current value
+        let updated = false;
+        Ref { inner, updated }
     }
 
     /// Checks if the channel has been closed. This happens when all receivers