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