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 #![cfg_attr(docsrs, deny(broken_intra_doc_links))] 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/0.4/tokio_util/codec/index.html 68 //! [`tokio::io`]: https://docs.rs/tokio/1.0/tokio/io/index.html 69 //! [`AsyncRead`]: https://docs.rs/tokio/1.0/tokio/io/trait.AsyncRead.html 70 //! [`AsyncWrite`]: https://docs.rs/tokio/1.0/tokio/io/trait.AsyncWrite.html 71 //! [`ReaderStream`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.ReaderStream.html 72 //! [`StreamReader`]: https://docs.rs/tokio-util/0.4/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 82 mod empty; 83 pub use empty::{empty, Empty}; 84 85 mod iter; 86 pub use iter::{iter, Iter}; 87 88 mod once; 89 pub use once::{once, Once}; 90 91 mod pending; 92 pub use pending::{pending, Pending}; 93 94 mod stream_map; 95 pub use stream_map::StreamMap; 96 97 #[doc(no_inline)] 98 pub use futures_core::Stream; 99