From 431ec68f93401fbca3c2976edc0fb6e55530cbc3 Mon Sep 17 00:00:00 2001 From: Jan Behrens <76393822+JanBeh@users.noreply.github.com> Date: Thu, 1 Sep 2022 21:11:01 +0200 Subject: [PATCH] sync: doc of `watch::Sender::send` improved (#4959) Current documentation of `sync::watch::Sender::send` may be intepreted as the method failing if at some point in past the channel has been closed because every receiver has been dropped. This isn't true, however, as the channel could have been reopened by using `sync::watch::Sender::subscribe`. This fix clarifies the behavior. Moreover, it is noted that on failure, the value isn't made available to future subscribers (but returned as part of the `SendError`). Fixes #4957. --- tokio/src/sync/watch.rs | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs index ce47685a6..fba49224f 100644 --- a/tokio/src/sync/watch.rs +++ b/tokio/src/sync/watch.rs @@ -604,8 +604,22 @@ impl Drop for Receiver { impl Sender { /// Sends a new value via the channel, notifying all receivers. /// - /// This method fails if the channel has been closed, which happens when - /// every receiver has been dropped. + /// This method fails if the channel is closed, which is the case when + /// every receiver has been dropped. It is possible to reopen the channel + /// using the [`subscribe`] method. However, when `send` fails, the value + /// isn't made available for future receivers (but returned with the + /// [`SendError`]). + /// + /// To always make a new value available for future receivers, even if no + /// receiver currently exists, one of the other send methods + /// ([`send_if_modified`], [`send_modify`], or [`send_replace`]) can be + /// used instead. + /// + /// [`subscribe`]: Sender::subscribe + /// [`SendError`]: error::SendError + /// [`send_if_modified`]: Sender::send_if_modified + /// [`send_modify`]: Sender::send_modify + /// [`send_replace`]: Sender::send_replace pub fn send(&self, value: T) -> Result<(), error::SendError> { // This is pretty much only useful as a hint anyway, so synchronization isn't critical. if 0 == self.receiver_count() {