itsscb/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2025-09-25 12:00:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

sync: improve the docs of sync::watch (#7601)

Browse Source 
Co-authored-by: Alice Ryhl <aliceryhl@google.com>
This commit is contained in:
Martin Grigorov 2025-09-15 14:56:29 +03:00 committed by GitHub
parent 32a1acc85f
commit 5f3f5b0be4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 10 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
tokio/src/sync/mod.rs
View File

@ -278,8 +278,8 @@
//! //!
//! ## `watch` channel //! ## `watch` channel
//! //!
//! The [`watch` channel] supports sending **many** values from a **many** //! The [`watch` channel] supports sending **many** values from **many**
//! producer to **many** consumers. However, only the **most recent** value is //! 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 //! stored in the channel. Consumers are notified when a new value is sent, but
//! there is no guarantee that consumers will see **all** values. //! there is no guarantee that consumers will see **all** values.
//! //!

16
tokio/src/sync/watch.rs
View File

@ -30,7 +30,7 @@
//! method is ready when a new, *unseen* value is sent via the [`Sender`] half. //! method is ready when a new, *unseen* value is sent via the [`Sender`] half.
//! //!
//! * [`Receiver::changed()`] returns `Ok(())` on receiving a new value, or //! * [`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 //! * If the current value is *unseen* when calling [`changed`], then
//! [`changed`] will return immediately. If the current value is *seen*, 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, //! 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 //! 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. //! 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. //! receivers have been dropped.
//! //!
//! # Thread safety //! # Thread safety
@ -391,7 +391,7 @@ mod state {
/// Snapshot of the state. The first bit is used as the CLOSED bit. /// Snapshot of the state. The first bit is used as the CLOSED bit.
/// The remaining bits are used as the version. /// 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. /// receivers does not set it.
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
pub(super) struct StateSnapshot(usize); pub(super) struct StateSnapshot(usize);
@ -670,7 +670,7 @@ impl<T> Receiver<T> {
// Load the version from the state // Load the version from the state
let state = self.shared.state.load(); let state = self.shared.state.load();
if state.is_closed() { if state.is_closed() {
// The sender has dropped. // All senders have dropped.
return Err(error::RecvError(())); return Err(error::RecvError(()));
} }
let new_version = state.version(); let new_version = state.version();
@ -706,10 +706,10 @@ impl<T> Receiver<T> {
/// If the newest value in the channel has not yet been marked seen when /// 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 /// this method is called, the method marks that value seen and returns
/// immediately. If the newest value has already been marked seen, then the /// 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 /// method sleeps until a new message is sent by a [`Sender`] connected to
/// this `Receiver`, or until the [`Sender`] is dropped. /// 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 /// For more information, see
/// [*Change notifications*](self#change-notifications) in the module-level documentation. /// [*Change notifications*](self#change-notifications) in the module-level documentation.
@ -901,7 +901,7 @@ fn maybe_changed<T>(
} }
if state.is_closed() { if state.is_closed() {
// The sender has been dropped. // All senders have been dropped.
return Some(Err(error::RecvError(()))); return Some(Err(error::RecvError(())));
} }