From 804511822b4be12a958d01fe1156b0a71bc8e6f7 Mon Sep 17 00:00:00 2001
From: Uwe Klotz <uwe.klotz@slowtec.de>
Date: Tue, 19 Sep 2023 15:13:46 +0200
Subject: [PATCH] sync: rename `watch::mark_unseen` to `watch::mark_changed`
 (#6014)

---
 tokio/src/sync/watch.rs   | 13 ++++++++++---
 tokio/tests/sync_watch.rs | 12 ++++++------
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs
index 0452a81aa0a..2b4fd561e96 100644
--- a/tokio/src/sync/watch.rs
+++ b/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();
     }
 
diff --git a/tokio/tests/sync_watch.rs b/tokio/tests/sync_watch.rs
index 5bcb7476888..70cc110b937 100644
--- a/tokio/tests/sync_watch.rs
+++ b/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")
     }