sync: oneshot::Receiver::is_empty()

[cratelyn]

this commit introduces a new method to tokio::sync::oneshot::Receiver<T>.

this method returns true if the channel has no messages waiting to be received. this is similar to the existing tokio::sync::mpsc::Receiver::is_empty() and tokio::sync::broadcast::Receiver::is_empty() methods.

see:

• https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.is_empty
• https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Receiver.html#method.is_empty
• sync: oneshot::Receiver::{is_empty, is_closed} #7137 (comment)

[maminrayej]

If I understand correctly, it's not safe to poll the receiver even if is_empty returns true, since you can consume the message with try_recv and incorrectly try to poll the receiver later on. I wonder whether it's worth it to document this fact on the is_empty method and redirect users to is_terminated implemented in #7152.

[cratelyn]

If I understand correctly, it's not safe to poll the receiver even if is_empty returns true, since you can consume the message with try_recv and incorrectly try to poll the receiver later on. I wonder whether it's worth it to document this fact on the is_empty method and redirect users to is_terminated implemented in #7152.

that's right, and i agree that this would be a good signpost to provide in order to mitigate misuse and clarify purpose.

note that this branch is now based upon #7152, to reflect that the documentation of is_empty() now references an interface proposed in that pull request.

b7d1b3e introduces additional documentation and accompanying examples to help draw attention to what exactly "empty" means, semantically.

[cratelyn]

this branch has been rebased, now that the prerequisite #7152 has been merged.

[maminrayej]

Thanks.