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