futures_concurrency_dynamic/
lib.rs

1//! Dynamic merge combinator built on top of futures-util's SelectAll.
2//!
3//! This crate provides a wrapper around `futures_util::stream::SelectAll` that adds
4//! dynamic stream management capabilities with a convenient API for adding and managing
5//! multiple streams at runtime.
6//!
7//! ## 1. Direct API with `DynamicMerge`
8//!
9//! Use `DynamicMerge` directly when you want a single object that owns both the stream
10//! and the ability to push new streams:
11//!
12//! ```rust
13//! use futures_concurrency_dynamic::DynamicMerge;
14//! use futures_util::stream::{self, StreamExt, SelectAll};
15//!
16//! # async fn example() {
17//! let mut merge: DynamicMerge<'_, i32> = SelectAll::new();
18//! merge.push(Box::pin(stream::iter(vec![1, 2, 3])));
19//! merge.push(Box::pin(stream::iter(vec![4, 5, 6])));
20//!
21//! while let Some(item) = merge.next().await {
22//!     println!("{}", item);
23//! }
24//! # }
25//! ```
26//!
27//! ## 2. Handle-based API with `dynamic_merge_with_handle`
28//!
29//! Use the handle-based API when you need separate mutable references to the stream
30//! and the push functionality. This is useful when different parts of your code need
31//! to own and mutate each component independently:
32//!
33//! ```rust
34//! use futures_concurrency_dynamic::dynamic_merge_with_handle;
35//! use futures_util::stream::{self, StreamExt};
36//!
37//! # async fn example() {
38//! let (mut stream, mut handle) = dynamic_merge_with_handle::<i32>();
39//!
40//! // One task can push streams
41//! let producer = tokio::spawn(async move {
42//!     handle.push(stream::iter(vec![1, 2, 3]));
43//!     handle.push(stream::iter(vec![4, 5, 6]));
44//! });
45//!
46//! // Another task can consume from the stream
47//! let consumer = tokio::spawn(async move {
48//!     while let Some(item) = stream.next().await {
49//!         println!("{}", item);
50//!     }
51//! });
52//!
53//! producer.await.unwrap();
54//! consumer.await.unwrap();
55//! # }
56//! ```
57//!
58//! ## Implementation Note
59//!
60//! This crate is built on top of `futures_util::stream::SelectAll`, providing a more
61//! ergonomic API while leveraging the proven implementation from the futures ecosystem.
62//! All streams must be `Send + 'static`. If you need to work with borrowed streams,
63//! consider using `futures_util::stream::SelectAll` directly.
64
65pub mod dynamic_merge;
66pub mod handle;
67
68pub use dynamic_merge::DynamicMerge;
69pub use handle::{dynamic_merge_with_handle, DynamicMergeHandle, DynamicMergeStream};
futures_concurrency_dynamic/lib.rs

futures_concurrency_dynamic/
lib.rs
