stream: provide `StreamMap` utility (#2185)

`StreamMap` is similar to `StreamExt::merge` in that it combines source
streams into a single merged stream that yields values in the order that
they arrive from the source streams. However, `StreamMap` has a lot more
flexibility in usage patterns.

`StreamMap` can:

- Merge an arbitrary number of streams.
- Track which source stream the value was received from.
- Handle inserting and removing streams from the set of managed streams
  at any point during iteration.

All source streams held by `StreamMap` are indexed using a key. This key
is included with the value when a source stream yields a value. The key
is also used to remove the stream from the `StreamMap` before the stream
has completed streaming.

Because the `StreamMap` API moves streams during runtime, both streams
and keys must be `Unpin`. In order to insert a `!Unpin` stream into a
`StreamMap`, use `pin!` to pin the stream to the stack or `Box::pin` to
pin the stream in the heap.

1 files changed, 3 insertions, 0 deletions

diff --git a/tokio/src/stream/mod.rs b/tokio/src/stream/mod.rs
index 82771eee..3cc7e68f 100644
--- a/tokio/src/stream/mod.rs
+++ b/tokio/src/stream/mod.rs
@@ -50,6 +50,9 @@ pub use once::{once, Once};
 mod pending;
 pub use pending::{pending, Pending};
 
+mod stream_map;
+pub use stream_map::StreamMap;
+
 mod try_next;
 use try_next::TryNext;