sync: rename watch::mark_unseen to watch::mark_changed (#6014)

tokio/src/sync/watch.rs

@@ -380,7 +380,7 @@ mod state {
     impl Version {
         /// Get the initial version when creating the channel.
         pub(super) fn initial() -> Self {
-            // The initial version is 1 so that `mark_unseen` can decrement by one.
+            // The initial version is 1 so that `mark_changed` can decrement by one.
             // (The value is 2 due to the closed bit.)
             Version(2)
         }
@@ -644,8 +644,15 @@ impl<T> Receiver<T> {
         Ok(self.version != new_version)
     }
 
-    /// Marks the state as unseen.
-    pub fn mark_unseen(&mut self) {
+    /// Marks the state as changed.
+    ///
+    /// After invoking this method [`has_changed()`](Self::has_changed)
+    /// returns `true` and [`changed()`](Self::changed) returns
+    /// immediately, regardless of whether a new value has been sent.
+    ///
+    /// This is useful for triggering an initial change notification after
+    /// subscribing to synchronize new receivers.
+    pub fn mark_changed(&mut self) {
         self.version.decrement();
     }
 

tokio/tests/sync_watch.rs

@@ -49,19 +49,19 @@ fn rx_version_underflow() {
     let (_tx, mut rx) = watch::channel("one");
 
     // Version starts at 2, validate we do not underflow
-    rx.mark_unseen();
-    rx.mark_unseen();
+    rx.mark_changed();
+    rx.mark_changed();
 }
 
 #[test]
-fn rx_mark_unseen() {
+fn rx_mark_changed() {
     let (tx, mut rx) = watch::channel("one");
 
     let mut rx2 = rx.clone();
     let mut rx3 = rx.clone();
     let mut rx4 = rx.clone();
     {
-        rx.mark_unseen();
+        rx.mark_changed();
         assert!(rx.has_changed().unwrap());
 
         let mut t = spawn(rx.changed());
@@ -76,7 +76,7 @@ fn rx_mark_unseen() {
     }
 
     {
-        rx3.mark_unseen();
+        rx3.mark_changed();
         assert_eq!(*rx3.borrow(), "one");
 
         assert!(rx3.has_changed().unwrap());
@@ -94,7 +94,7 @@ fn rx_mark_unseen() {
         assert!(rx4.has_changed().unwrap());
         assert_eq!(*rx4.borrow_and_update(), "two");
 
-        rx4.mark_unseen();
+        rx4.mark_changed();
         assert!(rx4.has_changed().unwrap());
         assert_eq!(*rx4.borrow_and_update(), "two")
     }