From 5f3f5b0be4ec933aed2290ea9d929b5daadae321 Mon Sep 17 00:00:00 2001 From: Martin Grigorov Date: Mon, 15 Sep 2025 14:56:29 +0300 Subject: [PATCH] sync: improve the docs of `sync::watch` (#7601) Co-authored-by: Alice Ryhl --- tokio/src/sync/mod.rs | 4 ++-- tokio/src/sync/watch.rs | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/tokio/src/sync/mod.rs b/tokio/src/sync/mod.rs index 20eef09f1..d6d17c3f3 100644 --- a/tokio/src/sync/mod.rs +++ b/tokio/src/sync/mod.rs @@ -278,8 +278,8 @@ //! //! ## `watch` channel //! -//! The [`watch` channel] supports sending **many** values from a **many** -//! producer to **many** consumers. However, only the **most recent** value is +//! The [`watch` channel] supports sending **many** values from **many** +//! producers to **many** consumers. However, only the **most recent** value is //! stored in the channel. Consumers are notified when a new value is sent, but //! there is no guarantee that consumers will see **all** values. //! diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs index 884efffa3..868d0aa5e 100644 --- a/tokio/src/sync/watch.rs +++ b/tokio/src/sync/watch.rs @@ -30,7 +30,7 @@ //! method is ready when a new, *unseen* value is sent via the [`Sender`] half. //! //! * [`Receiver::changed()`] returns `Ok(())` on receiving a new value, or -//! `Err(`[`error::RecvError`]`)` if the [`Sender`] has been dropped. +//! `Err(`[`error::RecvError`]`)` if all [`Sender`]s have been dropped. //! * If the current value is *unseen* when calling [`changed`], then //! [`changed`] will return immediately. If the current value is *seen*, then //! it will sleep until either a new message is sent via the [`Sender`] half, @@ -90,7 +90,7 @@ //! when all [`Receiver`] handles have been dropped. This indicates that there //! is no further interest in the values being produced and work can be stopped. //! -//! The value in the channel will not be dropped until the sender and all +//! The value in the channel will not be dropped until all senders and all //! receivers have been dropped. //! //! # Thread safety @@ -391,7 +391,7 @@ mod state { /// Snapshot of the state. The first bit is used as the CLOSED bit. /// The remaining bits are used as the version. /// - /// The CLOSED bit tracks whether the Sender has been dropped. Dropping all + /// The CLOSED bit tracks whether all senders have been dropped. Dropping all /// receivers does not set it. #[derive(Copy, Clone, Debug)] pub(super) struct StateSnapshot(usize); @@ -670,7 +670,7 @@ impl Receiver { // Load the version from the state let state = self.shared.state.load(); if state.is_closed() { - // The sender has dropped. + // All senders have dropped. return Err(error::RecvError(())); } let new_version = state.version(); @@ -706,10 +706,10 @@ impl Receiver { /// 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. + /// method sleeps until a new message is sent by a [`Sender`] connected to + /// this `Receiver`, or until all [`Sender`]s are dropped. /// - /// This method returns an error if and only if the [`Sender`] is dropped. + /// This method returns an error if and only if all [`Sender`]s are dropped. /// /// For more information, see /// [*Change notifications*](self#change-notifications) in the module-level documentation. @@ -901,7 +901,7 @@ fn maybe_changed( } if state.is_closed() { - // The sender has been dropped. + // All senders have been dropped. return Some(Err(error::RecvError(()))); }