feat: Add poll_recv_many for Receiver & UnboundedReceiver

[Owen-CH-Leung]

fixes #6209

Add a new API poll_recv_many for Receiver & UnboundedReceiver

Motivation

Further to the implementation of recv_many, it is suggested to also add similar functionality for the API poll_recv. Hence, a new API poll_recv_many is created

Solution

This PR adds a new API poll_recv_many into Receiver & UnboundedReceiver. An example is also added for reference

[Darksonn]

Here is the documentation for poll_recv. I was hoping to see an explanation of what it does in the same style as this.

    /// Polls to receive the next message on this channel.
    ///
    /// This method returns:
    ///
    ///  * `Poll::Pending` if no messages are available but the channel is not
    ///    closed, or if a spurious failure happens.
    ///  * `Poll::Ready(Some(message))` if a message is available.
    ///  * `Poll::Ready(None)` if the channel has been closed and all messages
    ///    sent before it was closed have been received.
    ///
    /// When the method returns `Poll::Pending`, the `Waker` in the provided
    /// `Context` is scheduled to receive a wakeup when a message is sent on any
    /// receiver, or when the channel is closed.  Note that on multiple calls to
    /// `poll_recv`, only the `Waker` from the `Context` passed to the most
    /// recent call is scheduled to receive a wakeup.
    ///
    /// If this method returns `Poll::Pending` due to a spurious failure, then
    /// the `Waker` will be notified when the situation causing the spurious
    /// failure has been resolved. Note that receiving such a wakeup does not
    /// guarantee that the next call will succeed — it could fail with another
    /// spurious failure.
    pub fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Option<T>> {
        self.chan.recv(cx)
    }

[Owen-CH-Leung]

Here is the documentation for poll_recv. I was hoping to see an explanation of what it does in the same style as this.

    /// Polls to receive the next message on this channel.
    ///
    /// This method returns:
    ///
    ///  * `Poll::Pending` if no messages are available but the channel is not
    ///    closed, or if a spurious failure happens.
    ///  * `Poll::Ready(Some(message))` if a message is available.
    ///  * `Poll::Ready(None)` if the channel has been closed and all messages
    ///    sent before it was closed have been received.
    ///
    /// When the method returns `Poll::Pending`, the `Waker` in the provided
    /// `Context` is scheduled to receive a wakeup when a message is sent on any
    /// receiver, or when the channel is closed.  Note that on multiple calls to
    /// `poll_recv`, only the `Waker` from the `Context` passed to the most
    /// recent call is scheduled to receive a wakeup.
    ///
    /// If this method returns `Poll::Pending` due to a spurious failure, then
    /// the `Waker` will be notified when the situation causing the spurious
    /// failure has been resolved. Note that receiving such a wakeup does not
    /// guarantee that the next call will succeed — it could fail with another
    /// spurious failure.
    pub fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Option<T>> {
        self.chan.recv(cx)
    }

@Darksonn Thanks for your feedback! I've revised the documentation to be more detailed & clear on what this API does. Could you review again ? Thanks

[Darksonn]

The part about the waker should be moved below this list, similar to poll_recv.

[Owen-CH-Leung]

Thanks & I've included your suggestions in my latest commit

[Darksonn]

I would split this into two cases: Poll::Ready(count) for count > 0 and Poll::Ready(0). The length-zero case is special because it only happens when the channel is closed (or n == 0).

[Owen-CH-Leung]

Yup that will be much clearer. I've split it into 2

[Darksonn]

These two paragraphs can probably just be deleted. As long as the list below is comprehensive, this isn't necessary, and it is obvious that it is similar to poll_recv and recv_many.

[Owen-CH-Leung]

Sure & deleted

[Darksonn]

The English used here is rather complicated. Perhaps we could simplify it like this?

Suggested change

	/// Note that this method does not guarantee that the buffer will be filled up to `limit` on each call,
	/// especially if fewer messages are available. Also, the actual number of messages received can be
	/// zero if the channel is empty or closed.
	/// Note that this method does not guarantee that exactly `limit` messages
	/// are received. Rather, if at least one message is available, it returns
	/// as many messages as it can up to the given limit. This method returns
	/// zero only if the channel is closed (or if `limit` is zero).

[Owen-CH-Leung]

Thanks & I've adopted your suggestion

[Darksonn]

Only one changed I'd like left, then I think this is ready to be merged.

[Darksonn]

Please use the same wording as on poll_recv. That's a standardized wording taking from Future::poll, and we use the same wording on all poll functions with a note of this kind.

Suggested change

	/// When the method returns `Poll::Pending`, the `Waker` from the `Context` is scheduled
	/// to be woken up when new messages are sent on the channel or when the channel is closed.
	/// When the method returns `Poll::Pending`, the `Waker` in the provided
	/// `Context` is scheduled to receive a wakeup when a message is sent on any
	/// receiver, or when the channel is closed. Note that on multiple calls to
	/// `poll_recv` or `poll_recv_many`, only the `Waker` from the `Context`
	/// passed to the most recent call is scheduled to receive a wakeup.

Please also update the documentation of poll_recv to say "poll_recv or poll_recv_many" like how I did here.

[Owen-CH-Leung]

@Darksonn Thanks a lot. I've revised accordingly.

[Darksonn]

Thank you.