tokio_stream/
lib.rs

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]
75mod macros;
76
77pub mod wrappers;
78
79mod stream_ext;
80pub use stream_ext::{collect::FromStream, StreamExt};
81/// Adapters for [`Stream`]s created by methods in [`StreamExt`].
82pub 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
92cfg_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
99mod empty;
100pub use empty::{empty, Empty};
101
102mod iter;
103pub use iter::{iter, Iter};
104
105mod once;
106pub use once::{once, Once};
107
108mod pending;
109pub use pending::{pending, Pending};
110
111mod stream_map;
112pub use stream_map::StreamMap;
113
114mod stream_close;
115pub use stream_close::StreamNotifyClose;
116
117#[doc(no_inline)]
118pub use futures_core::Stream;
tokio_stream/lib.rs

tokio_stream/
lib.rs
