diff --git a/src/async.rs b/src/async.rs index 727cc64..4b02e2a 100644 --- a/src/async.rs +++ b/src/async.rs @@ -342,6 +342,8 @@ impl<'a, T> Clone for SendSink<'a, T> { impl Receiver { /// Asynchronously receive a value from the channel, returning an error if all senders have been /// dropped. If the channel is empty, the returned future will yield to the async runtime. + /// + /// See [`RecvFut`] for how dropping the returned future affects other receivers. pub fn recv_async(&self) -> RecvFut<'_, T> { RecvFut::new(OwnedOrRef::Ref(self)) } @@ -349,6 +351,8 @@ impl Receiver { /// Convert this receiver into a future that asynchronously receives a single message from the /// channel, returning an error if all senders have been dropped. If the channel is empty, this /// future will yield to the async runtime. + /// + /// See [`RecvFut`] for how dropping the returned future affects other receivers. pub fn into_recv_async<'a>(self) -> RecvFut<'a, T> { RecvFut::new(OwnedOrRef::Owned(self)) } @@ -368,6 +372,14 @@ impl Receiver { /// A future which allows asynchronously receiving a message. /// /// Can be created via [`Receiver::recv_async`] or [`Receiver::into_recv_async`]. +/// +/// # Wakeups +/// +/// Dropping this future after the channel has woken it, whether it completed or you +/// cancelled it, passes the wakeup on to the other waiting receivers in queue order +/// while the channel is non-empty, stopping after the first [`RecvStream`]. This keeps +/// the future cancel safe. With many receivers on one channel, it can cause a burst of +/// spurious wakeups. #[must_use = "futures/streams/sinks do nothing unless you `.await` or poll them"] pub struct RecvFut<'a, T> { receiver: OwnedOrRef<'a, Receiver>,