sync: add Receiver::poll_recv(..) method

[cratelyn]

this commit adds a rx.poll_recv(cx) method to the public interface of tokio::sync::oneshot::Receiver<T>.

this method has the following signature:

// tokio/src/sync/oneshot.rs
impl<T> Receiver<T> {
    pub fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Result<T, RecvError>> {
        // ...
    }
}

this is similar to the tokio::sync::mpsc::Receiver::poll_recv and tokio::sync::mpsc::UnboundedReceiver::poll_recv methods, which have the following signature:

// tokio/src/sync/mpsc/bounded.rs
impl<T> Receiver<T> {
    pub fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Option<T>> {
        // ...
    }
}

see:

• https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Receiver.html#method.poll_recv
• https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.UnboundedReceiver.html#method.poll_recv

in particular, note the &mut self receiver of these methods, as opposed to the Pin<&mut Self> receiver in Future::poll(..). today, a oneshot receiver must be pinned in order to be polled via Future::poll(..).

tokio::sync::oneshot::Receiver::try_recv(..) has an important but subtle difference from poll_recv(..), alluded to in its documentation:

If a pending value exists in the channel, it is returned. If no value
has been sent, the current task will not be registered for future
notification.

This function is useful to call from outside the context of an
asynchronous task.

see hyperium/http-body#100 for an example use-case for this.

if we are in the context of an asynchronous task, we may wish to poll on the receiver-end of the channel and register for future notification, indicating that we should be awoken later when a value is ready or when conditions yielding a spurious failure have passed.

providing a means to poll a &mut Receiver<T> avoids the performance impact of boxing the receiver as an erased dyn Future trait object, or of using an tokio::sync::mpsc::Receiver<T>, or the ergonomic wrinkles of needing to rely on pin projection in asynchronous types that compose on top of oneshot channels.

---

• https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Receiver.html#method.poll_recv
• https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.UnboundedReceiver.html#method.poll_recv
• https://doc.rust-lang.org/stable/std/future/trait.Future.html#tymethod.poll
• https://docs.rs/tokio/latest/tokio/sync/oneshot/struct.Receiver.html#method.try_recv
• https://github.com/hyperium/http-body/pull/100/files#r1399818104
• util: add a channel body hyperium/http-body#100

Motivation

Solution

[seanmonstar]

If Receiver is Unpin, then it should be easy to wrap the borrow in a Pin and just call Future::poll. Is that not possible?

[cratelyn]

i'll close this. a receiver can be pinned, as described above. while there isn't any strict need for it to be pinned, i'm not especially attached to this proposal.