chore: prepare tokio v1.2.0 (#3506)

The time driver stores an Instant internally used as a "base" for future
time calculations. Since this is generated as the Runtime is being
constructed, it previously always happened before the user had a chance
to pause time. The fractional-millisecond variations in the timing
around the runtime construction and time pause cause tests running
entirely in paused time to be very slightly deterministic, with the time
driver advancing time by 1 millisecond more or less depending on how the
sub-millisecond components of the `Instant`s involved compared.

To avoid this, there is now a new option on `runtime::Builder` which
will create a `Runtime` with time "instantly" paused. This, along with a
small change to have the time driver use the provided clock as the
source for its start time allow totally deterministic tests with paused
time.

.cirrus.yml

@@ -21,9 +21,9 @@ task:
       rustc --version
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --all
+    - cargo test --all --all-features
     - cargo doc --all --no-deps
   i686_test_script:
     - . $HOME/.cargo/env
     - |
-      cargo test --all --target i686-unknown-freebsd
+      cargo test --all --all-features --target i686-unknown-freebsd

.github/ISSUE_TEMPLATE/bug_report.md

@@ -9,12 +9,7 @@ assignees: ''
 
 **Version**
 List the versions of all `tokio` crates you are using. The easiest way to get
-this information is using `cargo-tree`.
-
-`cargo install cargo-tree`
-(see install here: https://github.com/sfackler/cargo-tree)
-
-Then:
+this information is using `cargo tree` subcommand:
 
 `cargo tree | grep tokio`
 

.github/workflows/ci.yml

@@ -1,8 +1,8 @@
 on:
   push:
-    branches: ["master"]
+    branches: ["master", "tokio-*.x"]
   pull_request:
-    branches: ["master"]
+    branches: ["master", "tokio-*.x"]
 
 name: CI
 
@@ -28,6 +28,7 @@ jobs:
       - clippy
       - docs
       - loom
+      - valgrind
     steps:
       - run: exit 0
 
@@ -67,6 +68,28 @@ jobs:
         run: cargo hack test --each-feature
         working-directory: tests-build
 
+  valgrind:
+    name: valgrind
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update stable
+
+      - name: Install Valgrind
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y valgrind
+
+      # Compile tests
+      - name: cargo build
+        run: cargo build --features rt-net --bin test-mem
+        working-directory: tests-integration
+
+      # Run with valgrind
+      - name: Run valgrind
+        run: valgrind  --leak-check=full --show-leak-kinds=all ./target/debug/test-mem
+
   test-unstable:
     name: test tokio full --unstable
     runs-on: ${{ matrix.os }}
@@ -232,7 +255,7 @@ jobs:
 
       # Run clippy
       - name: "clippy --all"
-        run: cargo clippy --all --tests
+        run: cargo clippy --all --tests --all-features
 
   docs:
     name: docs

.github/workflows/stress-test.yml

@@ -19,7 +19,9 @@ jobs:
         run: rustup update stable
 
       - name: Install Valgrind
-        run: sudo apt-get install -y valgrind
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y valgrind
 
       # Compiles each of the stress test examples.
       - name: Compile stress test examples

CONTRIBUTING.md

@@ -427,11 +427,14 @@ _Adapted from the [Node.js contributing guide][node]_.
 
 ## Keeping track of issues and PRs
 
-The Tokio GitHub repository has a lot of issues and PRs, which is not easy to
-keep track of. This section explains the meaning of various labels, as well as
-our [GitHub project][project]. The section is primarily targeted at maintainers.
+The Tokio GitHub repository has a lot of issues and PRs to keep track of. This
+section explains the meaning of various labels, as well as our [GitHub
+project][project]. The section is primarily targeted at maintainers.  Most
+contributors aren't able to set these labels.
 
-**Area.** The area label describes the crates relevant to this issue or PR.
+### Area
+
+The area label describes the crates relevant to this issue or PR.
 
  - **A-tokio** This issue concerns the main Tokio crate.
  - **A-tokio-util** This issue concerns the `tokio-util` crate.
@@ -442,7 +445,7 @@ our [GitHub project][project]. The section is primarily targeted at maintainers.
    be used for the procedural macros, and not `join!` or `select!`.
  - **A-ci** This issue concerns our GitHub Actions setup.
 
-**Category.** The category label describes the category.
+### Category
 
  - **C-bug** This is a bug-report. Bug-fix PRs use `C-enhancement` instead.
  - **C-enhancement** This is a PR that adds a new features.
@@ -460,8 +463,7 @@ our [GitHub project][project]. The section is primarily targeted at maintainers.
  - **C-request** A non-feature request, e.g. "please add deprecation notices to
    `-alpha.*` versions of crates"
 
-**Call for participation.** I don't know why it's called `E-`. Many issues are
-missing a difficulty rating, and you should feel free to add one.
+### Calls for participation
 
  - **E-help-wanted** Stuff where we want help. Often seen together with `C-bug`
    or `C-feature-accepted`.
@@ -473,7 +475,13 @@ missing a difficulty rating, and you should feel free to add one.
  - **E-needs-mvce** This bug is missing a minimal complete and verifiable
    example.
 
-**Module.** A more fine groaned categorization than area.
+The "E-" prefix is the same as used in the Rust compiler repository. Some
+issues are missing a difficulty rating, but feel free to ask on our Discord
+server if you want to know how difficult an issue likely is.
+
+### Module
+
+The module label provides a more fine grained categorization than **Area**.
 
  - **M-blocking** Things relevant to `spawn_blocking`, `block_in_place`.
  - **M-codec** The `tokio_util::codec` module.
@@ -486,13 +494,14 @@ missing a difficulty rating, and you should feel free to add one.
  - **M-process** The `tokio::process` module.
  - **M-runtime** The `tokio::runtime` module.
  - **M-signal** The `tokio::signal` module.
- - **M-stream** The `tokio::stream` module.
  - **M-sync** The `tokio::sync` module.
  - **M-task** The `tokio::task` module.
  - **M-time** The `tokio::time` module.
  - **M-tracing** Tracing support in Tokio.
 
-**Topic.** Some extra information.
+### Topic
+
+Some extra information.
 
  - **T-docs** This is about documentation.
  - **T-performance** This is about performance.
@@ -502,6 +511,34 @@ Any label not listed here is not in active use.
 
 [project]: https://github.com/orgs/tokio-rs/projects/1
 
+## LTS guarantees
+
+Tokio ≥1.0.0 comes with LTS guarantees:
+
+ * A minimum of 5 years of maintenance.
+ * A minimum of 3 years before a hypothetical 2.0 release.
+
+The goal of these guarantees is to provide stability to the ecosystem.
+
+## Mininum Supported Rust Version (MSRV)
+
+ * All Tokio ≥1.0.0 releases will support at least a 6-month old Rust
+   compiler release.
+ * The MSRV will only be increased on 1.x releases.
+
+## Versioning Policy
+
+With Tokio ≥1.0.0:
+
+ * Patch (1.\_.x) releases _should only_ contain bug fixes or documentation
+   changes. Besides this, these releases should not substantially change
+   runtime behavior.
+ * Minor (1.x) releases may contain new functionality, MSRV increases (see
+   above), minor dependency updates, deprecations, and larger internal
+   implementation changes.
+
+This is as defined by [Semantic Versioning 2.0](https://semver.org/).
+
 ## Releasing
 
 Since the Tokio project consists of a number of crates, many of which depend on

Cargo.toml

@@ -4,6 +4,7 @@ members = [
   "tokio",
   "tokio-macros",
   "tokio-test",
+  "tokio-stream",
   "tokio-util",
 
   # Internal

README.md

@@ -29,7 +29,6 @@ the Rust programming language. It is:
 [Website](https://tokio.rs) |
 [Guides](https://tokio.rs/tokio/tutorial) |
 [API Docs](https://docs.rs/tokio/latest/tokio) |
-[Roadmap](https://github.com/tokio-rs/tokio/blob/master/ROADMAP.md) |
 [Chat](https://discord.gg/tokio)
 
 ## Overview
@@ -55,7 +54,7 @@ A basic TCP echo server with Tokio:
 
 ```rust,no_run
 use tokio::net::TcpListener;
-use tokio::prelude::*;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {

ROADMAP.md

@@ -1,67 +0,0 @@
-# Tokio Roadmap
-
-## A Roadmap to 1.0
-
-The question of "why not 1.0?" has come up a few times. After all, Tokio 0.1 has
-been stable for three years. The short answer: because it isn't time. There is
-nobody who would rather ship a Tokio 1.0 than us. It also isn't something to rush.
-
-After all, `async / await` only landed in the stable Rust channel weeks ago.
-There has been no significant production validation yet, except maybe fuchsia
-and that seems like a fairly specialized use case. This release of Tokio
-includes significant new code and new strategies with feature flags. Also, there
-are still big open questions, such as the [proposed changes][pr-1744] to
-`AsyncRead` and `AsyncWrite`.
-
-Tokio 1.0 will be released as soon as the APIs are proven to handle real-world
-production cases.
-
-### Tokio 1.0 in Q3 2020 with LTS support
-
-The Tokio 1.0 release will be **no later** than Q3 2020. It will also come with
-"long-term support" guarantees:
-
-* A minimum of 5 years of maintenance.
-* A minimum of 3 years before a hypothetical 2.0 release.
-
-When Tokio 1.0 is released in Q3 2020, on-going support, security fixes, and
-critical bug fixes are guaranteed until **at least** Q3 2025. Tokio 2.0 will not
-be released until **at least** Q3 2023 (though, ideally there will never be a
-Tokio 2.0 release).
-
-### How to get there
-
-While Tokio 0.1 probably should have been a 1.0, Tokio 0.2 will be a **true**
-0.2 release. There will be breaking change releases every 2 ~ 3 months until 1.0.
-These changes will be **much** smaller than going from 0.1 -> 0.2. It is
-expected that the 1.0 release will look a lot like 0.2.
-
-### What is expected to change
-
-The biggest change will be the `AsyncRead` and `AsyncWrite` traits. Based on
-experience gained over the past 3 years, there are a couple of issues to
-address:
-
-* Be able to **safely** use uninitialized memory as a read buffer.
-* Practical read vectored and write vectored APIs.
-
-There are a few strategies to solve these problems. These strategies need to be
-investigated and the solution validated. You can see [this comment][pr-1744-comment] for a
-detailed statement of the problem.
-
-The other major change, which has been in the works for a while, is updating
-Mio. Mio 0.6 was first released almost 4 years ago and has not had a breaking
-change since. Mio 0.7 has been in the works for a while. It includes a full
-rewrite of the windows support as well as a refined API. More will be written
-about this shortly.
-
-Finally, now that the API is starting to stabilize, effort will be put into
-documentation. Tokio 0.2 is being released before updating the website and many
-of the old content will no longer be relevant. In the coming weeks, expect to
-see updates there.
-
-So, we have our work cut out for us. We hope you enjoy this 0.2 release and are
-looking forward to your feedback and help.
-
-[pr-1744]: https://github.com/tokio-rs/tokio/pull/1744
-[pr-1744-comment]: https://github.com/tokio-rs/tokio/pull/1744#issuecomment-553575438

benches/Cargo.toml

@@ -5,7 +5,7 @@ publish = false
 edition = "2018"
 
 [dependencies]
-tokio = { version = "0.3.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
 bencher = "0.1.5"
 
 [target.'cfg(unix)'.dependencies]

benches/sync_mpsc.rs

@@ -30,22 +30,26 @@ fn create_100_000_medium(b: &mut Bencher) {
 }
 
 fn send_medium(b: &mut Bencher) {
+    let rt = rt();
+
     b.iter(|| {
         let (tx, mut rx) = mpsc::channel::<Medium>(1000);
 
-        let _ = tx.try_send([0; 64]);
+        let _ = rt.block_on(tx.send([0; 64]));
 
-        rx.try_recv().unwrap();
+        rt.block_on(rx.recv()).unwrap();
     });
 }
 
 fn send_large(b: &mut Bencher) {
+    let rt = rt();
+
     b.iter(|| {
         let (tx, mut rx) = mpsc::channel::<Large>(1000);
 
-        let _ = tx.try_send([[0; 64]; 64]);
+        let _ = rt.block_on(tx.send([[0; 64]; 64]));
 
-        rx.try_recv().unwrap();
+        rt.block_on(rx.recv()).unwrap();
     });
 }
 

examples/Cargo.toml

@@ -7,18 +7,23 @@ edition = "2018"
 # If you copy one of the examples into a new project, you should be using
 # [dependencies] instead.
 [dev-dependencies]
-tokio = { version = "0.3.0", path = "../tokio", features = ["full", "tracing"] }
+tokio = { version = "1.0.0", features = ["full", "tracing"] }
+tokio-util = { version = "0.6.3", features = ["full"] }
+tokio-stream = { version = "0.1" }
+
+async-stream = "0.3"
 tracing = "0.1"
 tracing-subscriber = { version = "0.2.7", default-features = false, features = ["fmt", "ansi", "env-filter", "chrono", "tracing-log"] }
-tokio-util = { version = "0.5.0", path = "../tokio-util", features = ["full"] }
-bytes = "0.6"
-futures = "0.3.0"
+bytes = "1.0.0"
+futures = { version = "0.3.0", features = ["thread-pool"]}
 http = "0.2"
 serde = "1.0"
 serde_derive = "1.0"
 serde_json = "1.0"
 httparse = "1.0"
 time = "0.1"
+once_cell = "1.5.2"
+
 
 [[example]]
 name = "chat"
@@ -63,3 +68,12 @@ path = "udp-codec.rs"
 [[example]]
 name = "tinyhttp"
 path = "tinyhttp.rs"
+
+[[example]]
+name = "custom-executor"
+path = "custom-executor.rs"
+
+
+[[example]]
+name = "custom-executor-tokio-context"
+path = "custom-executor-tokio-context.rs"

examples/chat.rs

@@ -27,8 +27,8 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::{TcpListener, TcpStream};
-use tokio::stream::{Stream, StreamExt};
 use tokio::sync::{mpsc, Mutex};
+use tokio_stream::{Stream, StreamExt};
 use tokio_util::codec::{Framed, LinesCodec, LinesCodecError};
 
 use futures::SinkExt;
@@ -101,9 +101,6 @@ async fn main() -> Result<(), Box<dyn Error>> {
 /// Shorthand for the transmit half of the message channel.
 type Tx = mpsc::UnboundedSender<String>;
 
-/// Shorthand for the receive half of the message channel.
-type Rx = mpsc::UnboundedReceiver<String>;
-
 /// Data that is shared between all peers in the chat server.
 ///
 /// This is the set of `Tx` handles for all connected clients. Whenever a
@@ -127,7 +124,7 @@ struct Peer {
     ///
     /// This is used to receive messages from peers. When a message is received
     /// off of this `Rx`, it will be written to the socket.
-    rx: Rx,
+    rx: Pin<Box<dyn Stream<Item = String> + Send>>,
 }
 
 impl Shared {
@@ -159,11 +156,17 @@ impl Peer {
         let addr = lines.get_ref().peer_addr()?;
 
         // Create a channel for this peer
-        let (tx, rx) = mpsc::unbounded_channel();
+        let (tx, mut rx) = mpsc::unbounded_channel();
 
         // Add an entry for this `Peer` in the shared state map.
         state.lock().await.peers.insert(addr, tx);
 
+        let rx = Box::pin(async_stream::stream! {
+            while let Some(item) = rx.recv().await {
+                yield item;
+            }
+        });
+
         Ok(Peer { lines, rx })
     }
 }

examples/connect.rs

@@ -92,7 +92,7 @@ mod tcp {
 
 mod udp {
     use bytes::Bytes;
-    use futures::{future, Sink, SinkExt, Stream, StreamExt};
+    use futures::{Sink, SinkExt, Stream, StreamExt};
     use std::error::Error;
     use std::io;
     use std::net::SocketAddr;
@@ -114,7 +114,7 @@ mod udp {
         let socket = UdpSocket::bind(&bind_addr).await?;
         socket.connect(addr).await?;
 
-        future::try_join(send(stdin, &socket), recv(stdout, &socket)).await?;
+        tokio::try_join!(send(stdin, &socket), recv(stdout, &socket))?;
 
         Ok(())
     }

examples/custom-executor-tokio-context.rs

@@ -0,0 +1,32 @@
+// This example shows how to use the tokio runtime with any other executor
+//
+//It takes advantage from RuntimeExt which provides the extension to customize your
+//runtime.
+
+use tokio::net::TcpListener;
+use tokio::runtime::Builder;
+use tokio::sync::oneshot;
+use tokio_util::context::RuntimeExt;
+
+fn main() {
+    let (tx, rx) = oneshot::channel();
+    let rt1 = Builder::new_multi_thread()
+        .worker_threads(1)
+        // no timer!
+        .build()
+        .unwrap();
+    let rt2 = Builder::new_multi_thread()
+        .worker_threads(1)
+        .enable_all()
+        .build()
+        .unwrap();
+
+    // Without the `HandleExt.wrap()` there would be a panic because there is
+    // no timer running, since it would be referencing runtime r1.
+    let _ = rt1.block_on(rt2.wrap(async move {
+        let listener = TcpListener::bind("0.0.0.0:0").await.unwrap();
+        println!("addr: {:?}", listener.local_addr());
+        tx.send(()).unwrap();
+    }));
+    futures::executor::block_on(rx).unwrap();
+}

examples/custom-executor.rs

@@ -0,0 +1,56 @@
+// This example shows how to use the tokio runtime with any other executor
+//
+// The main components are a spawn fn that will wrap futures in a special future
+// that will always enter the tokio context on poll. This only spawns one extra thread
+// to manage and run the tokio drivers in the background.
+
+use tokio::net::TcpListener;
+use tokio::sync::oneshot;
+
+fn main() {
+    let (tx, rx) = oneshot::channel();
+
+    my_custom_runtime::spawn(async move {
+        let listener = TcpListener::bind("0.0.0.0:0").await.unwrap();
+
+        println!("addr: {:?}", listener.local_addr());
+
+        tx.send(()).unwrap();
+    });
+
+    futures::executor::block_on(rx).unwrap();
+}
+
+mod my_custom_runtime {
+    use once_cell::sync::Lazy;
+    use std::future::Future;
+    use tokio_util::context::TokioContext;
+
+    pub fn spawn(f: impl Future<Output = ()> + Send + 'static) {
+        EXECUTOR.spawn(f);
+    }
+
+    struct ThreadPool {
+        inner: futures::executor::ThreadPool,
+        rt: tokio::runtime::Runtime,
+    }
+
+    static EXECUTOR: Lazy<ThreadPool> = Lazy::new(|| {
+        // Spawn tokio runtime on a single background thread
+        // enabling IO and timers.
+        let rt = tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let inner = futures::executor::ThreadPool::builder().create().unwrap();
+
+        ThreadPool { inner, rt }
+    });
+
+    impl ThreadPool {
+        fn spawn(&self, f: impl Future<Output = ()> + Send + 'static) {
+            let handle = self.rt.handle().clone();
+            self.inner.spawn_ok(TokioContext::new(f, handle));
+        }
+    }
+}

examples/echo.rs

@@ -55,7 +55,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
         // which will allow all of our clients to be processed concurrently.
 
         tokio::spawn(async move {
-            let mut buf = [0; 1024];
+            let mut buf = vec![0; 1024];
 
             // In a loop, read data from the socket and write the data back.
             loop {

examples/print_each_packet.rs

@@ -55,7 +55,7 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::TcpListener;
-use tokio::stream::StreamExt;
+use tokio_stream::StreamExt;
 use tokio_util::codec::{BytesCodec, Decoder};
 
 use std::env;

examples/proxy.rs

@@ -26,7 +26,6 @@ use tokio::io;
 use tokio::io::AsyncWriteExt;
 use tokio::net::{TcpListener, TcpStream};
 
-use futures::future::try_join;
 use futures::FutureExt;
 use std::env;
 use std::error::Error;
@@ -74,7 +73,7 @@ async fn transfer(mut inbound: TcpStream, proxy_addr: String) -> Result<(), Box<
         wi.shutdown().await
     };
 
-    try_join(client_to_server, server_to_client).await?;
+    tokio::try_join!(client_to_server, server_to_client)?;
 
     Ok(())
 }

examples/tinydb.rs

@@ -42,7 +42,7 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::TcpListener;
-use tokio::stream::StreamExt;
+use tokio_stream::StreamExt;
 use tokio_util::codec::{Framed, LinesCodec};
 
 use futures::SinkExt;

examples/tinyhttp.rs

@@ -20,7 +20,7 @@ use http::{header::HeaderValue, Request, Response, StatusCode};
 extern crate serde_derive;
 use std::{env, error::Error, fmt, io};
 use tokio::net::{TcpListener, TcpStream};
-use tokio::stream::StreamExt;
+use tokio_stream::StreamExt;
 use tokio_util::codec::{Decoder, Encoder, Framed};
 
 #[tokio::main]

examples/udp-codec.rs

@@ -9,8 +9,8 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::UdpSocket;
-use tokio::stream::StreamExt;
 use tokio::{io, time};
+use tokio_stream::StreamExt;
 use tokio_util::codec::BytesCodec;
 use tokio_util::udp::UdpFramed;
 
@@ -45,7 +45,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     let b = pong(&mut b);
 
     // Run both futures simultaneously of `a` and `b` sending messages back and forth.
-    match futures::future::try_join(a, b).await {
+    match tokio::try_join!(a, b) {
         Err(e) => println!("an error occurred; error = {:?}", e),
         _ => println!("done!"),
     }

stress-test/Cargo.toml

@@ -8,7 +8,7 @@ publish = false
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-tokio = {path = "../tokio/", features = ["full"]}
+tokio = { path = "../tokio/", features = ["full"] }
 
 [dev-dependencies]
-rand = "0.7.3"
+rand = "0.8"

tests-build/tests/fail/macros_invalid_input.stderr

@@ -4,7 +4,7 @@ error: the async keyword is missing from the function declaration
 4 | fn main_is_not_async() {}
   | ^^
 
-error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`
+error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`, `start_paused`
  --> $DIR/macros_invalid_input.rs:6:15
   |
 6 | #[tokio::main(foo)]
@@ -28,7 +28,7 @@ error: the test function cannot accept arguments
 16 | async fn test_fn_has_args(_x: u8) {}
    |                           ^^^^^^
 
-error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`
+error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`, `start_paused`
   --> $DIR/macros_invalid_input.rs:18:15
    |
 18 | #[tokio::test(foo)]

tests-integration/Cargo.toml

@@ -5,7 +5,17 @@ authors = ["Tokio Contributors <[email protected]>"]
 edition = "2018"
 publish = false
 
+[[bin]]
+name = "test-cat"
+
+[[bin]]
+name = "test-mem"
+required-features = ["rt-net"]
+
 [features]
+# For mem check
+rt-net = ["tokio/rt", "tokio/rt-multi-thread", "tokio/net"]
+
 full = [
     "macros",
     "rt",
@@ -23,6 +33,4 @@ rt-multi-thread = ["rt", "tokio/rt-multi-thread"]
 tokio = { path = "../tokio" }
 tokio-test = { path = "../tokio-test", optional = true }
 doc-comment = "0.3.1"
-
-[dev-dependencies]
 futures = { version = "0.3.0", features = ["async-await"] }

tests-integration/src/bin/test-mem.rs

@@ -0,0 +1,21 @@
+use futures::future::poll_fn;
+
+fn main() {
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(1)
+        .enable_io()
+        .build()
+        .unwrap();
+
+    rt.block_on(async {
+        let listener = tokio::net::TcpListener::bind("0.0.0.0:0").await.unwrap();
+        tokio::spawn(async move {
+            loop {
+                poll_fn(|cx| listener.poll_accept(cx)).await.unwrap();
+            }
+        });
+    });
+
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    drop(rt);
+}

tests-integration/tests/process_stdio.rs

@@ -1,26 +1,19 @@
 #![warn(rust_2018_idioms)]
 #![cfg(feature = "full")]
 
-use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
+use tokio::join;
 use tokio::process::{Child, Command};
 use tokio_test::assert_ok;
 
 use futures::future::{self, FutureExt};
+use std::convert::TryInto;
 use std::env;
 use std::io;
 use std::process::{ExitStatus, Stdio};
 
 fn cat() -> Command {
-    let mut me = env::current_exe().unwrap();
-    me.pop();
-
-    if me.ends_with("deps") {
-        me.pop();
-    }
-
-    me.push("test-cat");
-
-    let mut cmd = Command::new(me);
+    let mut cmd = Command::new(env!("CARGO_BIN_EXE_test-cat"));
     cmd.stdin(Stdio::piped()).stdout(Stdio::piped());
     cmd
 }
@@ -148,3 +141,52 @@ async fn try_wait() {
     // Can't get id after process has exited
     assert_eq!(child.id(), None);
 }
+
+#[tokio::test]
+async fn pipe_from_one_command_to_another() {
+    let mut first = cat().spawn().expect("first cmd");
+    let mut third = cat().spawn().expect("third cmd");
+
+    // Convert ChildStdout to Stdio
+    let second_stdin: Stdio = first
+        .stdout
+        .take()
+        .expect("first.stdout")
+        .try_into()
+        .expect("first.stdout into Stdio");
+
+    // Convert ChildStdin to Stdio
+    let second_stdout: Stdio = third
+        .stdin
+        .take()
+        .expect("third.stdin")
+        .try_into()
+        .expect("third.stdin into Stdio");
+
+    let mut second = cat()
+        .stdin(second_stdin)
+        .stdout(second_stdout)
+        .spawn()
+        .expect("first cmd");
+
+    let msg = "hello world! please pipe this message through";
+
+    let mut stdin = first.stdin.take().expect("first.stdin");
+    let write = async move { stdin.write_all(msg.as_bytes()).await };
+
+    let mut stdout = third.stdout.take().expect("third.stdout");
+    let read = async move {
+        let mut data = String::new();
+        stdout.read_to_string(&mut data).await.map(|_| data)
+    };
+
+    let (read, write, first_status, second_status, third_status) =
+        join!(read, write, first.wait(), second.wait(), third.wait());
+
+    assert_eq!(msg, read.expect("read result"));
+    write.expect("write result");
+
+    assert!(first_status.expect("first status").success());
+    assert!(second_status.expect("second status").success());
+    assert!(third_status.expect("third status").success());
+}

tokio-macros/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 1.1.0 (February 5, 2021)
+
+- add `start_paused` option to macros ([#3492])
+
+# 1.0.0 (December 23, 2020)
+
+- track `tokio` 1.0 release.
+
 # 0.3.1 (October 25, 2020)
 
 ### Fixed
@@ -51,3 +59,4 @@
 [#2177]: https://github.com/tokio-rs/tokio/pull/2177
 [#2225]: https://github.com/tokio-rs/tokio/pull/2225
 [#3038]: https://github.com/tokio-rs/tokio/pull/3038
+[#3492]: https://github.com/tokio-rs/tokio/pull/3492

tokio-macros/Cargo.toml

@@ -6,14 +6,14 @@ name = "tokio-macros"
 # - Update doc url
 #   - Cargo.toml
 # - Update CHANGELOG.md.
-# - Create "v0.3.x" git tag.
-version = "0.3.1"
+# - Create "tokio-macros-1.0.x" git tag.
+version = "1.1.0"
 edition = "2018"
 authors = ["Tokio Contributors <[email protected]>"]
 license = "MIT"
 repository = "https://github.com/tokio-rs/tokio"
 homepage = "https://tokio.rs"
-documentation = "https://docs.rs/tokio-macros/0.3.1/tokio_macros"
+documentation = "https://docs.rs/tokio-macros/1.1.0/tokio_macros"
 description = """
 Tokio's proc macros.
 """
@@ -30,7 +30,7 @@ quote = "1"
 syn = { version = "1.0.3", features = ["full"] }
 
 [dev-dependencies]
-tokio = { version = "0.3.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
 
 [package.metadata.docs.rs]
 all-features = true

tokio-macros/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Tokio Contributors
+Copyright (c) 2020 Tokio Contributors
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

tokio-macros/src/entry.rs

@@ -25,6 +25,7 @@ impl RuntimeFlavor {
 struct FinalConfig {
     flavor: RuntimeFlavor,
     worker_threads: Option<usize>,
+    start_paused: Option<bool>,
 }
 
 struct Configuration {
@@ -32,6 +33,7 @@ struct Configuration {
     default_flavor: RuntimeFlavor,
     flavor: Option<RuntimeFlavor>,
     worker_threads: Option<(usize, Span)>,
+    start_paused: Option<(bool, Span)>,
 }
 
 impl Configuration {
@@ -44,6 +46,7 @@ impl Configuration {
             },
             flavor: None,
             worker_threads: None,
+            start_paused: None,
         }
     }
 
@@ -79,31 +82,57 @@ impl Configuration {
         Ok(())
     }
 
+    fn set_start_paused(&mut self, start_paused: syn::Lit, span: Span) -> Result<(), syn::Error> {
+        if self.start_paused.is_some() {
+            return Err(syn::Error::new(span, "`start_paused` set multiple times."));
+        }
+
+        let start_paused = parse_bool(start_paused, span, "start_paused")?;
+        self.start_paused = Some((start_paused, span));
+        Ok(())
+    }
+
     fn build(&self) -> Result<FinalConfig, syn::Error> {
         let flavor = self.flavor.unwrap_or(self.default_flavor);
         use RuntimeFlavor::*;
-        match (flavor, self.worker_threads) {
-            (CurrentThread, Some((_, worker_threads_span))) => Err(syn::Error::new(
-                worker_threads_span,
-                "The `worker_threads` option requires the `multi_thread` runtime flavor.",
-            )),
-            (CurrentThread, None) => Ok(FinalConfig {
-                flavor,
-                worker_threads: None,
-            }),
-            (Threaded, worker_threads) if self.rt_multi_thread_available => Ok(FinalConfig {
-                flavor,
-                worker_threads: worker_threads.map(|(val, _span)| val),
-            }),
+
+        let worker_threads = match (flavor, self.worker_threads) {
+            (CurrentThread, Some((_, worker_threads_span))) => {
+                return Err(syn::Error::new(
+                    worker_threads_span,
+                    "The `worker_threads` option requires the `multi_thread` runtime flavor.",
+                ))
+            }
+            (CurrentThread, None) => None,
+            (Threaded, worker_threads) if self.rt_multi_thread_available => {
+                worker_threads.map(|(val, _span)| val)
+            }
             (Threaded, _) => {
                 let msg = if self.flavor.is_none() {
                     "The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled."
                 } else {
                     "The runtime flavor `multi_thread` requires the `rt-multi-thread` feature."
                 };
-                Err(syn::Error::new(Span::call_site(), msg))
+                return Err(syn::Error::new(Span::call_site(), msg));
             }
-        }
+        };
+
+        let start_paused = match (flavor, self.start_paused) {
+            (Threaded, Some((_, start_paused_span))) => {
+                return Err(syn::Error::new(
+                    start_paused_span,
+                    "The `start_paused` option requires the `current_thread` runtime flavor.",
+                ));
+            }
+            (CurrentThread, Some((start_paused, _))) => Some(start_paused),
+            (_, None) => None,
+        };
+
+        Ok(FinalConfig {
+            flavor,
+            worker_threads,
+            start_paused,
+        })
     }
 }
 
@@ -134,6 +163,16 @@ fn parse_string(int: syn::Lit, span: Span, field: &str) -> Result<String, syn::E
     }
 }
 
+fn parse_bool(bool: syn::Lit, span: Span, field: &str) -> Result<bool, syn::Error> {
+    match bool {
+        syn::Lit::Bool(b) => Ok(b.value),
+        _ => Err(syn::Error::new(
+            span,
+            format!("Failed to parse {} as bool.", field),
+        )),
+    }
+}
+
 fn parse_knobs(
     mut input: syn::ItemFn,
     args: syn::AttributeArgs,
@@ -174,6 +213,9 @@ fn parse_knobs(
                     "flavor" => {
                         config.set_flavor(namevalue.lit.clone(), namevalue.span())?;
                     }
+                    "start_paused" => {
+                        config.set_start_paused(namevalue.lit.clone(), namevalue.span())?;
+                    }
                     "core_threads" => {
                         let msg = "Attribute `core_threads` is renamed to `worker_threads`";
                         return Err(syn::Error::new_spanned(namevalue, msg));
@@ -204,11 +246,11 @@ fn parse_knobs(
                             macro_name
                         )
                     }
-                    "flavor" | "worker_threads" => {
+                    "flavor" | "worker_threads" | "start_paused" => {
                         format!("The `{}` attribute requires an argument.", name)
                     }
                     name => {
-                        format!("Unknown attribute {} is specified; expected one of: `flavor`, `worker_threads`", name)
+                        format!("Unknown attribute {} is specified; expected one of: `flavor`, `worker_threads`, `start_paused`", name)
                     }
                 };
                 return Err(syn::Error::new_spanned(path, msg));
@@ -235,6 +277,9 @@ fn parse_knobs(
     if let Some(v) = config.worker_threads {
         rt = quote! { #rt.worker_threads(#v) };
     }
+    if let Some(v) = config.start_paused {
+        rt = quote! { #rt.start_paused(#v) };
+    }
 
     let header = {
         if is_test {
@@ -254,7 +299,7 @@ fn parse_knobs(
                 .enable_all()
                 .build()
                 .unwrap()
-                .block_on(async { #body })
+                .block_on(async #body)
         }
     };
 

tokio-macros/src/lib.rs

@@ -1,4 +1,4 @@
-#![doc(html_root_url = "https://docs.rs/tokio-macros/0.3.1")]
+#![doc(html_root_url = "https://docs.rs/tokio-macros/1.1.0")]
 #![allow(clippy::needless_doctest_main)]
 #![warn(
     missing_debug_implementations,
@@ -24,8 +24,8 @@ mod select;
 
 use proc_macro::TokenStream;
 
-/// Marks async function to be executed by the selected runtime. This macro helps
-/// set up a `Runtime` without requiring the user to use
+/// Marks async function to be executed by the selected runtime. This macro
+/// helps set up a `Runtime` without requiring the user to use
 /// [Runtime](../tokio/runtime/struct.Runtime.html) or
 /// [Builder](../tokio/runtime/struct.Builder.html) directly.
 ///
@@ -36,10 +36,10 @@ use proc_macro::TokenStream;
 /// powerful interface.
 ///
 /// Note: This macro can be used on any function and not just the `main`
-/// function. Using it on a non-main function makes the function behave
-/// as if it was synchronous by starting a new runtime each time it is called.
-/// If the function is called often, it is preferable to create the runtime using
-/// the runtime builder so the runtime can be reused across calls.
+/// function. Using it on a non-main function makes the function behave as if it
+/// was synchronous by starting a new runtime each time it is called. If the
+/// function is called often, it is preferable to create the runtime using the
+/// runtime builder so the runtime can be reused across calls.
 ///
 /// # Multi-threaded runtime
 ///
@@ -53,6 +53,9 @@ use proc_macro::TokenStream;
 /// The `worker_threads` option configures the number of worker threads, and
 /// defaults to the number of cpus on the system. This is the default flavor.
 ///
+/// Note: The multi-threaded runtime requires the `rt-multi-thread` feature
+/// flag.
+///
 /// # Current thread runtime
 ///
 /// To use the single-threaded runtime known as the `current_thread` runtime,
@@ -141,12 +144,36 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
+/// ### Configure the runtime to start with time paused
+///
+/// ```rust
+/// #[tokio::main(flavor = "current_thread", start_paused = true)]
+/// async fn main() {
+///     println!("Hello world");
+/// }
+/// ```
+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```rust
+/// fn main() {
+///     tokio::runtime::Builder::new_current_thread()
+///         .enable_all()
+///         .start_paused(true)
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
 /// ### NOTE:
 ///
-/// If you rename the tokio crate in your dependencies this macro will not work.
-/// If you must rename the 0.3 version of tokio because you're also using the
-/// 0.1 version of tokio, you _must_ make the tokio 0.3 crate available as
-/// `tokio` in the module where this macro is expanded.
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
 #[cfg(not(test))] // Work around for rust-lang/rust#62127
 pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
@@ -188,11 +215,10 @@ pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// ### NOTE:
 ///
-/// If you rename the tokio crate in your dependencies this macro
-/// will not work. If you must rename the 0.3 version of tokio because
-/// you're also using the 0.1 version of tokio, you _must_ make the
-/// tokio 0.3 crate available as `tokio` in the module where this
-/// macro is expanded.
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
 #[cfg(not(test))] // Work around for rust-lang/rust#62127
 pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
@@ -223,13 +249,21 @@ pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
 /// }
 /// ```
 ///
+/// ### Configure the runtime to start with time paused
+///
+/// ```no_run
+/// #[tokio::test(start_paused = true)]
+/// async fn my_test() {
+///     assert!(true);
+/// }
+/// ```
+///
 /// ### NOTE:
 ///
-/// If you rename the tokio crate in your dependencies this macro
-/// will not work. If you must rename the 0.3 version of tokio because
-/// you're also using the 0.1 version of tokio, you _must_ make the
-/// tokio 0.3 crate available as `tokio` in the module where this
-/// macro is expanded.
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
 pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::test(args, item, true)
@@ -248,11 +282,10 @@ pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// ### NOTE:
 ///
-/// If you rename the tokio crate in your dependencies this macro
-/// will not work. If you must rename the 0.3 version of tokio because
-/// you're also using the 0.1 version of tokio, you _must_ make the
-/// tokio 0.3 crate available as `tokio` in the module where this
-/// macro is expanded.
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
 pub fn test_rt(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::test(args, item, false)

tokio-stream/CHANGELOG.md

@@ -0,0 +1,33 @@
+# 0.1.3 (February 5, 2021)
+
+Added
+
+ - sync: add wrapper for broadcast and watch ([#3384], [#3504])
+
+[#3384]: https://github.com/tokio-rs/tokio/pull/3384
+[#3504]: https://github.com/tokio-rs/tokio/pull/3504
+
+# 0.1.2 (January 12, 2021)
+
+Fixed
+
+ - docs: fix some wrappers missing in documentation ([#3378])
+
+[#3378]: https://github.com/tokio-rs/tokio/pull/3378
+
+# 0.1.1 (January 4, 2021)
+
+Added
+
+ - add `Stream` wrappers ([#3343])
+
+Fixed
+
+ - move `async-stream` to `dev-dependencies` ([#3366])
+
+[#3366]: https://github.com/tokio-rs/tokio/pull/3366
+[#3343]: https://github.com/tokio-rs/tokio/pull/3343
+
+# 0.1.0 (December 23, 2020)
+
+ - Initial release

tokio-stream/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "tokio-stream"
+# When releasing to crates.io:
+# - Remove path dependencies
+# - Update html_root_url.
+# - Update doc url
+#   - Cargo.toml
+# - Update CHANGELOG.md.
+# - Create "tokio-stream-0.1.x" git tag.
+version = "0.1.3"
+edition = "2018"
+authors = ["Tokio Contributors <[email protected]>"]
+license = "MIT"
+repository = "https://github.com/tokio-rs/tokio"
+homepage = "https://tokio.rs"
+documentation = "https://docs.rs/tokio-stream/0.1.3/tokio_stream"
+description = """
+Utilities to work with `Stream` and `tokio`.
+"""
+categories = ["asynchronous"]
+
+[features]
+default = ["time"]
+time = ["tokio/time"]
+net = ["tokio/net"]
+io-util = ["tokio/io-util"]
+fs = ["tokio/fs"]
+sync = ["tokio/sync", "tokio-util"]
+
+[dependencies]
+futures-core = { version = "0.3.0" }
+pin-project-lite = "0.2.0"
+tokio = { version = "1.0", features = ["sync"] }
+tokio-util = { version = "0.6.3", optional = true }
+
+[dev-dependencies]
+tokio = { version = "1.0", features = ["full", "test-util"] }
+async-stream = "0.3"
+tokio-test = { path = "../tokio-test" }
+futures = { version = "0.3", default-features = false }
+
+proptest = "0.10.0"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

tokio-stream/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2020 Tokio Contributors
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

tokio-stream/src/empty.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::marker::PhantomData;
 use core::pin::Pin;
@@ -24,7 +24,7 @@ unsafe impl<T> Sync for Empty<T> {}
 /// Basic usage:
 ///
 /// ```
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// #[tokio::main]
 /// async fn main() {

tokio-stream/src/iter.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::pin::Pin;
 use core::task::{Context, Poll};
@@ -8,6 +8,7 @@ use core::task::{Context, Poll};
 #[must_use = "streams do nothing unless polled"]
 pub struct Iter<I> {
     iter: I,
+    yield_amt: usize,
 }
 
 impl<I> Unpin for Iter<I> {}
@@ -20,7 +21,7 @@ impl<I> Unpin for Iter<I> {}
 ///
 /// ```
 /// # async fn dox() {
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// let mut stream = stream::iter(vec![17, 19]);
 ///
@@ -35,6 +36,7 @@ where
 {
     Iter {
         iter: i.into_iter(),
+        yield_amt: 0,
     }
 }
 
@@ -45,9 +47,18 @@ where
     type Item = I::Item;
 
     fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<I::Item>> {
-        let coop = ready!(crate::coop::poll_proceed(cx));
-        coop.made_progress();
-        Poll::Ready(self.iter.next())
+        // TODO: add coop back
+        if self.yield_amt >= 32 {
+            self.yield_amt = 0;
+
+            cx.waker().wake_by_ref();
+
+            Poll::Pending
+        } else {
+            self.yield_amt += 1;
+
+            Poll::Ready(self.iter.next())
+        }
     }
 
     fn size_hint(&self) -> (usize, Option<usize>) {

tokio-stream/src/lib.rs

@@ -0,0 +1,105 @@
+#![doc(html_root_url = "https://docs.rs/tokio-stream/0.1.3")]
+#![allow(
+    clippy::cognitive_complexity,
+    clippy::large_enum_variant,
+    clippy::needless_doctest_main
+)]
+#![warn(
+    missing_debug_implementations,
+    missing_docs,
+    rust_2018_idioms,
+    unreachable_pub
+)]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
+#![doc(test(
+    no_crate_inject,
+    attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
+))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
+#![doc(test(
+    no_crate_inject,
+    attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
+))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
+//! Stream utilities for Tokio.
+//!
+//! A `Stream` is an asynchronous sequence of values. It can be thought of as
+//! an asynchronous version of the standard library's `Iterator` trait.
+//!
+//! This crate provides helpers to work with them. For examples of usage and a more in-depth
+//! description of streams you can also refer to the [streams
+//! tutorial](https://tokio.rs/tokio/tutorial/streams) on the tokio website.
+//!
+//! # Iterating over a Stream
+//!
+//! Due to similarities with the standard library's `Iterator` trait, some new
+//! users may assume that they can use `for in` syntax to iterate over a
+//! `Stream`, but this is unfortunately not possible. Instead, you can use a
+//! `while let` loop as follows:
+//!
+//! ```rust
+//! use tokio_stream::{self as stream, StreamExt};
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let mut stream = stream::iter(vec![0, 1, 2]);
+//!
+//!     while let Some(value) = stream.next().await {
+//!         println!("Got {}", value);
+//!     }
+//! }
+//! ```
+//!
+//! # Returning a Stream from a function
+//!
+//! A common way to stream values from a function is to pass in the sender
+//! half of a channel and use the receiver as the stream. This requires awaiting
+//! both futures to ensure progress is made. Another alternative is the
+//! [async-stream] crate, which contains macros that provide a `yield` keyword
+//! and allow you to return an `impl Stream`.
+//!
+//! [async-stream]: https://docs.rs/async-stream
+//!
+//! # Conversion to and from AsyncRead/AsyncWrite
+//!
+//! It is often desirable to convert a `Stream` into an [`AsyncRead`],
+//! especially when dealing with plaintext formats streamed over the network.
+//! The opposite conversion from an [`AsyncRead`] into a `Stream` is also
+//! another commonly required feature. To enable these conversions,
+//! [`tokio-util`] provides the [`StreamReader`] and [`ReaderStream`]
+//! types when the io feature is enabled.
+//!
+//! [`tokio-util`]: https://docs.rs/tokio-util/0.4/tokio_util/codec/index.html
+//! [`tokio::io`]: https://docs.rs/tokio/1.0/tokio/io/index.html
+//! [`AsyncRead`]: https://docs.rs/tokio/1.0/tokio/io/trait.AsyncRead.html
+//! [`AsyncWrite`]: https://docs.rs/tokio/1.0/tokio/io/trait.AsyncWrite.html
+//! [`ReaderStream`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.ReaderStream.html
+//! [`StreamReader`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.StreamReader.html
+
+#[macro_use]
+mod macros;
+
+pub mod wrappers;
+
+mod stream_ext;
+pub use stream_ext::{collect::FromStream, StreamExt};
+
+mod empty;
+pub use empty::{empty, Empty};
+
+mod iter;
+pub use iter::{iter, Iter};
+
+mod once;
+pub use once::{once, Once};
+
+mod pending;
+pub use pending::{pending, Pending};
+
+mod stream_map;
+pub use stream_map::StreamMap;
+
+#[doc(no_inline)]
+pub use futures_core::Stream;

tokio-stream/src/macros.rs

@@ -0,0 +1,58 @@
+macro_rules! cfg_fs {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "fs")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
+            $item
+        )*
+    }
+}
+
+macro_rules! cfg_io_util {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "io-util")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "io-util")))]
+            $item
+        )*
+    }
+}
+
+macro_rules! cfg_net {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "net")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "net")))]
+            $item
+        )*
+    }
+}
+
+macro_rules! cfg_time {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "time")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
+            $item
+        )*
+    }
+}
+
+macro_rules! cfg_sync {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "sync")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
+            $item
+        )*
+    }
+}
+
+macro_rules! ready {
+    ($e:expr $(,)?) => {
+        match $e {
+            std::task::Poll::Ready(t) => t,
+            std::task::Poll::Pending => return std::task::Poll::Pending,
+        }
+    };
+}

tokio-stream/src/once.rs

@@ -1,4 +1,4 @@
-use crate::stream::{self, Iter, Stream};
+use crate::{Iter, Stream};
 
 use core::option;
 use core::pin::Pin;
@@ -20,7 +20,7 @@ impl<I> Unpin for Once<I> {}
 /// # Examples
 ///
 /// ```
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// #[tokio::main]
 /// async fn main() {
@@ -35,7 +35,7 @@ impl<I> Unpin for Once<I> {}
 /// ```
 pub fn once<T>(value: T) -> Once<T> {
     Once {
-        iter: stream::iter(Some(value).into_iter()),
+        iter: crate::iter(Some(value).into_iter()),
     }
 }
 

tokio-stream/src/pending.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::marker::PhantomData;
 use core::pin::Pin;
@@ -16,7 +16,7 @@ unsafe impl<T> Sync for Pending<T> {}
 /// Creates a stream that is never ready
 ///
 /// The returned stream is never ready. Attempting to call
-/// [`next()`](crate::stream::StreamExt::next) will never complete. Use
+/// [`next()`](crate::StreamExt::next) will never complete. Use
 /// [`stream::empty()`](super::empty()) to obtain a stream that is is
 /// immediately empty but returns no values.
 ///
@@ -25,7 +25,7 @@ unsafe impl<T> Sync for Pending<T> {}
 /// Basic usage:
 ///
 /// ```no_run
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// #[tokio::main]
 /// async fn main() {

tokio-stream/src/stream_ext.rs

@@ -1,57 +1,4 @@
-//! Stream utilities for Tokio.
-//!
-//! A `Stream` is an asynchronous sequence of values. It can be thought of as
-//! an asynchronous version of the standard library's `Iterator` trait.
-//!
-//! This module provides helpers to work with them. For examples of usage and a more in-depth
-//! description of streams you can also refer to the [streams
-//! tutorial](https://tokio.rs/tokio/tutorial/streams) on the tokio website.
-//!
-//! # Iterating over a Stream
-//!
-//! Due to similarities with the standard library's `Iterator` trait, some new
-//! users may assume that they can use `for in` syntax to iterate over a
-//! `Stream`, but this is unfortunately not possible. Instead, you can use a
-//! `while let` loop as follows:
-//!
-//! ```rust
-//! use tokio::stream::{self, StreamExt};
-//!
-//! #[tokio::main]
-//! async fn main() {
-//!     let mut stream = stream::iter(vec![0, 1, 2]);
-//!
-//!     while let Some(value) = stream.next().await {
-//!         println!("Got {}", value);
-//!     }
-//! }
-//! ```
-//!
-//! # Returning a Stream from a function
-//!
-//! A common way to stream values from a function is to pass in the sender
-//! half of a channel and use the receiver as the stream. This requires awaiting
-//! both futures to ensure progress is made. Another alternative is the
-//! [async-stream] crate, which contains macros that provide a `yield` keyword
-//! and allow you to return an `impl Stream`.
-//!
-//! [async-stream]: https://docs.rs/async-stream
-//!
-//! # Conversion to and from AsyncRead/AsyncWrite
-//!
-//! It is often desirable to convert a `Stream` into an [`AsyncRead`],
-//! especially when dealing with plaintext formats streamed over the network.
-//! The opposite conversion from an [`AsyncRead`] into a `Stream` is also
-//! another commonly required feature. To enable these conversions,
-//! [`tokio-util`] provides the [`StreamReader`] and [`ReaderStream`]
-//! types when the io feature is enabled.
-//!
-//! [tokio-util]: https://docs.rs/tokio-util/0.3/tokio_util/codec/index.html
-//! [`tokio::io`]: crate::io
-//! [`AsyncRead`]: crate::io::AsyncRead
-//! [`AsyncWrite`]: crate::io::AsyncWrite
-//! [`ReaderStream`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.ReaderStream.html
-//! [`StreamReader`]: https://docs.rs/tokio-util/0.4/tokio_util/io/struct.StreamReader.html
+use futures_core::Stream;
 
 mod all;
 use all::AllFuture;
@@ -62,12 +9,8 @@ use any::AnyFuture;
 mod chain;
 use chain::Chain;
 
-mod collect;
-use collect::Collect;
-pub use collect::FromStream;
-
-mod empty;
-pub use empty::{empty, Empty};
+pub(crate) mod collect;
+use collect::{Collect, FromStream};
 
 mod filter;
 use filter::Filter;
@@ -81,9 +24,6 @@ use fold::FoldFuture;
 mod fuse;
 use fuse::Fuse;
 
-mod iter;
-pub use iter::{iter, Iter};
-
 mod map;
 use map::Map;
 
@@ -93,15 +33,6 @@ use merge::Merge;
 mod next;
 use next::Next;
 
-mod once;
-pub use once::{once, Once};
-
-mod pending;
-pub use pending::{pending, Pending};
-
-mod stream_map;
-pub use stream_map::StreamMap;
-
 mod skip;
 use skip::Skip;
 
@@ -120,14 +51,11 @@ use take_while::TakeWhile;
 cfg_time! {
     mod timeout;
     use timeout::Timeout;
-    use crate::time::Duration;
+    use tokio::time::Duration;
     mod throttle;
-    use crate::stream::throttle::{throttle, Throttle};
+    use throttle::{throttle, Throttle};
 }
 
-#[doc(no_inline)]
-pub use futures_core::Stream;
-
 /// An extension trait for the [`Stream`] trait that provides a variety of
 /// convenient combinator functions.
 ///
@@ -146,11 +74,11 @@ pub use futures_core::Stream;
 /// # #[tokio::main(flavor = "current_thread")]
 /// # async fn main() {
 ///
-/// let a = tokio::stream::iter(vec![1, 3, 5]);
-/// let b = tokio::stream::iter(vec![2, 4, 6]);
+/// let a = tokio_stream::iter(vec![1, 3, 5]);
+/// let b = tokio_stream::iter(vec![2, 4, 6]);
 ///
 /// // use the fully qualified call syntax for the other trait:
-/// let merged = tokio::stream::StreamExt::merge(a, b);
+/// let merged = tokio_stream::StreamExt::merge(a, b);
 ///
 /// // use normal call notation for futures::stream::StreamExt::collect
 /// let output: Vec<_> = merged.collect().await;
@@ -158,7 +86,7 @@ pub use futures_core::Stream;
 /// # }
 /// ```
 ///
-/// [`Stream`]: crate::stream::Stream
+/// [`Stream`]: crate::Stream
 /// [futures]: https://docs.rs/futures
 /// [futures-StreamExt]: https://docs.rs/futures/0.3/futures/stream/trait.StreamExt.html
 pub trait StreamExt: Stream {
@@ -183,7 +111,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=3);
     ///
@@ -219,7 +147,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(vec![Ok(1), Ok(2), Err("nope")]);
     ///
@@ -251,7 +179,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let stream = stream::iter(1..=3);
     /// let mut stream = stream.map(|x| x + 3);
@@ -284,16 +212,17 @@ pub trait StreamExt: Stream {
     ///
     /// For merging multiple streams, consider using [`StreamMap`] instead.
     ///
-    /// [`StreamMap`]: crate::stream::StreamMap
+    /// [`StreamMap`]: crate::StreamMap
     ///
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::StreamExt;
+    /// use tokio_stream::{StreamExt, Stream};
     /// use tokio::sync::mpsc;
     /// use tokio::time;
     ///
     /// use std::time::Duration;
+    /// use std::pin::Pin;
     ///
     /// # /*
     /// #[tokio::main]
@@ -301,8 +230,21 @@ pub trait StreamExt: Stream {
     /// # #[tokio::main(flavor = "current_thread")]
     /// async fn main() {
     /// # time::pause();
-    ///     let (tx1, rx1) = mpsc::channel(10);
-    ///     let (tx2, rx2) = mpsc::channel(10);
+    ///     let (tx1, mut rx1) = mpsc::channel::<usize>(10);
+    ///     let (tx2, mut rx2) = mpsc::channel::<usize>(10);
+    ///
+    ///     // Convert the channels to a `Stream`.
+    ///     let rx1 = Box::pin(async_stream::stream! {
+    ///           while let Some(item) = rx1.recv().await {
+    ///               yield item;
+    ///           }
+    ///     }) as Pin<Box<dyn Stream<Item = usize> + Send>>;
+    ///
+    ///     let rx2 = Box::pin(async_stream::stream! {
+    ///           while let Some(item) = rx2.recv().await {
+    ///               yield item;
+    ///           }
+    ///     }) as Pin<Box<dyn Stream<Item = usize> + Send>>;
     ///
     ///     let mut rx = rx1.merge(rx2);
     ///
@@ -365,7 +307,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let stream = stream::iter(1..=8);
     /// let mut evens = stream.filter(|x| x % 2 == 0);
@@ -401,7 +343,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let stream = stream::iter(1..=8);
     /// let mut evens = stream.filter_map(|x| {
@@ -433,7 +375,7 @@ pub trait StreamExt: Stream {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{Stream, StreamExt};
+    /// use tokio_stream::{Stream, StreamExt};
     ///
     /// use std::pin::Pin;
     /// use std::task::{Context, Poll};
@@ -498,7 +440,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=10).take(3);
     ///
@@ -527,7 +469,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=10).take_while(|x| *x <= 3);
     ///
@@ -553,7 +495,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=10).skip(7);
     ///
@@ -584,7 +526,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     /// let mut stream = stream::iter(vec![1,2,3,4,1]).skip_while(|x| *x < 3);
     ///
     /// assert_eq!(Some(3), stream.next().await);
@@ -627,7 +569,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -642,7 +584,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -686,7 +628,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -701,7 +643,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -730,7 +672,7 @@ pub trait StreamExt: Stream {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// #[tokio::main]
     /// async fn main() {
@@ -770,7 +712,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, *};
+    /// use tokio_stream::{self as stream, *};
     ///
     /// let s = stream::iter(vec![1u8, 2, 3]);
     /// let sum = s.fold(0, |acc, x| acc + x).await;
@@ -797,7 +739,9 @@ pub trait StreamExt: Stream {
     /// `collect` streams all values, awaiting as needed. Values are pushed into
     /// a collection. A number of different target collection types are
     /// supported, including [`Vec`](std::vec::Vec),
-    /// [`String`](std::string::String), and [`Bytes`](bytes::Bytes).
+    /// [`String`](std::string::String), and [`Bytes`].
+    ///
+    /// [`Bytes`]: https://docs.rs/bytes/0.6.0/bytes/struct.Bytes.html
     ///
     /// # `Result`
     ///
@@ -816,7 +760,7 @@ pub trait StreamExt: Stream {
     /// Basic usage:
     ///
     /// ```
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// #[tokio::main]
     /// async fn main() {
@@ -833,7 +777,7 @@ pub trait StreamExt: Stream {
     /// Collecting a stream of `Result` values
     ///
     /// ```
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// #[tokio::main]
     /// async fn main() {
@@ -889,11 +833,12 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     /// use std::time::Duration;
     /// # let int_stream = stream::iter(1..=3);
     ///
-    /// let mut int_stream = int_stream.timeout(Duration::from_secs(1));
+    /// let int_stream = int_stream.timeout(Duration::from_secs(1));
+    /// tokio::pin!(int_stream);
     ///
     /// // When no items time out, we get the 3 elements in succession:
     /// assert_eq!(int_stream.try_next().await, Ok(Some(1)));
@@ -934,10 +879,11 @@ pub trait StreamExt: Stream {
     /// Create a throttled stream.
     /// ```rust,no_run
     /// use std::time::Duration;
-    /// use tokio::stream::StreamExt;
+    /// use tokio_stream::StreamExt;
     ///
     /// # async fn dox() {
-    /// let mut item_stream = futures::stream::repeat("one").throttle(Duration::from_secs(2));
+    /// let item_stream = futures::stream::repeat("one").throttle(Duration::from_secs(2));
+    /// tokio::pin!(item_stream);
     ///
     /// loop {
     ///     // The string will be produced at most every 2 seconds

tokio-stream/src/stream_ext/all.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::future::Future;
 use core::marker::PhantomPinned;

tokio-stream/src/stream_ext/any.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::future::Future;
 use core::marker::PhantomPinned;

tokio-stream/src/stream_ext/chain.rs

@@ -1,4 +1,5 @@
-use crate::stream::{Fuse, Stream};
+use crate::stream_ext::Fuse;
+use crate::Stream;
 
 use core::pin::Pin;
 use core::task::{Context, Poll};

tokio-stream/src/stream_ext/collect.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::future::Future;
 use core::marker::PhantomPinned;
@@ -26,7 +26,7 @@ pin_project! {
     }
 }
 
-/// Convert from a [`Stream`](crate::stream::Stream).
+/// Convert from a [`Stream`](crate::Stream).
 ///
 /// This trait is not intended to be used directly. Instead, call
 /// [`StreamExt::collect()`](super::StreamExt::collect).

tokio-stream/src/stream_ext/filter.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::fmt;
 use core::pin::Pin;

tokio-stream/src/stream_ext/filter_map.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::fmt;
 use core::pin::Pin;

tokio-stream/src/stream_ext/fold.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::future::Future;
 use core::marker::PhantomPinned;

tokio-stream/src/stream_ext/fuse.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use pin_project_lite::pin_project;
 use std::pin::Pin;

tokio-stream/src/stream_ext/map.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::fmt;
 use core::pin::Pin;

tokio-stream/src/stream_ext/merge.rs

@@ -1,4 +1,5 @@
-use crate::stream::{Fuse, Stream};
+use crate::stream_ext::Fuse;
+use crate::Stream;
 
 use core::pin::Pin;
 use core::task::{Context, Poll};

tokio-stream/src/stream_ext/next.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::future::Future;
 use core::marker::PhantomPinned;

tokio-stream/src/stream_ext/skip.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::fmt;
 use core::pin::Pin;

tokio-stream/src/stream_ext/skip_while.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::fmt;
 use core::pin::Pin;

tokio-stream/src/stream_ext/take.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::cmp;
 use core::fmt;

tokio-stream/src/stream_ext/take_while.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::fmt;
 use core::pin::Pin;

tokio-stream/src/stream_ext/throttle.rs

@@ -1,7 +1,7 @@
 //! Slow down a stream by enforcing a delay between items.
 
-use crate::stream::Stream;
-use crate::time::{Duration, Instant, Sleep};
+use crate::Stream;
+use tokio::time::{Duration, Instant, Sleep};
 
 use std::future::Future;
 use std::marker::Unpin;
@@ -14,14 +14,8 @@ pub(super) fn throttle<T>(duration: Duration, stream: T) -> Throttle<T>
 where
     T: Stream,
 {
-    let delay = if duration == Duration::from_millis(0) {
-        None
-    } else {
-        Some(Sleep::new_timeout(Instant::now() + duration))
-    };
-
     Throttle {
-        delay,
+        delay: tokio::time::sleep_until(Instant::now() + duration),
         duration,
         has_delayed: true,
         stream,
@@ -33,8 +27,8 @@ pin_project! {
     #[derive(Debug)]
     #[must_use = "streams do nothing unless polled"]
     pub struct Throttle<T> {
-        // `None` when duration is zero.
-        delay: Option<Sleep>,
+        #[pin]
+        delay: Sleep,
         duration: Duration,
 
         // Set to true when `delay` has returned ready, but `stream` hasn't.
@@ -75,23 +69,29 @@ impl<T: Unpin> Throttle<T> {
 impl<T: Stream> Stream for Throttle<T> {
     type Item = T::Item;
 
-    fn poll_next(mut self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Option<Self::Item>> {
-        if !self.has_delayed && self.delay.is_some() {
-            ready!(Pin::new(self.as_mut().project().delay.as_mut().unwrap()).poll(cx));
-            *self.as_mut().project().has_delayed = true;
+    fn poll_next(self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Option<Self::Item>> {
+        let mut me = self.project();
+        let dur = *me.duration;
+
+        if !*me.has_delayed && !is_zero(dur) {
+            ready!(me.delay.as_mut().poll(cx));
+            *me.has_delayed = true;
         }
 
-        let value = ready!(self.as_mut().project().stream.poll_next(cx));
+        let value = ready!(me.stream.poll_next(cx));
 
         if value.is_some() {
-            let dur = self.duration;
-            if let Some(ref mut delay) = self.as_mut().project().delay {
-                delay.reset(Instant::now() + dur);
+            if !is_zero(dur) {
+                me.delay.reset(Instant::now() + dur);
             }
 
-            *self.as_mut().project().has_delayed = false;
+            *me.has_delayed = false;
         }
 
         Poll::Ready(value)
     }
 }
+
+fn is_zero(dur: Duration) -> bool {
+    dur == Duration::from_millis(0)
+}

tokio-stream/src/stream_ext/timeout.rs

@@ -1,10 +1,12 @@
-use crate::stream::{Fuse, Stream};
-use crate::time::{error::Elapsed, Instant, Sleep};
+use crate::stream_ext::Fuse;
+use crate::Stream;
+use tokio::time::{Instant, Sleep};
 
 use core::future::Future;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 use pin_project_lite::pin_project;
+use std::fmt;
 use std::time::Duration;
 
 pin_project! {
@@ -14,16 +16,21 @@ pin_project! {
     pub struct Timeout<S> {
         #[pin]
         stream: Fuse<S>,
+        #[pin]
         deadline: Sleep,
         duration: Duration,
         poll_deadline: bool,
     }
 }
 
+/// Error returned by `Timeout`.
+#[derive(Debug, PartialEq)]
+pub struct Elapsed(());
+
 impl<S: Stream> Timeout<S> {
     pub(super) fn new(stream: S, duration: Duration) -> Self {
         let next = Instant::now() + duration;
-        let deadline = Sleep::new_timeout(next);
+        let deadline = tokio::time::sleep_until(next);
 
         Timeout {
             stream: Fuse::new(stream),
@@ -37,22 +44,24 @@ impl<S: Stream> Timeout<S> {
 impl<S: Stream> Stream for Timeout<S> {
     type Item = Result<S::Item, Elapsed>;
 
-    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
-        match self.as_mut().project().stream.poll_next(cx) {
+    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        let me = self.project();
+
+        match me.stream.poll_next(cx) {
             Poll::Ready(v) => {
                 if v.is_some() {
-                    let next = Instant::now() + self.duration;
-                    self.as_mut().project().deadline.reset(next);
-                    *self.as_mut().project().poll_deadline = true;
+                    let next = Instant::now() + *me.duration;
+                    me.deadline.reset(next);
+                    *me.poll_deadline = true;
                 }
                 return Poll::Ready(v.map(Ok));
             }
             Poll::Pending => {}
         };
 
-        if self.poll_deadline {
-            ready!(Pin::new(self.as_mut().project().deadline).poll(cx));
-            *self.as_mut().project().poll_deadline = false;
+        if *me.poll_deadline {
+            ready!(me.deadline.poll(cx));
+            *me.poll_deadline = false;
             return Poll::Ready(Some(Err(Elapsed::new())));
         }
 
@@ -63,3 +72,25 @@ impl<S: Stream> Stream for Timeout<S> {
         self.stream.size_hint()
     }
 }
+
+// ===== impl Elapsed =====
+
+impl Elapsed {
+    pub(crate) fn new() -> Self {
+        Elapsed(())
+    }
+}
+
+impl fmt::Display for Elapsed {
+    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+        "deadline has elapsed".fmt(fmt)
+    }
+}
+
+impl std::error::Error for Elapsed {}
+
+impl From<Elapsed> for std::io::Error {
+    fn from(_err: Elapsed) -> std::io::Error {
+        std::io::ErrorKind::TimedOut.into()
+    }
+}

tokio-stream/src/stream_ext/try_next.rs

@@ -1,4 +1,5 @@
-use crate::stream::{Next, Stream};
+use crate::stream_ext::Next;
+use crate::Stream;
 
 use core::future::Future;
 use core::marker::PhantomPinned;

tokio-stream/src/stream_map.rs

@@ -1,4 +1,4 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use std::borrow::Borrow;
 use std::hash::Hash;
@@ -42,9 +42,9 @@ use std::task::{Context, Poll};
 /// to be merged, it may be advisable to use tasks sending values on a shared
 /// [`mpsc`] channel.
 ///
-/// [`StreamExt::merge`]: crate::stream::StreamExt::merge
-/// [`mpsc`]: crate::sync::mpsc
-/// [`pin!`]: macro@pin
+/// [`StreamExt::merge`]: crate::StreamExt::merge
+/// [`mpsc`]: https://docs.rs/tokio/1.0/tokio/sync/mpsc/index.html
+/// [`pin!`]: https://docs.rs/tokio/1.0/tokio/macro.pin.html
 /// [`Box::pin`]: std::boxed::Box::pin
 ///
 /// # Examples
@@ -52,13 +52,27 @@ use std::task::{Context, Poll};
 /// Merging two streams, then remove them after receiving the first value
 ///
 /// ```
-/// use tokio::stream::{StreamExt, StreamMap};
+/// use tokio_stream::{StreamExt, StreamMap, Stream};
 /// use tokio::sync::mpsc;
+/// use std::pin::Pin;
 ///
 /// #[tokio::main]
 /// async fn main() {
-///     let (tx1, rx1) = mpsc::channel(10);
-///     let (tx2, rx2) = mpsc::channel(10);
+///     let (tx1, mut rx1) = mpsc::channel::<usize>(10);
+///     let (tx2, mut rx2) = mpsc::channel::<usize>(10);
+///
+///     // Convert the channels to a `Stream`.
+///     let rx1 = Box::pin(async_stream::stream! {
+///           while let Some(item) = rx1.recv().await {
+///               yield item;
+///           }
+///     }) as Pin<Box<dyn Stream<Item = usize> + Send>>;
+///
+///     let rx2 = Box::pin(async_stream::stream! {
+///           while let Some(item) = rx2.recv().await {
+///               yield item;
+///           }
+///     }) as Pin<Box<dyn Stream<Item = usize> + Send>>;
 ///
 ///     tokio::spawn(async move {
 ///         tx1.send(1).await.unwrap();
@@ -103,7 +117,7 @@ use std::task::{Context, Poll};
 /// sent to the client over a socket.
 ///
 /// ```no_run
-/// use tokio::stream::{Stream, StreamExt, StreamMap};
+/// use tokio_stream::{Stream, StreamExt, StreamMap};
 ///
 /// enum Command {
 ///     Join(String),
@@ -112,13 +126,13 @@ use std::task::{Context, Poll};
 ///
 /// fn commands() -> impl Stream<Item = Command> {
 ///     // Streams in user commands by parsing `stdin`.
-/// # tokio::stream::pending()
+/// # tokio_stream::pending()
 /// }
 ///
 /// // Join a channel, returns a stream of messages received on the channel.
 /// fn join(channel: &str) -> impl Stream<Item = String> + Unpin {
 ///     // left as an exercise to the reader
-/// # tokio::stream::pending()
+/// # tokio_stream::pending()
 /// }
 ///
 /// #[tokio::main]
@@ -170,7 +184,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     ///
@@ -193,7 +207,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     ///
@@ -217,7 +231,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, Pending};
+    /// use tokio_stream::{StreamMap, Pending};
     ///
     /// let map: StreamMap<&str, Pending<()>> = StreamMap::new();
     /// ```
@@ -233,7 +247,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, Pending};
+    /// use tokio_stream::{StreamMap, Pending};
     ///
     /// let map: StreamMap<&str, Pending<()>> = StreamMap::with_capacity(10);
     /// ```
@@ -250,7 +264,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     ///
@@ -273,7 +287,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     ///
@@ -296,7 +310,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     ///
@@ -320,7 +334,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, Pending};
+    /// use tokio_stream::{StreamMap, Pending};
     ///
     /// let map: StreamMap<i32, Pending<()>> = StreamMap::with_capacity(100);
     /// assert!(map.capacity() >= 100);
@@ -334,7 +348,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut a = StreamMap::new();
     /// assert_eq!(a.len(), 0);
@@ -367,7 +381,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut a = StreamMap::new();
     /// a.insert(1, pending::<i32>());
@@ -388,7 +402,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     ///
@@ -416,7 +430,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     /// map.insert(1, pending::<i32>());
@@ -445,7 +459,7 @@ impl<K, V> StreamMap<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{StreamMap, pending};
+    /// use tokio_stream::{StreamMap, pending};
     ///
     /// let mut map = StreamMap::new();
     /// map.insert(1, pending::<i32>());
@@ -476,7 +490,7 @@ where
     fn poll_next_entry(&mut self, cx: &mut Context<'_>) -> Poll<Option<(usize, V::Item)>> {
         use Poll::*;
 
-        let start = crate::util::thread_rng_n(self.entries.len() as u32) as usize;
+        let start = self::rand::thread_rng_n(self.entries.len() as u32) as usize;
         let mut idx = start;
 
         for _ in 0..self.entries.len() {
@@ -553,3 +567,98 @@ where
         ret
     }
 }
+
+mod rand {
+    use std::cell::Cell;
+
+    mod loom {
+        #[cfg(not(loom))]
+        pub(crate) mod rand {
+            use std::collections::hash_map::RandomState;
+            use std::hash::{BuildHasher, Hash, Hasher};
+            use std::sync::atomic::AtomicU32;
+            use std::sync::atomic::Ordering::Relaxed;
+
+            static COUNTER: AtomicU32 = AtomicU32::new(1);
+
+            pub(crate) fn seed() -> u64 {
+                let rand_state = RandomState::new();
+
+                let mut hasher = rand_state.build_hasher();
+
+                // Hash some unique-ish data to generate some new state
+                COUNTER.fetch_add(1, Relaxed).hash(&mut hasher);
+
+                // Get the seed
+                hasher.finish()
+            }
+        }
+
+        #[cfg(loom)]
+        pub(crate) mod rand {
+            pub(crate) fn seed() -> u64 {
+                1
+            }
+        }
+    }
+
+    /// Fast random number generate
+    ///
+    /// Implement xorshift64+: 2 32-bit xorshift sequences added together.
+    /// Shift triplet [17,7,16] was calculated as indicated in Marsaglia's
+    /// Xorshift paper: https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf
+    /// This generator passes the SmallCrush suite, part of TestU01 framework:
+    /// http://simul.iro.umontreal.ca/testu01/tu01.html
+    #[derive(Debug)]
+    pub(crate) struct FastRand {
+        one: Cell<u32>,
+        two: Cell<u32>,
+    }
+
+    impl FastRand {
+        /// Initialize a new, thread-local, fast random number generator.
+        pub(crate) fn new(seed: u64) -> FastRand {
+            let one = (seed >> 32) as u32;
+            let mut two = seed as u32;
+
+            if two == 0 {
+                // This value cannot be zero
+                two = 1;
+            }
+
+            FastRand {
+                one: Cell::new(one),
+                two: Cell::new(two),
+            }
+        }
+
+        pub(crate) fn fastrand_n(&self, n: u32) -> u32 {
+            // This is similar to fastrand() % n, but faster.
+            // See https://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/
+            let mul = (self.fastrand() as u64).wrapping_mul(n as u64);
+            (mul >> 32) as u32
+        }
+
+        fn fastrand(&self) -> u32 {
+            let mut s1 = self.one.get();
+            let s0 = self.two.get();
+
+            s1 ^= s1 << 17;
+            s1 = s1 ^ s0 ^ s1 >> 7 ^ s0 >> 16;
+
+            self.one.set(s0);
+            self.two.set(s1);
+
+            s0.wrapping_add(s1)
+        }
+    }
+
+    // Used by `StreamMap`
+    pub(crate) fn thread_rng_n(n: u32) -> u32 {
+        thread_local! {
+            static THREAD_RNG: FastRand = FastRand::new(loom::rand::seed());
+        }
+
+        THREAD_RNG.with(|rng| rng.fastrand_n(n))
+    }
+}

tokio-stream/src/wrappers.rs

@@ -0,0 +1,50 @@
+//! Wrappers for Tokio types that implement `Stream`.
+
+/// Error types for the wrappers.
+pub mod errors {
+    cfg_sync! {
+        pub use crate::wrappers::broadcast::BroadcastStreamRecvError;
+    }
+}
+
+mod mpsc_bounded;
+pub use mpsc_bounded::ReceiverStream;
+
+mod mpsc_unbounded;
+pub use mpsc_unbounded::UnboundedReceiverStream;
+
+cfg_sync! {
+    mod broadcast;
+    pub use broadcast::BroadcastStream;
+
+    mod watch;
+    pub use watch::WatchStream;
+}
+
+cfg_time! {
+    mod interval;
+    pub use interval::IntervalStream;
+}
+
+cfg_net! {
+    mod tcp_listener;
+    pub use tcp_listener::TcpListenerStream;
+
+    #[cfg(unix)]
+    mod unix_listener;
+    #[cfg(unix)]
+    pub use unix_listener::UnixListenerStream;
+}
+
+cfg_io_util! {
+    mod split;
+    pub use split::SplitStream;
+
+    mod lines;
+    pub use lines::LinesStream;
+}
+
+cfg_fs! {
+    mod read_dir;
+    pub use read_dir::ReadDirStream;
+}

tokio-stream/src/wrappers/broadcast.rs

@@ -0,0 +1,63 @@
+use std::pin::Pin;
+use tokio::sync::broadcast::error::RecvError;
+use tokio::sync::broadcast::Receiver;
+
+use futures_core::Stream;
+use tokio_util::sync::ReusableBoxFuture;
+
+use std::fmt;
+use std::task::{Context, Poll};
+
+/// A wrapper around [`tokio::sync::broadcast::Receiver`] that implements [`Stream`].
+///
+/// [`tokio::sync::broadcast::Receiver`]: struct@tokio::sync::broadcast::Receiver
+/// [`Stream`]: trait@crate::Stream
+#[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
+pub struct BroadcastStream<T> {
+    inner: ReusableBoxFuture<(Result<T, RecvError>, Receiver<T>)>,
+}
+
+/// An error returned from the inner stream of a [`BroadcastStream`].
+#[derive(Debug, PartialEq)]
+pub enum BroadcastStreamRecvError {
+    /// The receiver lagged too far behind. Attempting to receive again will
+    /// return the oldest message still retained by the channel.
+    ///
+    /// Includes the number of skipped messages.
+    Lagged(u64),
+}
+
+async fn make_future<T: Clone>(mut rx: Receiver<T>) -> (Result<T, RecvError>, Receiver<T>) {
+    let result = rx.recv().await;
+    (result, rx)
+}
+
+impl<T: 'static + Clone + Send> BroadcastStream<T> {
+    /// Create a new `BroadcastStream`.
+    pub fn new(rx: Receiver<T>) -> Self {
+        Self {
+            inner: ReusableBoxFuture::new(make_future(rx)),
+        }
+    }
+}
+
+impl<T: 'static + Clone + Send> Stream for BroadcastStream<T> {
+    type Item = Result<T, BroadcastStreamRecvError>;
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        let (result, rx) = ready!(self.inner.poll(cx));
+        self.inner.set(make_future(rx));
+        match result {
+            Ok(item) => Poll::Ready(Some(Ok(item))),
+            Err(RecvError::Closed) => Poll::Ready(None),
+            Err(RecvError::Lagged(n)) => {
+                Poll::Ready(Some(Err(BroadcastStreamRecvError::Lagged(n))))
+            }
+        }
+    }
+}
+
+impl<T> fmt::Debug for BroadcastStream<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("BroadcastStream").finish()
+    }
+}

tokio-stream/src/wrappers/interval.rs

@@ -0,0 +1,50 @@
+use crate::Stream;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::time::{Instant, Interval};
+
+/// A wrapper around [`Interval`] that implements [`Stream`].
+///
+/// [`Interval`]: struct@tokio::time::Interval
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(feature = "time")))]
+pub struct IntervalStream {
+    inner: Interval,
+}
+
+impl IntervalStream {
+    /// Create a new `IntervalStream`.
+    pub fn new(interval: Interval) -> Self {
+        Self { inner: interval }
+    }
+
+    /// Get back the inner `Interval`.
+    pub fn into_inner(self) -> Interval {
+        self.inner
+    }
+}
+
+impl Stream for IntervalStream {
+    type Item = Instant;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Instant>> {
+        self.inner.poll_tick(cx).map(Some)
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (std::usize::MAX, None)
+    }
+}
+
+impl AsRef<Interval> for IntervalStream {
+    fn as_ref(&self) -> &Interval {
+        &self.inner
+    }
+}
+
+impl AsMut<Interval> for IntervalStream {
+    fn as_mut(&mut self) -> &mut Interval {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/lines.rs

@@ -0,0 +1,60 @@
+use crate::Stream;
+use pin_project_lite::pin_project;
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::io::{AsyncBufRead, Lines};
+
+pin_project! {
+    /// A wrapper around [`tokio::io::Lines`] that implements [`Stream`].
+    ///
+    /// [`tokio::io::Lines`]: struct@tokio::io::Lines
+    /// [`Stream`]: trait@crate::Stream
+    #[derive(Debug)]
+    #[cfg_attr(docsrs, doc(cfg(feature = "io-util")))]
+    pub struct LinesStream<R> {
+        #[pin]
+        inner: Lines<R>,
+    }
+}
+
+impl<R> LinesStream<R> {
+    /// Create a new `LinesStream`.
+    pub fn new(lines: Lines<R>) -> Self {
+        Self { inner: lines }
+    }
+
+    /// Get back the inner `Lines`.
+    pub fn into_inner(self) -> Lines<R> {
+        self.inner
+    }
+
+    /// Obtain a pinned reference to the inner `Lines<R>`.
+    #[allow(clippy::wrong_self_convention)] // https://github.com/rust-lang/rust-clippy/issues/4546
+    pub fn as_pin_mut(self: Pin<&mut Self>) -> Pin<&mut Lines<R>> {
+        self.project().inner
+    }
+}
+
+impl<R: AsyncBufRead> Stream for LinesStream<R> {
+    type Item = io::Result<String>;
+
+    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.project()
+            .inner
+            .poll_next_line(cx)
+            .map(Result::transpose)
+    }
+}
+
+impl<R> AsRef<Lines<R>> for LinesStream<R> {
+    fn as_ref(&self) -> &Lines<R> {
+        &self.inner
+    }
+}
+
+impl<R> AsMut<Lines<R>> for LinesStream<R> {
+    fn as_mut(&mut self) -> &mut Lines<R> {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/mpsc_bounded.rs

@@ -0,0 +1,59 @@
+use crate::Stream;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::sync::mpsc::Receiver;
+
+/// A wrapper around [`tokio::sync::mpsc::Receiver`] that implements [`Stream`].
+///
+/// [`tokio::sync::mpsc::Receiver`]: struct@tokio::sync::mpsc::Receiver
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+pub struct ReceiverStream<T> {
+    inner: Receiver<T>,
+}
+
+impl<T> ReceiverStream<T> {
+    /// Create a new `ReceiverStream`.
+    pub fn new(recv: Receiver<T>) -> Self {
+        Self { inner: recv }
+    }
+
+    /// Get back the inner `Receiver`.
+    pub fn into_inner(self) -> Receiver<T> {
+        self.inner
+    }
+
+    /// Closes the receiving half of a channel without dropping it.
+    ///
+    /// This prevents any further messages from being sent on the channel while
+    /// still enabling the receiver to drain messages that are buffered. Any
+    /// outstanding [`Permit`] values will still be able to send messages.
+    ///
+    /// To guarantee no messages are dropped, after calling `close()`, you must
+    /// receive all items from the stream until `None` is returned.
+    ///
+    /// [`Permit`]: struct@tokio::sync::mpsc::Permit
+    pub fn close(&mut self) {
+        self.inner.close()
+    }
+}
+
+impl<T> Stream for ReceiverStream<T> {
+    type Item = T;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.inner.poll_recv(cx)
+    }
+}
+
+impl<T> AsRef<Receiver<T>> for ReceiverStream<T> {
+    fn as_ref(&self) -> &Receiver<T> {
+        &self.inner
+    }
+}
+
+impl<T> AsMut<Receiver<T>> for ReceiverStream<T> {
+    fn as_mut(&mut self) -> &mut Receiver<T> {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/mpsc_unbounded.rs

@@ -0,0 +1,53 @@
+use crate::Stream;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::sync::mpsc::UnboundedReceiver;
+
+/// A wrapper around [`tokio::sync::mpsc::UnboundedReceiver`] that implements [`Stream`].
+///
+/// [`tokio::sync::mpsc::UnboundedReceiver`]: struct@tokio::sync::mpsc::UnboundedReceiver
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+pub struct UnboundedReceiverStream<T> {
+    inner: UnboundedReceiver<T>,
+}
+
+impl<T> UnboundedReceiverStream<T> {
+    /// Create a new `UnboundedReceiverStream`.
+    pub fn new(recv: UnboundedReceiver<T>) -> Self {
+        Self { inner: recv }
+    }
+
+    /// Get back the inner `UnboundedReceiver`.
+    pub fn into_inner(self) -> UnboundedReceiver<T> {
+        self.inner
+    }
+
+    /// Closes the receiving half of a channel without dropping it.
+    ///
+    /// This prevents any further messages from being sent on the channel while
+    /// still enabling the receiver to drain messages that are buffered.
+    pub fn close(&mut self) {
+        self.inner.close()
+    }
+}
+
+impl<T> Stream for UnboundedReceiverStream<T> {
+    type Item = T;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.inner.poll_recv(cx)
+    }
+}
+
+impl<T> AsRef<UnboundedReceiver<T>> for UnboundedReceiverStream<T> {
+    fn as_ref(&self) -> &UnboundedReceiver<T> {
+        &self.inner
+    }
+}
+
+impl<T> AsMut<UnboundedReceiver<T>> for UnboundedReceiverStream<T> {
+    fn as_mut(&mut self) -> &mut UnboundedReceiver<T> {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/read_dir.rs

@@ -0,0 +1,47 @@
+use crate::Stream;
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::fs::{DirEntry, ReadDir};
+
+/// A wrapper around [`tokio::fs::ReadDir`] that implements [`Stream`].
+///
+/// [`tokio::fs::ReadDir`]: struct@tokio::fs::ReadDir
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
+pub struct ReadDirStream {
+    inner: ReadDir,
+}
+
+impl ReadDirStream {
+    /// Create a new `ReadDirStream`.
+    pub fn new(read_dir: ReadDir) -> Self {
+        Self { inner: read_dir }
+    }
+
+    /// Get back the inner `ReadDir`.
+    pub fn into_inner(self) -> ReadDir {
+        self.inner
+    }
+}
+
+impl Stream for ReadDirStream {
+    type Item = io::Result<DirEntry>;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.inner.poll_next_entry(cx).map(Result::transpose)
+    }
+}
+
+impl AsRef<ReadDir> for ReadDirStream {
+    fn as_ref(&self) -> &ReadDir {
+        &self.inner
+    }
+}
+
+impl AsMut<ReadDir> for ReadDirStream {
+    fn as_mut(&mut self) -> &mut ReadDir {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/split.rs

@@ -0,0 +1,60 @@
+use crate::Stream;
+use pin_project_lite::pin_project;
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::io::{AsyncBufRead, Split};
+
+pin_project! {
+    /// A wrapper around [`tokio::io::Split`] that implements [`Stream`].
+    ///
+    /// [`tokio::io::Split`]: struct@tokio::io::Split
+    /// [`Stream`]: trait@crate::Stream
+    #[derive(Debug)]
+    #[cfg_attr(docsrs, doc(cfg(feature = "io-util")))]
+    pub struct SplitStream<R> {
+        #[pin]
+        inner: Split<R>,
+    }
+}
+
+impl<R> SplitStream<R> {
+    /// Create a new `SplitStream`.
+    pub fn new(split: Split<R>) -> Self {
+        Self { inner: split }
+    }
+
+    /// Get back the inner `Split`.
+    pub fn into_inner(self) -> Split<R> {
+        self.inner
+    }
+
+    /// Obtain a pinned reference to the inner `Split<R>`.
+    #[allow(clippy::wrong_self_convention)] // https://github.com/rust-lang/rust-clippy/issues/4546
+    pub fn as_pin_mut(self: Pin<&mut Self>) -> Pin<&mut Split<R>> {
+        self.project().inner
+    }
+}
+
+impl<R: AsyncBufRead> Stream for SplitStream<R> {
+    type Item = io::Result<Vec<u8>>;
+
+    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.project()
+            .inner
+            .poll_next_segment(cx)
+            .map(Result::transpose)
+    }
+}
+
+impl<R> AsRef<Split<R>> for SplitStream<R> {
+    fn as_ref(&self) -> &Split<R> {
+        &self.inner
+    }
+}
+
+impl<R> AsMut<Split<R>> for SplitStream<R> {
+    fn as_mut(&mut self) -> &mut Split<R> {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/tcp_listener.rs

@@ -0,0 +1,54 @@
+use crate::Stream;
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::net::{TcpListener, TcpStream};
+
+/// A wrapper around [`TcpListener`] that implements [`Stream`].
+///
+/// [`TcpListener`]: struct@tokio::net::TcpListener
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(feature = "net")))]
+pub struct TcpListenerStream {
+    inner: TcpListener,
+}
+
+impl TcpListenerStream {
+    /// Create a new `TcpListenerStream`.
+    pub fn new(listener: TcpListener) -> Self {
+        Self { inner: listener }
+    }
+
+    /// Get back the inner `TcpListener`.
+    pub fn into_inner(self) -> TcpListener {
+        self.inner
+    }
+}
+
+impl Stream for TcpListenerStream {
+    type Item = io::Result<TcpStream>;
+
+    fn poll_next(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Option<io::Result<TcpStream>>> {
+        match self.inner.poll_accept(cx) {
+            Poll::Ready(Ok((stream, _))) => Poll::Ready(Some(Ok(stream))),
+            Poll::Ready(Err(err)) => Poll::Ready(Some(Err(err))),
+            Poll::Pending => Poll::Pending,
+        }
+    }
+}
+
+impl AsRef<TcpListener> for TcpListenerStream {
+    fn as_ref(&self) -> &TcpListener {
+        &self.inner
+    }
+}
+
+impl AsMut<TcpListener> for TcpListenerStream {
+    fn as_mut(&mut self) -> &mut TcpListener {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/unix_listener.rs

@@ -0,0 +1,54 @@
+use crate::Stream;
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::net::{UnixListener, UnixStream};
+
+/// A wrapper around [`UnixListener`] that implements [`Stream`].
+///
+/// [`UnixListener`]: struct@tokio::net::UnixListener
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(all(unix, feature = "net"))))]
+pub struct UnixListenerStream {
+    inner: UnixListener,
+}
+
+impl UnixListenerStream {
+    /// Create a new `UnixListenerStream`.
+    pub fn new(listener: UnixListener) -> Self {
+        Self { inner: listener }
+    }
+
+    /// Get back the inner `UnixListener`.
+    pub fn into_inner(self) -> UnixListener {
+        self.inner
+    }
+}
+
+impl Stream for UnixListenerStream {
+    type Item = io::Result<UnixStream>;
+
+    fn poll_next(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Option<io::Result<UnixStream>>> {
+        match self.inner.poll_accept(cx) {
+            Poll::Ready(Ok((stream, _))) => Poll::Ready(Some(Ok(stream))),
+            Poll::Ready(Err(err)) => Poll::Ready(Some(Err(err))),
+            Poll::Pending => Poll::Pending,
+        }
+    }
+}
+
+impl AsRef<UnixListener> for UnixListenerStream {
+    fn as_ref(&self) -> &UnixListener {
+        &self.inner
+    }
+}
+
+impl AsMut<UnixListener> for UnixListenerStream {
+    fn as_mut(&mut self) -> &mut UnixListener {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/watch.rs

@@ -0,0 +1,61 @@
+use std::pin::Pin;
+use tokio::sync::watch::Receiver;
+
+use futures_core::Stream;
+use tokio_util::sync::ReusableBoxFuture;
+
+use std::fmt;
+use std::task::{Context, Poll};
+use tokio::sync::watch::error::RecvError;
+
+/// A wrapper around [`tokio::sync::watch::Receiver`] that implements [`Stream`].
+///
+/// [`tokio::sync::watch::Receiver`]: struct@tokio::sync::watch::Receiver
+/// [`Stream`]: trait@crate::Stream
+#[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
+pub struct WatchStream<T> {
+    inner: ReusableBoxFuture<(Result<(), RecvError>, Receiver<T>)>,
+}
+
+async fn make_future<T: Clone + Send + Sync>(
+    mut rx: Receiver<T>,
+) -> (Result<(), RecvError>, Receiver<T>) {
+    let result = rx.changed().await;
+    (result, rx)
+}
+
+impl<T: 'static + Clone + Unpin + Send + Sync> WatchStream<T> {
+    /// Create a new `WatchStream`.
+    pub fn new(rx: Receiver<T>) -> Self {
+        Self {
+            inner: ReusableBoxFuture::new(make_future(rx)),
+        }
+    }
+}
+
+impl<T: Clone + 'static + Send + Sync> Stream for WatchStream<T> {
+    type Item = T;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        let (result, rx) = ready!(self.inner.poll(cx));
+        match result {
+            Ok(_) => {
+                let received = (*rx.borrow()).clone();
+                self.inner.set(make_future(rx));
+                Poll::Ready(Some(received))
+            }
+            Err(_) => {
+                self.inner.set(make_future(rx));
+                Poll::Ready(None)
+            }
+        }
+    }
+}
+
+impl<T> Unpin for WatchStream<T> {}
+
+impl<T> fmt::Debug for WatchStream<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("WatchStream").finish()
+    }
+}

tokio-stream/tests/async_send_sync.rs

@@ -0,0 +1,105 @@
+use std::rc::Rc;
+
+#[allow(dead_code)]
+type BoxStream<T> = std::pin::Pin<Box<dyn tokio_stream::Stream<Item = T>>>;
+
+#[allow(dead_code)]
+fn require_send<T: Send>(_t: &T) {}
+#[allow(dead_code)]
+fn require_sync<T: Sync>(_t: &T) {}
+#[allow(dead_code)]
+fn require_unpin<T: Unpin>(_t: &T) {}
+
+#[allow(dead_code)]
+struct Invalid;
+
+trait AmbiguousIfSend<A> {
+    fn some_item(&self) {}
+}
+impl<T: ?Sized> AmbiguousIfSend<()> for T {}
+impl<T: ?Sized + Send> AmbiguousIfSend<Invalid> for T {}
+
+trait AmbiguousIfSync<A> {
+    fn some_item(&self) {}
+}
+impl<T: ?Sized> AmbiguousIfSync<()> for T {}
+impl<T: ?Sized + Sync> AmbiguousIfSync<Invalid> for T {}
+
+trait AmbiguousIfUnpin<A> {
+    fn some_item(&self) {}
+}
+impl<T: ?Sized> AmbiguousIfUnpin<()> for T {}
+impl<T: ?Sized + Unpin> AmbiguousIfUnpin<Invalid> for T {}
+
+macro_rules! into_todo {
+    ($typ:ty) => {{
+        let x: $typ = todo!();
+        x
+    }};
+}
+
+macro_rules! async_assert_fn {
+    ($($f:ident $(< $($generic:ty),* > )? )::+($($arg:ty),*): Send & Sync) => {
+        #[allow(unreachable_code)]
+        #[allow(unused_variables)]
+        const _: fn() = || {
+            let f = $($f $(::<$($generic),*>)? )::+( $( into_todo!($arg) ),* );
+            require_send(&f);
+            require_sync(&f);
+        };
+    };
+    ($($f:ident $(< $($generic:ty),* > )? )::+($($arg:ty),*): Send & !Sync) => {
+        #[allow(unreachable_code)]
+        #[allow(unused_variables)]
+        const _: fn() = || {
+            let f = $($f $(::<$($generic),*>)? )::+( $( into_todo!($arg) ),* );
+            require_send(&f);
+            AmbiguousIfSync::some_item(&f);
+        };
+    };
+    ($($f:ident $(< $($generic:ty),* > )? )::+($($arg:ty),*): !Send & Sync) => {
+        #[allow(unreachable_code)]
+        #[allow(unused_variables)]
+        const _: fn() = || {
+            let f = $($f $(::<$($generic),*>)? )::+( $( into_todo!($arg) ),* );
+            AmbiguousIfSend::some_item(&f);
+            require_sync(&f);
+        };
+    };
+    ($($f:ident $(< $($generic:ty),* > )? )::+($($arg:ty),*): !Send & !Sync) => {
+        #[allow(unreachable_code)]
+        #[allow(unused_variables)]
+        const _: fn() = || {
+            let f = $($f $(::<$($generic),*>)? )::+( $( into_todo!($arg) ),* );
+            AmbiguousIfSend::some_item(&f);
+            AmbiguousIfSync::some_item(&f);
+        };
+    };
+    ($($f:ident $(< $($generic:ty),* > )? )::+($($arg:ty),*): !Unpin) => {
+        #[allow(unreachable_code)]
+        #[allow(unused_variables)]
+        const _: fn() = || {
+            let f = $($f $(::<$($generic),*>)? )::+( $( into_todo!($arg) ),* );
+            AmbiguousIfUnpin::some_item(&f);
+        };
+    };
+    ($($f:ident $(< $($generic:ty),* > )? )::+($($arg:ty),*): Unpin) => {
+        #[allow(unreachable_code)]
+        #[allow(unused_variables)]
+        const _: fn() = || {
+            let f = $($f $(::<$($generic),*>)? )::+( $( into_todo!($arg) ),* );
+            require_unpin(&f);
+        };
+    };
+}
+
+async_assert_fn!(tokio_stream::empty<Rc<u8>>(): Send & Sync);
+async_assert_fn!(tokio_stream::pending<Rc<u8>>(): Send & Sync);
+async_assert_fn!(tokio_stream::iter(std::vec::IntoIter<u8>): Send & Sync);
+
+async_assert_fn!(tokio_stream::StreamExt::next(&mut BoxStream<()>): !Unpin);
+async_assert_fn!(tokio_stream::StreamExt::try_next(&mut BoxStream<Result<(), ()>>): !Unpin);
+async_assert_fn!(tokio_stream::StreamExt::all(&mut BoxStream<()>, fn(())->bool): !Unpin);
+async_assert_fn!(tokio_stream::StreamExt::any(&mut BoxStream<()>, fn(())->bool): !Unpin);
+async_assert_fn!(tokio_stream::StreamExt::fold(&mut BoxStream<()>, (), fn((), ())->()): !Unpin);
+async_assert_fn!(tokio_stream::StreamExt::collect<Vec<()>>(&mut BoxStream<()>): !Unpin);

tokio-stream/tests/stream_chain.rs

@@ -1,7 +1,12 @@
-use tokio::stream::{self, Stream, StreamExt};
-use tokio::sync::mpsc;
+use tokio_stream::{self as stream, Stream, StreamExt};
 use tokio_test::{assert_pending, assert_ready, task};
 
+mod support {
+    pub(crate) mod mpsc;
+}
+
+use support::mpsc;
+
 #[tokio::test]
 async fn basic_usage() {
     let one = stream::iter(vec![1, 2, 3]);
@@ -36,8 +41,8 @@ async fn basic_usage() {
 
 #[tokio::test]
 async fn pending_first() {
-    let (tx1, rx1) = mpsc::unbounded_channel();
-    let (tx2, rx2) = mpsc::unbounded_channel();
+    let (tx1, rx1) = mpsc::unbounded_channel_stream();
+    let (tx2, rx2) = mpsc::unbounded_channel_stream();
 
     let mut stream = task::spawn(rx1.chain(rx2));
     assert_eq!(stream.size_hint(), (0, None));
@@ -74,7 +79,7 @@ async fn pending_first() {
 fn size_overflow() {
     struct Monster;
 
-    impl tokio::stream::Stream for Monster {
+    impl tokio_stream::Stream for Monster {
         type Item = ();
         fn poll_next(
             self: std::pin::Pin<&mut Self>,

tokio-stream/tests/stream_collect.rs

@@ -1,7 +1,12 @@
-use tokio::stream::{self, StreamExt};
-use tokio::sync::mpsc;
+use tokio_stream::{self as stream, StreamExt};
 use tokio_test::{assert_pending, assert_ready, assert_ready_err, assert_ready_ok, task};
 
+mod support {
+    pub(crate) mod mpsc;
+}
+
+use support::mpsc;
+
 #[allow(clippy::let_unit_value)]
 #[tokio::test]
 async fn empty_unit() {
@@ -37,7 +42,7 @@ async fn empty_result() {
 
 #[tokio::test]
 async fn collect_vec_items() {
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
     let mut fut = task::spawn(rx.collect::<Vec<i32>>());
 
     assert_pending!(fut.poll());
@@ -58,7 +63,8 @@ async fn collect_vec_items() {
 
 #[tokio::test]
 async fn collect_string_items() {
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
+
     let mut fut = task::spawn(rx.collect::<String>());
 
     assert_pending!(fut.poll());
@@ -79,7 +85,8 @@ async fn collect_string_items() {
 
 #[tokio::test]
 async fn collect_str_items() {
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
+
     let mut fut = task::spawn(rx.collect::<String>());
 
     assert_pending!(fut.poll());
@@ -100,7 +107,8 @@ async fn collect_str_items() {
 
 #[tokio::test]
 async fn collect_results_ok() {
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
+
     let mut fut = task::spawn(rx.collect::<Result<String, &str>>());
 
     assert_pending!(fut.poll());
@@ -121,7 +129,8 @@ async fn collect_results_ok() {
 
 #[tokio::test]
 async fn collect_results_err() {
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
+
     let mut fut = task::spawn(rx.collect::<Result<String, &str>>());
 
     assert_pending!(fut.poll());

tokio-stream/tests/stream_empty.rs

@@ -1,4 +1,4 @@
-use tokio::stream::{self, Stream, StreamExt};
+use tokio_stream::{self as stream, Stream, StreamExt};
 
 #[tokio::test]
 async fn basic_usage() {

tokio-stream/tests/stream_fuse.rs

@@ -1,4 +1,4 @@
-use tokio::stream::{Stream, StreamExt};
+use tokio_stream::{Stream, StreamExt};
 
 use std::pin::Pin;
 use std::task::{Context, Poll};

tokio-stream/tests/stream_iter.rs

@@ -1,4 +1,4 @@
-use tokio::stream;
+use tokio_stream as stream;
 use tokio_test::task;
 
 use std::iter;

tokio-stream/tests/stream_merge.rs

@@ -1,8 +1,13 @@
-use tokio::stream::{self, Stream, StreamExt};
-use tokio::sync::mpsc;
+use tokio_stream::{self as stream, Stream, StreamExt};
 use tokio_test::task;
 use tokio_test::{assert_pending, assert_ready};
 
+mod support {
+    pub(crate) mod mpsc;
+}
+
+use support::mpsc;
+
 #[tokio::test]
 async fn merge_sync_streams() {
     let mut s = stream::iter(vec![0, 2, 4, 6]).merge(stream::iter(vec![1, 3, 5]));
@@ -18,8 +23,8 @@ async fn merge_sync_streams() {
 
 #[tokio::test]
 async fn merge_async_streams() {
-    let (tx1, rx1) = mpsc::unbounded_channel();
-    let (tx2, rx2) = mpsc::unbounded_channel();
+    let (tx1, rx1) = mpsc::unbounded_channel_stream();
+    let (tx2, rx2) = mpsc::unbounded_channel_stream();
 
     let mut rx = task::spawn(rx1.merge(rx2));
 
@@ -57,7 +62,7 @@ async fn merge_async_streams() {
 fn size_overflow() {
     struct Monster;
 
-    impl tokio::stream::Stream for Monster {
+    impl tokio_stream::Stream for Monster {
         type Item = ();
         fn poll_next(
             self: std::pin::Pin<&mut Self>,

tokio-stream/tests/stream_once.rs

@@ -1,4 +1,4 @@
-use tokio::stream::{self, Stream, StreamExt};
+use tokio_stream::{self as stream, Stream, StreamExt};
 
 #[tokio::test]
 async fn basic_usage() {

tokio-stream/tests/stream_pending.rs

@@ -1,4 +1,4 @@
-use tokio::stream::{self, Stream, StreamExt};
+use tokio_stream::{self as stream, Stream, StreamExt};
 use tokio_test::{assert_pending, task};
 
 #[tokio::test]

tokio-stream/tests/stream_stream_map.rs

@@ -1,7 +1,12 @@
-use tokio::stream::{self, pending, Stream, StreamExt, StreamMap};
-use tokio::sync::mpsc;
+use tokio_stream::{self as stream, pending, Stream, StreamExt, StreamMap};
 use tokio_test::{assert_ok, assert_pending, assert_ready, task};
 
+mod support {
+    pub(crate) mod mpsc;
+}
+
+use support::mpsc;
+
 use std::pin::Pin;
 
 macro_rules! assert_ready_some {
@@ -38,7 +43,8 @@ async fn empty() {
 #[tokio::test]
 async fn single_entry() {
     let mut map = task::spawn(StreamMap::new());
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
+    let rx = Box::pin(rx);
 
     assert_ready_none!(map.poll_next());
 
@@ -76,8 +82,11 @@ async fn single_entry() {
 #[tokio::test]
 async fn multiple_entries() {
     let mut map = task::spawn(StreamMap::new());
-    let (tx1, rx1) = mpsc::unbounded_channel();
-    let (tx2, rx2) = mpsc::unbounded_channel();
+    let (tx1, rx1) = mpsc::unbounded_channel_stream();
+    let (tx2, rx2) = mpsc::unbounded_channel_stream();
+
+    let rx1 = Box::pin(rx1);
+    let rx2 = Box::pin(rx2);
 
     map.insert("foo", rx1);
     map.insert("bar", rx2);
@@ -132,7 +141,9 @@ async fn multiple_entries() {
 #[tokio::test]
 async fn insert_remove() {
     let mut map = task::spawn(StreamMap::new());
-    let (tx, rx) = mpsc::unbounded_channel();
+    let (tx, rx) = mpsc::unbounded_channel_stream();
+
+    let rx = Box::pin(rx);
 
     assert_ready_none!(map.poll_next());
 
@@ -160,8 +171,11 @@ async fn insert_remove() {
 #[tokio::test]
 async fn replace() {
     let mut map = task::spawn(StreamMap::new());
-    let (tx1, rx1) = mpsc::unbounded_channel();
-    let (tx2, rx2) = mpsc::unbounded_channel();
+    let (tx1, rx1) = mpsc::unbounded_channel_stream();
+    let (tx2, rx2) = mpsc::unbounded_channel_stream();
+
+    let rx1 = Box::pin(rx1);
+    let rx2 = Box::pin(rx2);
 
     assert!(map.insert("foo", rx1).is_none());
 

tokio-stream/tests/stream_timeout.rs

@@ -1,7 +1,7 @@
 #![cfg(feature = "full")]
 
-use tokio::stream::{self, StreamExt};
 use tokio::time::{self, sleep, Duration};
+use tokio_stream::{self, StreamExt};
 use tokio_test::*;
 
 use futures::StreamExt as _;

tokio-stream/tests/support/mpsc.rs

@@ -0,0 +1,15 @@
+use async_stream::stream;
+use tokio::sync::mpsc::{self, UnboundedSender};
+use tokio_stream::Stream;
+
+pub fn unbounded_channel_stream<T: Unpin>() -> (UnboundedSender<T>, impl Stream<Item = T>) {
+    let (tx, mut rx) = mpsc::unbounded_channel();
+
+    let stream = stream! {
+        while let Some(item) = rx.recv().await {
+            yield item;
+        }
+    };
+
+    (tx, stream)
+}

tokio-stream/tests/time_throttle.rs

@@ -1,8 +1,8 @@
 #![warn(rust_2018_idioms)]
 #![cfg(feature = "full")]
 
-use tokio::stream::StreamExt;
 use tokio::time;
+use tokio_stream::StreamExt;
 use tokio_test::*;
 
 use std::time::Duration;

tokio-test/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.4.0 (December 23, 2020)
+
+- Track `tokio` 1.0 release.
+
 # 0.3.0 (October 15, 2020)
 
 - Track `tokio` 0.3 release.

tokio-test/Cargo.toml

@@ -6,27 +6,29 @@ name = "tokio-test"
 # - Update doc url
 #   - Cargo.toml
 # - Update CHANGELOG.md.
-# - Create "v0.3.x" git tag.
-version = "0.3.0"
+# - Create "tokio-test-0.4.x" git tag.
+version = "0.4.0"
 edition = "2018"
 authors = ["Tokio Contributors <[email protected]>"]
 license = "MIT"
 repository = "https://github.com/tokio-rs/tokio"
 homepage = "https://tokio.rs"
-documentation = "https://docs.rs/tokio-test/0.3.0/tokio_test"
+documentation = "https://docs.rs/tokio-test/0.4.0/tokio_test"
 description = """
 Testing utilities for Tokio- and futures-based code
 """
 categories = ["asynchronous", "testing"]
 
 [dependencies]
-tokio = { version = "0.3.0", path = "../tokio", features = ["rt", "stream", "sync", "time", "test-util"] }
+tokio = { version = "1.0.0", path = "../tokio", features = ["rt", "sync", "time", "test-util"] }
+tokio-stream = { version = "0.1", path = "../tokio-stream" }
+async-stream = "0.3"
 
-bytes = "0.6.0"
+bytes = "1.0.0"
 futures-core = "0.3.0"
 
 [dev-dependencies]
-tokio = { version = "0.3.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
 futures-util = "0.3.0"
 
 [package.metadata.docs.rs]

tokio-test/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Tokio Contributors
+Copyright (c) 2020 Tokio Contributors
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

tokio-test/src/io.rs

@@ -22,8 +22,9 @@ use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
 use tokio::sync::mpsc;
 use tokio::time::{self, Duration, Instant, Sleep};
 
-use futures_core::ready;
+use futures_core::{ready, Stream};
 use std::collections::VecDeque;
+use std::fmt;
 use std::future::Future;
 use std::pin::Pin;
 use std::sync::Arc;
@@ -63,13 +64,13 @@ enum Action {
     WriteError(Option<Arc<io::Error>>),
 }
 
-#[derive(Debug)]
 struct Inner {
     actions: VecDeque<Action>,
     waiting: Option<Instant>,
-    sleep: Option<Sleep>,
+    sleep: Option<Pin<Box<Sleep>>>,
     read_wait: Option<Waker>,
-    rx: mpsc::UnboundedReceiver<Action>,
+    // rx: mpsc::UnboundedReceiver<Action>,
+    rx: Pin<Box<dyn Stream<Item = Action> + Send>>,
 }
 
 impl Builder {
@@ -184,7 +185,13 @@ impl Handle {
 
 impl Inner {
     fn new(actions: VecDeque<Action>) -> (Inner, Handle) {
-        let (tx, rx) = mpsc::unbounded_channel();
+        let (tx, mut rx) = mpsc::unbounded_channel();
+
+        let rx = Box::pin(async_stream::stream! {
+            while let Some(item) = rx.recv().await {
+                yield item;
+            }
+        });
 
         let inner = Inner {
             actions,
@@ -200,8 +207,6 @@ impl Inner {
     }
 
     fn poll_action(&mut self, cx: &mut task::Context<'_>) -> Poll<Option<Action>> {
-        use futures_core::stream::Stream;
-
         Pin::new(&mut self.rx).poll_next(cx)
     }
 
@@ -365,7 +370,7 @@ impl AsyncRead for Mock {
                 Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                     if let Some(rem) = self.inner.remaining_wait() {
                         let until = Instant::now() + rem;
-                        self.inner.sleep = Some(time::sleep_until(until));
+                        self.inner.sleep = Some(Box::pin(time::sleep_until(until)));
                     } else {
                         self.inner.read_wait = Some(cx.waker().clone());
                         return Poll::Pending;
@@ -410,7 +415,7 @@ impl AsyncWrite for Mock {
                 Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                     if let Some(rem) = self.inner.remaining_wait() {
                         let until = Instant::now() + rem;
-                        self.inner.sleep = Some(time::sleep_until(until));
+                        self.inner.sleep = Some(Box::pin(time::sleep_until(until)));
                     } else {
                         panic!("unexpected WouldBlock");
                     }
@@ -485,3 +490,9 @@ fn is_task_ctx() -> bool {
     r
 }
 */
+
+impl fmt::Debug for Inner {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Inner {{...}}")
+    }
+}

tokio-test/src/lib.rs

@@ -1,4 +1,4 @@
-#![doc(html_root_url = "https://docs.rs/tokio-test/0.3.0")]
+#![doc(html_root_url = "https://docs.rs/tokio-test/0.4.0")]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tokio-test/src/task.rs

@@ -9,7 +9,7 @@ use std::pin::Pin;
 use std::sync::{Arc, Condvar, Mutex};
 use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
 
-use tokio::stream::Stream;
+use tokio_stream::Stream;
 
 /// TODO: dox
 pub fn spawn<T>(task: T) -> Spawn<T> {

tokio-util/CHANGELOG.md

@@ -1,3 +1,42 @@
+# 0.6.3 (January 31, 2021)
+
+### Added
+
+- sync: add `ReusableBoxFuture` utility ([#3464])
+
+### Changed
+
+- sync: use `ReusableBoxFuture` for `PollSemaphore` ([#3463])
+- deps: remove `async-stream` dependency ([#3463])
+- deps: remove `tokio-stream` dependency ([#3487])
+
+# 0.6.2 (January 21, 2021)
+
+### Added
+
+- sync: add pollable `Semaphore` ([#3444])
+
+### Fixed
+
+- time: fix panics on updating `DelayQueue` entries ([#3270])
+
+# 0.6.1 (January 12, 2021)
+
+### Added
+
+- codec: `get_ref()`, `get_mut()`, `get_pin_mut()` and `into_inner()` for
+  `Framed`, `FramedRead`, `FramedWrite` and `StreamReader` ([#3364]).
+- codec: `write_buffer()` and `write_buffer_mut()` for `Framed` and
+  `FramedWrite` ([#3387]).
+
+# 0.6.0 (December 23, 2020)
+
+### Changed
+- depend on `tokio` 1.0.
+
+### Added
+- rt: add constructors to `TokioContext` (#3221).
+
 # 0.5.1 (December 3, 2020)
 
 ### Added
@@ -45,6 +84,13 @@
 
 - Initial release
 
+[#3487]: https://github.com/tokio-rs/tokio/pull/3487
+[#3464]: https://github.com/tokio-rs/tokio/pull/3464
+[#3463]: https://github.com/tokio-rs/tokio/pull/3463
+[#3444]: https://github.com/tokio-rs/tokio/pull/3444
+[#3387]: https://github.com/tokio-rs/tokio/pull/3387
+[#3364]: https://github.com/tokio-rs/tokio/pull/3364
+[#3270]: https://github.com/tokio-rs/tokio/pull/3270
 [#2326]: https://github.com/tokio-rs/tokio/pull/2326
 [#2215]: https://github.com/tokio-rs/tokio/pull/2215
 [#2198]: https://github.com/tokio-rs/tokio/pull/2198

tokio-util/Cargo.toml

@@ -6,14 +6,14 @@ name = "tokio-util"
 # - Update doc url
 #   - Cargo.toml
 # - Update CHANGELOG.md.
-# - Create "v0.2.x" git tag.
-version = "0.5.1"
+# - Create "tokio-util-0.6.x" git tag.
+version = "0.6.3"
 edition = "2018"
 authors = ["Tokio Contributors <[email protected]>"]
 license = "MIT"
 repository = "https://github.com/tokio-rs/tokio"
 homepage = "https://tokio.rs"
-documentation = "https://docs.rs/tokio-util/0.5.1/tokio_util"
+documentation = "https://docs.rs/tokio-util/0.6.3/tokio_util"
 description = """
 Additional utilities for working with Tokio.
 """
@@ -28,26 +28,31 @@ full = ["codec", "compat", "io", "time", "net", "rt"]
 
 net = ["tokio/net"]
 compat = ["futures-io",]
-codec = ["tokio/stream"]
+codec = []
 time = ["tokio/time","slab"]
 io = []
 rt = ["tokio/rt"]
 
-[dependencies]
-tokio = { version = "0.3.4", path = "../tokio" }
+__docs_rs = ["futures-util"]
 
-bytes = "0.6.0"
+[dependencies]
+tokio = { version = "1.0.0", features = ["sync"] }
+
+bytes = "1.0.0"
 futures-core = "0.3.0"
 futures-sink = "0.3.0"
 futures-io = { version = "0.3.0", optional = true }
+futures-util = { version = "0.3.0", optional = true }
 log = "0.4"
 pin-project-lite = "0.2.0"
 slab = { version = "0.4.1", optional = true } # Backs `DelayQueue`
 
 [dev-dependencies]
-tokio = { version = "0.3.0", path = "../tokio", features = ["full"] }
-tokio-test = { version = "0.3.0", path = "../tokio-test" }
+tokio = { version = "1.0.0", features = ["full"] }
+tokio-test = { version = "0.4.0" }
+tokio-stream = { version = "0.1" }
 
+async-stream = "0.3.0"
 futures = "0.3.0"
 futures-test = "0.3.5"
 

tokio-util/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Tokio Contributors
+Copyright (c) 2020 Tokio Contributors
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

tokio-util/src/codec/decoder.rs

@@ -153,7 +153,7 @@ pub trait Decoder {
     /// calling `split` on the [`Framed`] returned by this method, which will
     /// break them into separate objects, allowing them to interact more easily.
     ///
-    /// [`Stream`]: tokio::stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`Framed`]: crate::codec::Framed
     fn framed<T: AsyncRead + AsyncWrite + Sized>(self, io: T) -> Framed<T, Self>

tokio-util/src/codec/framed.rs

@@ -2,10 +2,8 @@ use crate::codec::decoder::Decoder;
 use crate::codec::encoder::Encoder;
 use crate::codec::framed_impl::{FramedImpl, RWFrames, ReadFrame, WriteFrame};
 
-use tokio::{
-    io::{AsyncRead, AsyncWrite},
-    stream::Stream,
-};
+use futures_core::Stream;
+use tokio::io::{AsyncRead, AsyncWrite};
 
 use bytes::BytesMut;
 use futures_sink::Sink;
@@ -22,7 +20,7 @@ pin_project! {
     /// You can create a `Framed` instance by using the [`Decoder::framed`] adapter, or
     /// by using the `new` function seen below.
     ///
-    /// [`Stream`]: tokio::stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`AsyncRead`]: tokio::io::AsyncRead
     /// [`Decoder::framed`]: crate::codec::Decoder::framed()
@@ -54,7 +52,7 @@ where
     /// calling [`split`] on the `Framed` returned by this method, which will
     /// break them into separate objects, allowing them to interact more easily.
     ///
-    /// [`Stream`]: tokio::stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`Decode`]: crate::codec::Decoder
     /// [`Encoder`]: crate::codec::Encoder
@@ -88,7 +86,7 @@ where
     /// calling [`split`] on the `Framed` returned by this method, which will
     /// break them into separate objects, allowing them to interact more easily.
     ///
-    /// [`Stream`]: tokio::stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`Decode`]: crate::codec::Decoder
     /// [`Encoder`]: crate::codec::Encoder
@@ -133,7 +131,7 @@ impl<T, U> Framed<T, U> {
     /// calling [`split`] on the `Framed` returned by this method, which will
     /// break them into separate objects, allowing them to interact more easily.
     ///
-    /// [`Stream`]: tokio::stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`Decoder`]: crate::codec::Decoder
     /// [`Encoder`]: crate::codec::Encoder
@@ -172,6 +170,16 @@ impl<T, U> Framed<T, U> {
         &mut self.inner.inner
     }
 
+    /// Returns a pinned mutable reference to the underlying I/O stream wrapped by
+    /// `Framed`.
+    ///
+    /// Note that care should be taken to not tamper with the underlying stream
+    /// of data coming in as it may corrupt the stream of frames otherwise
+    /// being worked with.
+    pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> {
+        self.project().inner.project().inner
+    }
+
     /// Returns a reference to the underlying codec wrapped by
     /// `Framed`.
     ///
@@ -200,6 +208,16 @@ impl<T, U> Framed<T, U> {
         &mut self.inner.state.read.buffer
     }
 
+    /// Returns a reference to the write buffer.
+    pub fn write_buffer(&self) -> &BytesMut {
+        &self.inner.state.write.buffer
+    }
+
+    /// Returns a mutable reference to the write buffer.
+    pub fn write_buffer_mut(&mut self) -> &mut BytesMut {
+        &mut self.inner.state.write.buffer
+    }
+
     /// Consumes the `Framed`, returning its underlying I/O stream.
     ///
     /// Note that care should be taken to not tamper with the underlying stream

tokio-util/src/codec/framed_impl.rs

@@ -1,10 +1,8 @@
 use crate::codec::decoder::Decoder;
 use crate::codec::encoder::Encoder;
 
-use tokio::{
-    io::{AsyncRead, AsyncWrite},
-    stream::Stream,
-};
+use futures_core::Stream;
+use tokio::io::{AsyncRead, AsyncWrite};
 
 use bytes::BytesMut;
 use futures_core::ready;

tokio-util/src/codec/framed_read.rs

@@ -1,7 +1,8 @@
 use crate::codec::framed_impl::{FramedImpl, ReadFrame};
 use crate::codec::Decoder;
 
-use tokio::{io::AsyncRead, stream::Stream};
+use futures_core::Stream;
+use tokio::io::AsyncRead;
 
 use bytes::BytesMut;
 use futures_sink::Sink;
@@ -13,7 +14,7 @@ use std::task::{Context, Poll};
 pin_project! {
     /// A [`Stream`] of messages decoded from an [`AsyncRead`].
     ///
-    /// [`Stream`]: tokio::stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`AsyncRead`]: tokio::io::AsyncRead
     pub struct FramedRead<T, D> {
         #[pin]
@@ -77,6 +78,16 @@ impl<T, D> FramedRead<T, D> {
         &mut self.inner.inner
     }
 
+    /// Returns a pinned mutable reference to the underlying I/O stream wrapped by
+    /// `FramedRead`.
+    ///
+    /// Note that care should be taken to not tamper with the underlying stream
+    /// of data coming in as it may corrupt the stream of frames otherwise
+    /// being worked with.
+    pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> {
+        self.project().inner.project().inner
+    }
+
     /// Consumes the `FramedRead`, returning its underlying I/O stream.
     ///
     /// Note that care should be taken to not tamper with the underlying stream

tokio-util/src/codec/framed_write.rs

@@ -1,8 +1,10 @@
 use crate::codec::encoder::Encoder;
 use crate::codec::framed_impl::{FramedImpl, WriteFrame};
 
-use tokio::{io::AsyncWrite, stream::Stream};
+use futures_core::Stream;
+use tokio::io::AsyncWrite;
 
+use bytes::BytesMut;
 use futures_sink::Sink;
 use pin_project_lite::pin_project;
 use std::fmt;
@@ -57,6 +59,16 @@ impl<T, E> FramedWrite<T, E> {
         &mut self.inner.inner
     }
 
+    /// Returns a pinned mutable reference to the underlying I/O stream wrapped by
+    /// `FramedWrite`.
+    ///
+    /// Note that care should be taken to not tamper with the underlying stream
+    /// of data coming in as it may corrupt the stream of frames otherwise
+    /// being worked with.
+    pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> {
+        self.project().inner.project().inner
+    }
+
     /// Consumes the `FramedWrite`, returning its underlying I/O stream.
     ///
     /// Note that care should be taken to not tamper with the underlying stream
@@ -75,6 +87,16 @@ impl<T, E> FramedWrite<T, E> {
     pub fn encoder_mut(&mut self) -> &mut E {
         &mut self.inner.codec
     }
+
+    /// Returns a reference to the write buffer.
+    pub fn write_buffer(&self) -> &BytesMut {
+        &self.inner.state.buffer
+    }
+
+    /// Returns a mutable reference to the write buffer.
+    pub fn write_buffer_mut(&mut self) -> &mut BytesMut {
+        &mut self.inner.state.buffer
+    }
 }
 
 // This impl just defers to the underlying FramedImpl

tokio-util/src/codec/length_delimited.rs

@@ -39,7 +39,7 @@
 //! Specifically, given the following:
 //!
 //! ```
-//! use tokio::prelude::*;
+//! use tokio::io::{AsyncRead, AsyncWrite};
 //! use tokio_util::codec::{Framed, LengthDelimitedCodec};
 //!
 //! use futures::SinkExt;

tokio-util/src/codec/mod.rs

@@ -1,18 +1,262 @@
 //! Adaptors from AsyncRead/AsyncWrite to Stream/Sink
 //!
-//! Raw I/O objects work with byte sequences, but higher-level code
-//! usually wants to batch these into meaningful chunks, called
-//! "frames".
+//! Raw I/O objects work with byte sequences, but higher-level code usually
+//! wants to batch these into meaningful chunks, called "frames".
 //!
-//! This module contains adapters to go from streams of bytes,
-//! [`AsyncRead`] and [`AsyncWrite`], to framed streams implementing
-//! [`Sink`] and [`Stream`].  Framed streams are also known as
-//! transports.
+//! This module contains adapters to go from streams of bytes, [`AsyncRead`] and
+//! [`AsyncWrite`], to framed streams implementing [`Sink`] and [`Stream`].
+//! Framed streams are also known as transports.
+//!
+//! # The Decoder trait
+//!
+//! A [`Decoder`] is used together with [`FramedRead`] or [`Framed`] to turn an
+//! [`AsyncRead`] into a [`Stream`]. The job of the decoder trait is to specify
+//! how sequences of bytes are turned into a sequence of frames, and to
+//! determine where the boundaries between frames are.  The job of the
+//! `FramedRead` is to repeatedly switch between reading more data from the IO
+//! resource, and asking the decoder whether we have received enough data to
+//! decode another frame of data.
+//!
+//! The main method on the `Decoder` trait is the [`decode`] method. This method
+//! takes as argument the data that has been read so far, and when it is called,
+//! it will be in one of the following situations:
+//!
+//!  1. The buffer contains less than a full frame.
+//!  2. The buffer contains exactly a full frame.
+//!  3. The buffer contains more than a full frame.
+//!
+//! In the first situation, the decoder should return `Ok(None)`.
+//!
+//! In the second situation, the decoder should clear the provided buffer and
+//! return `Ok(Some(the_decoded_frame))`.
+//!
+//! In the third situation, the decoder should use a method such as [`split_to`]
+//! or [`advance`] to modify the buffer such that the frame is removed from the
+//! buffer, but any data in the buffer after that frame should still remain in
+//! the buffer. The decoder should also return `Ok(Some(the_decoded_frame))` in
+//! this case.
+//!
+//! Finally the decoder may return an error if the data is invalid in some way.
+//! The decoder should _not_ return an error just because it has yet to receive
+//! a full frame.
+//!
+//! It is guaranteed that, from one call to `decode` to another, the provided
+//! buffer will contain the exact same data as before, except that if more data
+//! has arrived through the IO resource, that data will have been appended to
+//! the buffer.  This means that reading frames from a `FramedRead` is
+//! essentially equivalent to the following loop:
+//!
+//! ```no_run
+//! use tokio::io::AsyncReadExt;
+//! # // This uses async_stream to create an example that compiles.
+//! # fn foo() -> impl futures_core::Stream<Item = std::io::Result<bytes::BytesMut>> { async_stream::try_stream! {
+//! # use tokio_util::codec::Decoder;
+//! # let mut decoder = tokio_util::codec::BytesCodec::new();
+//! # let io_resource = &mut &[0u8, 1, 2, 3][..];
+//!
+//! let mut buf = bytes::BytesMut::new();
+//! loop {
+//!     // The read_buf call will append to buf rather than overwrite existing data.
+//!     let len = io_resource.read_buf(&mut buf).await?;
+//!
+//!     if len == 0 {
+//!         while let Some(frame) = decoder.decode_eof(&mut buf)? {
+//!             yield frame;
+//!         }
+//!         break;
+//!     }
+//!
+//!     while let Some(frame) = decoder.decode(&mut buf)? {
+//!         yield frame;
+//!     }
+//! }
+//! # }}
+//! ```
+//! The example above uses `yield` whenever the `Stream` produces an item.
+//!
+//! ## Example decoder
+//!
+//! As an example, consider a protocol that can be used to send strings where
+//! each frame is a four byte integer that contains the length of the frame,
+//! followed by that many bytes of string data. The decoder fails with an error
+//! if the string data is not valid utf-8 or too long.
+//!
+//! Such a decoder can be written like this:
+//! ```
+//! use tokio_util::codec::Decoder;
+//! use bytes::{BytesMut, Buf};
+//!
+//! struct MyStringDecoder {}
+//!
+//! const MAX: usize = 8 * 1024 * 1024;
+//!
+//! impl Decoder for MyStringDecoder {
+//!     type Item = String;
+//!     type Error = std::io::Error;
+//!
+//!     fn decode(
+//!         &mut self,
+//!         src: &mut BytesMut
+//!     ) -> Result<Option<Self::Item>, Self::Error> {
+//!         if src.len() < 4 {
+//!             // Not enough data to read length marker.
+//!             return Ok(None);
+//!         }
+//!
+//!         // Read length marker.
+//!         let mut length_bytes = [0u8; 4];
+//!         length_bytes.copy_from_slice(&src[..4]);
+//!         let length = u32::from_le_bytes(length_bytes) as usize;
+//!
+//!         // Check that the length is not too large to avoid a denial of
+//!         // service attack where the server runs out of memory.
+//!         if length > MAX {
+//!             return Err(std::io::Error::new(
+//!                 std::io::ErrorKind::InvalidData,
+//!                 format!("Frame of length {} is too large.", length)
+//!             ));
+//!         }
+//!
+//!         if src.len() < 4 + length {
+//!             // The full string has not yet arrived.
+//!             //
+//!             // We reserve more space in the buffer. This is not strictly
+//!             // necessary, but is a good idea performance-wise.
+//!             src.reserve(4 + length - src.len());
+//!
+//!             // We inform the Framed that we need more bytes to form the next
+//!             // frame.
+//!             return Ok(None);
+//!         }
+//!
+//!         // Use advance to modify src such that it no longer contains
+//!         // this frame.
+//!         let data = src[4..4 + length].to_vec();
+//!         src.advance(4 + length);
+//!
+//!         // Convert the data to a string, or fail if it is not valid utf-8.
+//!         match String::from_utf8(data) {
+//!             Ok(string) => Ok(Some(string)),
+//!             Err(utf8_error) => {
+//!                 Err(std::io::Error::new(
+//!                     std::io::ErrorKind::InvalidData,
+//!                     utf8_error.utf8_error(),
+//!                 ))
+//!             },
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! # The Encoder trait
+//!
+//! An [`Encoder`] is used together with [`FramedWrite`] or [`Framed`] to turn
+//! an [`AsyncWrite`] into a [`Sink`]. The job of the encoder trait is to
+//! specify how frames are turned into a sequences of bytes.  The job of the
+//! `FramedWrite` is to take the resulting sequence of bytes and write it to the
+//! IO resource.
+//!
+//! The main method on the `Encoder` trait is the [`encode`] method. This method
+//! takes an item that is being written, and a buffer to write the item to. The
+//! buffer may already contain data, and in this case, the encoder should append
+//! the new frame the to buffer rather than overwrite the existing data.
+//!
+//! It is guaranteed that, from one call to `encode` to another, the provided
+//! buffer will contain the exact same data as before, except that some of the
+//! data may have been removed from the front of the buffer. Writing to a
+//! `FramedWrite` is essentially equivalent to the following loop:
+//!
+//! ```no_run
+//! use tokio::io::AsyncWriteExt;
+//! use bytes::Buf; // for advance
+//! # use tokio_util::codec::Encoder;
+//! # async fn next_frame() -> bytes::Bytes { bytes::Bytes::new() }
+//! # async fn no_more_frames() { }
+//! # #[tokio::main] async fn main() -> std::io::Result<()> {
+//! # let mut io_resource = tokio::io::sink();
+//! # let mut encoder = tokio_util::codec::BytesCodec::new();
+//!
+//! const MAX: usize = 8192;
+//!
+//! let mut buf = bytes::BytesMut::new();
+//! loop {
+//!     tokio::select! {
+//!         num_written = io_resource.write(&buf), if !buf.is_empty() => {
+//!             buf.advance(num_written?);
+//!         },
+//!         frame = next_frame(), if buf.len() < MAX => {
+//!             encoder.encode(frame, &mut buf)?;
+//!         },
+//!         _ = no_more_frames() => {
+//!             io_resource.write_all(&buf).await?;
+//!             io_resource.shutdown().await?;
+//!             return Ok(());
+//!         },
+//!     }
+//! }
+//! # }
+//! ```
+//! Here the `next_frame` method corresponds to any frames you write to the
+//! `FramedWrite`. The `no_more_frames` method corresponds to closing the
+//! `FramedWrite` with [`SinkExt::close`].
+//!
+//! ## Example encoder
+//!
+//! As an example, consider a protocol that can be used to send strings where
+//! each frame is a four byte integer that contains the length of the frame,
+//! followed by that many bytes of string data. The encoder will fail if the
+//! string is too long.
+//!
+//! Such an encoder can be written like this:
+//! ```
+//! use tokio_util::codec::Encoder;
+//! use bytes::BytesMut;
+//!
+//! struct MyStringEncoder {}
+//!
+//! const MAX: usize = 8 * 1024 * 1024;
+//!
+//! impl Encoder<String> for MyStringEncoder {
+//!     type Error = std::io::Error;
+//!
+//!     fn encode(&mut self, item: String, dst: &mut BytesMut) -> Result<(), Self::Error> {
+//!         // Don't send a string if it is longer than the other end will
+//!         // accept.
+//!         if item.len() > MAX {
+//!             return Err(std::io::Error::new(
+//!                 std::io::ErrorKind::InvalidData,
+//!                 format!("Frame of length {} is too large.", item.len())
+//!             ));
+//!         }
+//!
+//!         // Convert the length into a byte array.
+//!         // The cast to u32 cannot overflow due to the length check above.
+//!         let len_slice = u32::to_le_bytes(item.len() as u32);
+//!
+//!         // Reserve space in the buffer.
+//!         dst.reserve(4 + item.len());
+//!
+//!         // Write the length and string to the buffer.
+//!         dst.extend_from_slice(&len_slice);
+//!         dst.extend_from_slice(item.as_bytes());
+//!         Ok(())
+//!     }
+//! }
+//! ```
 //!
 //! [`AsyncRead`]: tokio::io::AsyncRead
 //! [`AsyncWrite`]: tokio::io::AsyncWrite
-//! [`Stream`]: tokio::stream::Stream
+//! [`Stream`]: futures_core::Stream
 //! [`Sink`]: futures_sink::Sink
+//! [`SinkExt::close`]: https://docs.rs/futures/0.3/futures/sink/trait.SinkExt.html#method.close
+//! [`FramedRead`]: struct@crate::codec::FramedRead
+//! [`FramedWrite`]: struct@crate::codec::FramedWrite
+//! [`Framed`]: struct@crate::codec::Framed
+//! [`Decoder`]: trait@crate::codec::Decoder
+//! [`decode`]: fn@crate::codec::Decoder::decode
+//! [`encode`]: fn@crate::codec::Encoder::encode
+//! [`split_to`]: fn@bytes::BytesMut::split_to
+//! [`advance`]: fn@bytes::Buf::advance
 
 mod bytes_codec;
 pub use self::bytes_codec::BytesCodec;