sync: clarify the behavior of mpsc::Receiver::recv_many()

[ADD-SP]

Closes #7540

[Darksonn]

I'm not sure this table is the right way to explain this.

Here's the way I think of the method:

• It returns messages in exactly the same scenarios as recv.
• But when it returns one message, it will check if more messages are available in that instant, and return those too.

Perhaps we could say that recv_many is a more efficient version of this:

async fn recv_many(&mut self, buffer: &mut Vec<T>, limit: usize) -> usize {
    if limit == 0 {
        return 0;
    }

    // Wait for at least one message (or channel close).
    let Some(first_message) = self.recv().await else {
        return 0;
    };

    buffer.push(first_message);
    let mut num_pushed = 1;

    // Try to get more messages, but don't sleep.
    while num_pushed < limit {
        if let Some(msg) = self.try_recv() {
            buffer.push(msg);
            num_pushed += 1;
        } else {
            break;
        }
    }

    num_pushed
}

[ADD-SP]

I'm not sure this table is the right way to explain this.

Here's the way I think of the method:

* It returns messages in _exactly_ the same scenarios as `recv`.

* But when it returns one message, it will check if more messages are available _in that instant_, and return those too.

Perhaps we could say that recv_many is a more efficient version of this:

async fn recv_many(&mut self, buffer: &mut Vec<T>, limit: usize) -> usize {
    if limit == 0 {
        return 0;
    }

    // Wait for at least one message (or channel close).
    let Some(first_message) = self.recv().await else {
        return 0;
    };

    buffer.push(first_message);
    let mut num_pushed = 1;

    // Try to get more messages, but don't sleep.
    while num_pushed < limit {
        if let Some(msg) = self.try_recv() {
            buffer.push(msg);
            num_pushed += 1;
        } else {
            break;
        }
    }

    num_pushed
}

@Darksonn I believe this is a better way, let me try to shorten this code snippet, and then update the PR.

[ADD-SP]

I'm not sure this table is the right way to explain this.
Here's the way I think of the method:

* It returns messages in _exactly_ the same scenarios as `recv`.

* But when it returns one message, it will check if more messages are available _in that instant_, and return those too.

Perhaps we could say that recv_many is a more efficient version of this:

async fn recv_many(&mut self, buffer: &mut Vec<T>, limit: usize) -> usize {
    if limit == 0 {
        return 0;
    }

    // Wait for at least one message (or channel close).
    let Some(first_message) = self.recv().await else {
        return 0;
    };

    buffer.push(first_message);
    let mut num_pushed = 1;

    // Try to get more messages, but don't sleep.
    while num_pushed < limit {
        if let Some(msg) = self.try_recv() {
            buffer.push(msg);
            num_pushed += 1;
        } else {
            break;
        }
    }

    num_pushed
}

@Darksonn I believe this is a better way, let me try to shorten this code snippet, and then update the PR.

I think this is already the shortest version, so I just simple copy the above code.

[Darksonn]

I think we should still have some text saying that receives "at least one message".

[ADD-SP]

This PR duplicates #7201, I've asked the author to see if they are still going to work on it.

[ADD-SP]

Closed this PR, see #7201 (comment).