Documentation of watch::Sender implies that channel is closed forever when all receivers are dropped

[JanBeh]

Version
1.20.1

Platform
FreeBSD titanium 13.1-RELEASE-p1 FreeBSD 13.1-RELEASE-p1 GENERIC amd64

Description
Documentation of tokio::sync::watch::Sender says:

This method fails if the channel has been closed, which happens when every receiver has been dropped.

This may be interpreted 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 following code demonstrates:

fn main() {
    let (sender, receiver) = tokio::sync::watch::channel(());
    drop(receiver);
    assert!(sender.send(()).is_err());
    let _receiver = sender.subscribe();
    assert!(sender.send(()).is_ok());
}

Perhaps it would be better if it read something like:

This method fails if all receivers have been dropped and no new receiver for the sender has been created.

[Darksonn]

Well, if you want to be precise, your suggestion implies that it cannot ever be closed once a sender has been created.

[JanBeh]

Well, if you want to be precise, your suggestion implies that it cannot ever be closed once a sender has been created.

Whether it can be closed or not depends on the meaning of the word, I would say. You may say it can be "closed", but then it can be "reopened".

My problem is that it's unclear how "the channel has been closed" is to be interpreted in English. It could be interpreted as "the channel was closed at some point in past" or as "the channel has been closed and is still in closed state". It's somewhat ambiguous due to different possible interpretations of the perfect tense, I would say.

Hence I would suggest clarifying it.

[Darksonn]

I mean, I agree that we should clarify it.

[JanBeh]

Perhaps it should also be clarified what "failing" means (i.e. just returning Err or also failing to update the value). Currently the value doesn't get updated (see this comment to #4958). I would prefer if the Sender stored the value for future subscribers. In either case, the behavior could be better documented.