Circumstances may exist where multiple messages are queued for the
receiver by the time the receiving task runs -- and the receiving
task itself may benefit from batch as opposed to item-by-item
processing, e.g., update a row based on a primary key but
only the most recent update is needed; recv_many
enables the receiver to process messages last-first
and skip earlier updates for rows already updated.

The change involved introducing a peek function to sync/mpsc/list.rs;
it is based on fn pop.  fn recv_many returns Poll<Vec<T>> contrasting
recv's Poll<Option<T>>.  The new function returns
Ready(vec![]) where recv returned Ready(None).

The mpsc.rs trait Semaphore was extended with two functions,
num_acquired() and add_permits(n) -- which are used to size
the vector and update the underlying semaphores in a single
call.

Simple tests were added to tests/sync_mpsc.rs.

The implementation uses a passed-in buffer to return results.
The buffer is always cleared, and its capacity may be
increased to match the number of queued messages.
This avoids excessive memory allocation.

This commit also adds new benchmarks in benches/sync_mpsc_recv_many.rs
It borrows substantially from benches/sync_mpsc.rs

The benchmarks are framed around the idea that only the last value
is needed, e.g., what might be typical in a dashboard.

The following benchmarks compare extracting the last value from
5_000 recv's vs. a variable number of recv_many:
  contention_bounded_updater_recv vs.  contention_bounded_updater_recv_many
  contention_bounded_full_updater_recv vs.  contention_bounded_full_updater_recv_many
  contention_unbounded_updater_recv vs. contention_unbounded_updater_recv_many
  uncontented_bounded_updater_recv vs.  uncontented_bounded_updater_recv_many
  uncontented_unbounded_updater_recv vs.  uncontented_unbounded_updater_recv_many

Initial tests suggests a ~30% performance improvement for the
uncontented tests.

The benchmarks contention_bounded_updater_publish_recv and
contention_bounded_updater_publish_recv_many are different;
first the number of messages recevied are only 1_000.
In these test, we contemplate an actor who needs to receive a message
and forward it over an API that takes 1ns to complete.
An actor accepting a single message-at-a-time
will hit the 1ns lag repeatedly; the actor that can pick only
the last message out of the buffer from recv_many has much less work.

Previous benchmarks in sync_mpsc_recv_many.rs included a
contrived example that is removed.

Removed methods num_acquired and peek; allow caller to control
the number of retrieved elements by setting the capacity of the
result buffer.  In the event the result buffer has no capacity,
the capacity is set to BLOCK_CAP.  Added examples to the
documentation.

Also, update test async_send_recv_many_with_buffer to test that
buffer capacity is not increased by recv_many.

This commit changes the behavior of recv_many
to no longer clear the supplied buffer on each call.
Now, recv_many will append new messages to the end of
the supplied buffer until it reaches capacity.  The
return value is the number of new messages added to
the buffer.
This may be useful for a caller who expects a fixed number
of messages and wishes to avoid copying.
At the time of the call, recv_many now asserts that
the capacity of the buffer exceeds its length (fail-fast).
The caller must appropriately clear/resize the buffer between
calls if it is to be reused.
The method recv_many no longer changes the capacity of the
supplied buffer.

Unit and doc and doc tests were updated to test and document
the new behavior.

Implements approach of Darksonn, where the buffer is extended
when the capacity is equal to the length at the time of the call
to recv_many.

Co-authored-by: Alice Ryhl <[email protected]>

Co-authored-by: Alice Ryhl <[email protected]>

The documentation is changed to better highlight the limited
circumstance in which `recv_many` may return 0,
'..will never return 0 unless...'.
Two new tests are somewhat analogous to the doctests were added:
  - send_recv_many_bounded_capacity()
  - send_recv_many_unbounded_capacity()
These ensure that for buffers that have not reached their
capacity a call to `recv_many` only fills up to the capacity
leaving other messages still queued. A subsequent
call on a filled buffer would reserve additional elements.  The test
also looks at pending messages holding the channel open --
compared to the doctest example which showcases non-dropped
senders.

Co-authored-by: Alice Ryhl <[email protected]>

Co-authored-by: Alice Ryhl <[email protected]>

Positive values of `limit` set the maximum number of elements
that can be added to `buffer` in a single call.
A zero value of `limit` sets the maximum number of elements
that can be added to a default value, currently `super::BLOCK_CAP`.

Returning 0 immediately when limit=0 is consistent with
the current take(0) behavior.  Tests were updated.

Co-authored-by: Alice Ryhl <[email protected]>

Co-authored-by: Alice Ryhl <[email protected]>

Co-authored-by: Alice Ryhl <[email protected]>