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/0.4/tokio_util/codec/index.html 67 //! [`tokio::io`]: https://docs.rs/tokio/1.0/tokio/io/index.html 68 //! [`AsyncRead`]: https://docs.rs/tokio/1.0/tokio/io/trait.AsyncRead.html 69 //! [`AsyncWrite`]: https://docs.rs/tokio/1.0/tokio/io/trait.AsyncWrite.html 70 //! [`ReaderStream`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.ReaderStream.html 71 //! [`StreamReader`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.StreamReader.html 72 73 #[macro_use] 74 mod macros; 75 76 pub mod wrappers; 77 78 mod stream_ext; 79 pub use stream_ext::{collect::FromStream, StreamExt}; 80 cfg_time! { 81 pub use stream_ext::timeout::{Elapsed, Timeout}; 82 } 83 84 mod empty; 85 pub use empty::{empty, Empty}; 86 87 mod iter; 88 pub use iter::{iter, Iter}; 89 90 mod once; 91 pub use once::{once, Once}; 92 93 mod pending; 94 pub use pending::{pending, Pending}; 95 96 mod stream_map; 97 pub use stream_map::StreamMap; 98 99 #[doc(no_inline)] 100 pub use futures_core::Stream; 101