1#![allow(
2 clippy::cognitive_complexity,
3 clippy::large_enum_variant,
4 clippy::needless_doctest_main
5)]
6#![warn(
7 missing_debug_implementations,
8 missing_docs,
9 rust_2018_idioms,
10 unreachable_pub
11)]
12#![cfg_attr(docsrs, feature(doc_cfg))]
13#![doc(test(
14 no_crate_inject,
15 attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
16))]
17
18//! Stream utilities for Tokio.
19//!
20//! A `Stream` is an asynchronous sequence of values. It can be thought of as
21//! an asynchronous version of the standard library's `Iterator` trait.
22//!
23//! This crate provides helpers to work with them. For examples of usage and a more in-depth
24//! description of streams you can also refer to the [streams
25//! tutorial](https://tokio.rs/tokio/tutorial/streams) on the tokio website.
26//!
27//! # Iterating over a Stream
28//!
29//! Due to similarities with the standard library's `Iterator` trait, some new
30//! users may assume that they can use `for in` syntax to iterate over a
31//! `Stream`, but this is unfortunately not possible. Instead, you can use a
32//! `while let` loop as follows:
33//!
34//! ```rust
35//! use tokio_stream::{self as stream, StreamExt};
36//!
37//! #[tokio::main]
38//! async fn main() {
39//! let mut stream = stream::iter(vec![0, 1, 2]);
40//!
41//! while let Some(value) = stream.next().await {
42//! println!("Got {}", value);
43//! }
44//! }
45//! ```
46//!
47//! # Returning a Stream from a function
48//!
49//! A common way to stream values from a function is to pass in the sender
50//! half of a channel and use the receiver as the stream. This requires awaiting
51//! both futures to ensure progress is made. Another alternative is the
52//! [async-stream] crate, which contains macros that provide a `yield` keyword
53//! and allow you to return an `impl Stream`.
54//!
55//! [async-stream]: https://docs.rs/async-stream
56//!
57//! # Conversion to and from AsyncRead/AsyncWrite
58//!
59//! It is often desirable to convert a `Stream` into an [`AsyncRead`],
60//! especially when dealing with plaintext formats streamed over the network.
61//! The opposite conversion from an [`AsyncRead`] into a `Stream` is also
62//! another commonly required feature. To enable these conversions,
63//! [`tokio-util`] provides the [`StreamReader`] and [`ReaderStream`]
64//! types when the io feature is enabled.
65//!
66//! [`tokio-util`]: https://docs.rs/tokio-util/latest/tokio_util/codec/index.html
67//! [`tokio::io`]: https://docs.rs/tokio/latest/tokio/io/index.html
68//! [`AsyncRead`]: https://docs.rs/tokio/latest/tokio/io/trait.AsyncRead.html
69//! [`AsyncWrite`]: https://docs.rs/tokio/latest/tokio/io/trait.AsyncWrite.html
70//! [`ReaderStream`]: https://docs.rs/tokio-util/latest/tokio_util/io/struct.ReaderStream.html
71//! [`StreamReader`]: https://docs.rs/tokio-util/latest/tokio_util/io/struct.StreamReader.html
72
73#[macro_use]
74mod macros;
75
76pub mod wrappers;
77
78mod stream_ext;
79pub use stream_ext::{collect::FromStream, StreamExt};
80cfg_time! {
81 pub use stream_ext::timeout::{Elapsed, Timeout};
82}
83
84mod empty;
85pub use empty::{empty, Empty};
86
87mod iter;
88pub use iter::{iter, Iter};
89
90mod once;
91pub use once::{once, Once};
92
93mod pending;
94pub use pending::{pending, Pending};
95
96mod stream_map;
97pub use stream_map::StreamMap;
98
99mod stream_close;
100pub use stream_close::StreamNotifyClose;
101
102#[doc(no_inline)]
103pub use futures_core::Stream;
104