From c5861ef62fb0c1ed6bb8fe07a8e02534264eb7b8 Mon Sep 17 00:00:00 2001 From: Lucio Franco Date: Thu, 17 Dec 2020 11:46:09 -0500 Subject: [PATCH] docs: Add more comprehensive stream docs (#3286) * docs: Add more comprehensive stream docs * Apply suggestions from code review Co-authored-by: Alice Ryhl * Fix doc tests Co-authored-by: Alice Ryhl --- tokio/src/lib.rs | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs index 5cfefce76..c65fa64f1 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -411,7 +411,38 @@ mod util; /// release, most of the Tokio stream utilities have been moved into the [`tokio-stream`] /// crate. /// +/// # Why was `Stream` no included in Tokio 1.0? +/// +/// Originally, we had planned to ship Tokio 1.0 with a stable `Stream` type +/// but unfortunetly the [RFC] had not been merged in time for `Stream` to +/// reach `std` on a stable compiler in time for the 1.0 release of Tokio. For +/// this reason, the team has decided to move all `Stream` based utilities to +/// the [`tokio-stream`] crate. While this is not ideal, once `Stream` has made +/// it into the standard library and the MSRV period has passed, we will implement +/// stream for our different types. +/// +/// While this may seem unfortunate, not all is lost as you can get much of the +/// `Stream` support with `async/await` and `while let` loops. It is also possible +/// to create a `impl Stream` from `async fn` using the [`async-stream`] crate. +/// /// [`tokio-stream`]: https://docs.rs/tokio-stream +/// [RFC]: https://github.com/rust-lang/rfcs/pull/2996 +/// +/// # Example +/// +/// Convert a [`sync::mpsc::Receiver`] to an `impl Stream`. +/// +/// ```rust,no_run +/// use tokio::sync::mpsc; +/// +/// let (tx, mut rx) = mpsc::channel::(16); +/// +/// let stream = async_stream::stream! { +/// while let Some(item) = rx.recv().await { +/// yield item; +/// } +/// }; +/// ``` pub mod stream {} cfg_macros! {