tokio: add mpsc::Receiver::max_capacity and mpsc::Receiver::capacity

[mbrobbel]

Motivation

mpsc::Sender has max_capacity and capacity methods, however mpsc::Receiver does not. It may help to have these methods when trying to pre-allocate for Receiver::recv_many.

Solution

Adds Receiver::max_capacity and Receiver::capacity.

[Darksonn]

We already have an Receiver::len method. It was added in #6348.

[mbrobbel]

We already have an Receiver::len method. It was added in #6348.

This is supposed to be an addition to that: capacity = max_capacity - len.

[Darksonn]

Hmm, this is not actually equal to max_capacity - len. Generally, sending a message goes through this procedure:

1. Acquire a permit for the message.
2. Write the message into the channel's storage.
3. Make the message available to receivers.

With the len method, the length only changes in step 3, but with this method, the capacity already changes in step 1. If the user is using Permit to acquire permits before sending messages, then there may be a long amount of time between step 1 and step 2.

The documentation should clearly explain the difference.

[mbrobbel]

I've updated the example to explain the relation with Receiver::len. Is that sufficient?

[Darksonn]

Thank you.