feat: Add a way to reserve many permits on bounded mpsc channel

[Totodore]

Motivation

I am in a situation where I need to be able to efficiently reserve n permit from the same mpsc::bounded channel. Because the Semaphore API already implement the possibility to reserve n permit. It is quite easy to propagate this API to the mpsc::bounded API. More details on this need can be found on the corresponding issue :

• Fixes Add a way to request many permits on a mpsc::channel #6174

Solution

In order to avoid any API breaking change rather than adding a u32 field on the current Permit struct I added :

• a ManyPermit struct
• a reserve_many(n: u32) fn on the Sender struct
• a try_reserve_many(n: u32) fn on the Sender struct

[Totodore]

The scope of this PR has evolved a bit.
The internal batch_semaphore has been changed to take a usize permit count rather than a u32 permit count so that there is no conversion from usize to u32 because it might overflow.

[Darksonn]

I think this looks reasonable. However, we will need some tests as well. Here are the tests that come to mind:

• A test that just uses it to send n messages, then receives n messages. (You can wrap it in a for loop to try different values of n.)
• A test that acquires n permits, sends k messages, and then drops the iterator. The capacity should be correct at the end. (Again with a for loop for a few differen t values of n and k.)
• Test that you get a SendError in the right cases.
• Test edge-cases, e.g. what happens if n == 0 or n == MAX_PERMITS or n == usize::MAX?

[Darksonn]

This looks good to me. I came up with one minor improvement, but overall I think this is ready to be merged.

[Totodore]

Ready to merge :).

[Darksonn]

Thanks!