chore: prepare Tokio 1.5.2 release

The previous commit forgot to update the version in Cargo.toml

.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,37 @@ 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 test-mem
+        run: cargo build --features rt-net --bin test-mem
+        working-directory: tests-integration
+
+      # Run with valgrind
+      - name: Run valgrind test-mem
+        run: valgrind  --leak-check=full --show-leak-kinds=all ./target/debug/test-mem
+
+      # Compile tests
+      - name: cargo build test-process-signal
+        run: cargo build --features rt-process-signal --bin test-process-signal
+        working-directory: tests-integration
+
+      # Run with valgrind
+      - name: Run valgrind test-process-signal
+        run: valgrind --leak-check=full --show-leak-kinds=all ./target/debug/test-process-signal
+
   test-unstable:
     name: test tokio full --unstable
     runs-on: ${{ matrix.os }}

CONTRIBUTING.md

@@ -124,17 +124,27 @@ arguments to many common cargo commands. This section lists some commonly needed
 commands.
 
 Some commands just need the `--all-features` argument:
+
 ```
 cargo build --all-features
 cargo check --all-features
 cargo test --all-features
 ```
+
 When building documentation normally, the markers that list the features
 required for various parts of Tokio are missing. To build the documentation
 correctly, use this command:
+
 ```
 RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
 ```
+
+There is currently a [bug in cargo] that means documentation cannot be built
+from the root of the workspace. If you `cd` into the `tokio` subdirectory the
+command shown above will work.
+
+[bug in cargo]: https://github.com/rust-lang/cargo/issues/9274
+
 The `cargo fmt` command does not work on the Tokio codebase. You can use the
 command below instead:
 
@@ -571,9 +581,8 @@ When releasing a new version of a crate, follow these steps:
 2. **Update Cargo metadata.** After releasing any path dependencies, update the
    `version` field in `Cargo.toml` to the new version, and the `documentation`
    field to the docs.rs URL of the new version.
-3. **Update other documentation links.** Update the `#![doc(html_root_url)]`
-   attribute in the crate's `lib.rs` and the "Documentation" link in the crate's
-   `README.md` to point to the docs.rs URL of the new version.
+3. **Update other documentation links.** Update the "Documentation" link in the
+   crate's `README.md` to point to the docs.rs URL of the new version.
 4. **Update the changelog for the crate.** Each crate in the Tokio repository
    has its own `CHANGELOG.md` in that crate's subdirectory. Any changes to that
    crate since the last release should be added to the changelog. Change

LICENSE

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

README.md

@@ -50,7 +50,15 @@ an asynchronous application.
 
 ## Example
 
-A basic TCP echo server with Tokio:
+A basic TCP echo server with Tokio.
+
+Make sure you activated the full features of the tokio crate on Cargo.toml:
+
+```text
+[dependencies]
+tokio = { version = "1.4.0", features = ["full"] }
+```
+Then, on your main.rs:
 
 ```rust,no_run
 use tokio::net::TcpListener;

examples/Cargo.toml

@@ -8,10 +8,9 @@ edition = "2018"
 # [dependencies] instead.
 [dev-dependencies]
 tokio = { version = "1.0.0", features = ["full", "tracing"] }
-tokio-util = { version = "0.6.1", features = ["full"] }
+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"] }
 bytes = "1.0.0"

examples/chat.rs

@@ -28,8 +28,8 @@
 
 use tokio::net::{TcpListener, TcpStream};
 use tokio::sync::{mpsc, Mutex};
-use tokio_stream::{Stream, StreamExt};
-use tokio_util::codec::{Framed, LinesCodec, LinesCodecError};
+use tokio_stream::StreamExt;
+use tokio_util::codec::{Framed, LinesCodec};
 
 use futures::SinkExt;
 use std::collections::HashMap;
@@ -37,9 +37,7 @@ use std::env;
 use std::error::Error;
 use std::io;
 use std::net::SocketAddr;
-use std::pin::Pin;
 use std::sync::Arc;
-use std::task::{Context, Poll};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
@@ -101,6 +99,9 @@ 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
@@ -124,7 +125,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: Pin<Box<dyn Stream<Item = String> + Send>>,
+    rx: Rx,
 }
 
 impl Shared {
@@ -156,58 +157,15 @@ impl Peer {
         let addr = lines.get_ref().peer_addr()?;
 
         // Create a channel for this peer
-        let (tx, mut rx) = mpsc::unbounded_channel();
+        let (tx, 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 })
     }
 }
 
-#[derive(Debug)]
-enum Message {
-    /// A message that should be broadcasted to others.
-    Broadcast(String),
-
-    /// A message that should be received by a client
-    Received(String),
-}
-
-// Peer implements `Stream` in a way that polls both the `Rx`, and `Framed` types.
-// A message is produced whenever an event is ready until the `Framed` stream returns `None`.
-impl Stream for Peer {
-    type Item = Result<Message, LinesCodecError>;
-
-    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
-        // First poll the `UnboundedReceiver`.
-
-        if let Poll::Ready(Some(v)) = Pin::new(&mut self.rx).poll_next(cx) {
-            return Poll::Ready(Some(Ok(Message::Received(v))));
-        }
-
-        // Secondly poll the `Framed` stream.
-        let result: Option<_> = futures::ready!(Pin::new(&mut self.lines).poll_next(cx));
-
-        Poll::Ready(match result {
-            // We've received a message we should broadcast to others.
-            Some(Ok(message)) => Some(Ok(Message::Broadcast(message))),
-
-            // An error occurred.
-            Some(Err(e)) => Some(Err(e)),
-
-            // The stream has been exhausted.
-            None => None,
-        })
-    }
-}
-
 /// Process an individual chat client
 async fn process(
     state: Arc<Mutex<Shared>>,
@@ -241,28 +199,32 @@ async fn process(
     }
 
     // Process incoming messages until our stream is exhausted by a disconnect.
-    while let Some(result) = peer.next().await {
-        match result {
-            // A message was received from the current user, we should
-            // broadcast this message to the other users.
-            Ok(Message::Broadcast(msg)) => {
-                let mut state = state.lock().await;
-                let msg = format!("{}: {}", username, msg);
-
-                state.broadcast(addr, &msg).await;
-            }
-            // A message was received from a peer. Send it to the
-            // current user.
-            Ok(Message::Received(msg)) => {
+    loop {
+        tokio::select! {
+            // A message was received from a peer. Send it to the current user.
+            Some(msg) = peer.rx.recv() => {
                 peer.lines.send(&msg).await?;
             }
-            Err(e) => {
-                tracing::error!(
-                    "an error occurred while processing messages for {}; error = {:?}",
-                    username,
-                    e
-                );
-            }
+            result = peer.lines.next() => match result {
+                // A message was received from the current user, we should
+                // broadcast this message to the other users.
+                Some(Ok(msg)) => {
+                    let mut state = state.lock().await;
+                    let msg = format!("{}: {}", username, msg);
+
+                    state.broadcast(addr, &msg).await;
+                }
+                // An error occurred.
+                Some(Err(e)) => {
+                    tracing::error!(
+                        "an error occurred while processing messages for {}; error = {:?}",
+                        username,
+                        e
+                    );
+                }
+                // The stream has been exhausted.
+                None => break,
+            },
         }
     }
 

tests-build/tests/fail/macros_invalid_input.rs

@@ -12,12 +12,27 @@ async fn main_attr_has_path_args() {}
 #[tokio::test]
 fn test_is_not_async() {}
 
-#[tokio::test]
-async fn test_fn_has_args(_x: u8) {}
-
 #[tokio::test(foo)]
 async fn test_attr_has_args() {}
 
+#[tokio::test(foo = 123)]
+async fn test_unexpected_attr() {}
+
+#[tokio::test(flavor = 123)]
+async fn test_flavor_not_string() {}
+
+#[tokio::test(flavor = "foo")]
+async fn test_unknown_flavor() {}
+
+#[tokio::test(flavor = "multi_thread", start_paused = false)]
+async fn test_multi_thread_with_start_paused() {}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = "foo")]
+async fn test_worker_threads_not_int() {}
+
+#[tokio::test(flavor = "current_thread", worker_threads = 4)]
+async fn test_worker_threads_and_current_thread() {}
+
 #[tokio::test]
 #[test]
 async fn test_has_second_test_attr() {}

tests-build/tests/fail/macros_invalid_input.stderr

@@ -1,10 +1,10 @@
-error: the async keyword is missing from the function declaration
+error: the `async` keyword is missing from the function declaration
  --> $DIR/macros_invalid_input.rs:4:1
   |
 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)]
@@ -16,26 +16,56 @@ error: Must have specified ident
 9 | #[tokio::main(threadpool::bar)]
   |               ^^^^^^^^^^^^^^^
 
-error: the async keyword is missing from the function declaration
+error: the `async` keyword is missing from the function declaration
   --> $DIR/macros_invalid_input.rs:13:1
    |
 13 | fn test_is_not_async() {}
    | ^^
 
-error: the test function cannot accept arguments
-  --> $DIR/macros_invalid_input.rs:16:27
+error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`, `start_paused`
+  --> $DIR/macros_invalid_input.rs:15:15
    |
-16 | async fn test_fn_has_args(_x: u8) {}
-   |                           ^^^^^^
-
-error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`
-  --> $DIR/macros_invalid_input.rs:18:15
-   |
-18 | #[tokio::test(foo)]
+15 | #[tokio::test(foo)]
    |               ^^^
 
-error: second test attribute is supplied
-  --> $DIR/macros_invalid_input.rs:22:1
+error: Unknown attribute foo is specified; expected one of: `flavor`, `worker_threads`, `start_paused`
+  --> $DIR/macros_invalid_input.rs:18:15
    |
-22 | #[test]
+18 | #[tokio::test(foo = 123)]
+   |               ^^^^^^^^^
+
+error: Failed to parse value of `flavor` as string.
+  --> $DIR/macros_invalid_input.rs:21:24
+   |
+21 | #[tokio::test(flavor = 123)]
+   |                        ^^^
+
+error: No such runtime flavor `foo`. The runtime flavors are `current_thread` and `multi_thread`.
+  --> $DIR/macros_invalid_input.rs:24:24
+   |
+24 | #[tokio::test(flavor = "foo")]
+   |                        ^^^^^
+
+error: The `start_paused` option requires the `current_thread` runtime flavor. Use `#[tokio::test(flavor = "current_thread")]`
+  --> $DIR/macros_invalid_input.rs:27:55
+   |
+27 | #[tokio::test(flavor = "multi_thread", start_paused = false)]
+   |                                                       ^^^^^
+
+error: Failed to parse value of `worker_threads` as integer.
+  --> $DIR/macros_invalid_input.rs:30:57
+   |
+30 | #[tokio::test(flavor = "multi_thread", worker_threads = "foo")]
+   |                                                         ^^^^^
+
+error: The `worker_threads` option requires the `multi_thread` runtime flavor. Use `#[tokio::test(flavor = "multi_thread")]`
+  --> $DIR/macros_invalid_input.rs:33:59
+   |
+33 | #[tokio::test(flavor = "current_thread", worker_threads = 4)]
+   |                                                           ^
+
+error: second test attribute is supplied
+  --> $DIR/macros_invalid_input.rs:37:1
+   |
+37 | #[test]
    | ^^^^^^^

tests-build/tests/macros.rs

@@ -2,6 +2,9 @@
 fn compile_fail_full() {
     let t = trybuild::TestCases::new();
 
+    #[cfg(feature = "full")]
+    t.pass("tests/pass/forward_args_and_output.rs");
+
     #[cfg(feature = "full")]
     t.compile_fail("tests/fail/macros_invalid_input.rs");
 

tests-build/tests/pass/forward_args_and_output.rs

@@ -0,0 +1,13 @@
+use tests_build::tokio;
+
+fn main() {}
+
+// arguments and output type is forwarded so other macros can access them
+
+#[tokio::test]
+async fn test_fn_has_args(_x: u8) {}
+
+#[tokio::test]
+async fn test_has_output() -> Result<(), Box<dyn std::error::Error>> {
+    Ok(())
+}

tests-integration/Cargo.toml

@@ -5,7 +5,23 @@ authors = ["Tokio Contributors <[email protected]>"]
 edition = "2018"
 publish = false
 
+[[bin]]
+name = "test-cat"
+
+[[bin]]
+name = "test-mem"
+required-features = ["rt-net"]
+
+[[bin]]
+name = "test-process-signal"
+required-features = ["rt-process-signal"]
+
 [features]
+# For mem check
+rt-net = ["tokio/rt", "tokio/rt-multi-thread", "tokio/net"]
+# For test-process-signal
+rt-process-signal = ["rt", "tokio/process", "tokio/signal"]
+
 full = [
     "macros",
     "rt",
@@ -23,6 +39,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/src/bin/test-process-signal.rs

@@ -0,0 +1,11 @@
+// https://github.com/tokio-rs/tokio/issues/3550
+fn main() {
+    for _ in 0..1000 {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+
+        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,7 @@
+# 1.1.0 (February 5, 2021)
+
+- add `start_paused` option to macros ([#3492])
+
 # 1.0.0 (December 23, 2020)
 
 - track `tokio` 1.0 release.
@@ -55,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

@@ -2,18 +2,17 @@
 name = "tokio-macros"
 # When releasing to crates.io:
 # - Remove path dependencies
-# - Update html_root_url.
 # - Update doc url
 #   - Cargo.toml
 # - Update CHANGELOG.md.
 # - Create "tokio-macros-1.0.x" git tag.
-version = "1.0.0"
+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/1.0.0/tokio_macros"
+documentation = "https://docs.rs/tokio-macros/1.1.0/tokio_macros"
 description = """
 Tokio's proc macros.
 """

tokio-macros/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Tokio Contributors
+Copyright (c) 2021 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

@@ -1,7 +1,6 @@
 use proc_macro::TokenStream;
 use proc_macro2::Span;
 use quote::quote;
-use syn::spanned::Spanned;
 
 #[derive(Clone, Copy, PartialEq)]
 enum RuntimeFlavor {
@@ -25,6 +24,7 @@ impl RuntimeFlavor {
 struct FinalConfig {
     flavor: RuntimeFlavor,
     worker_threads: Option<usize>,
+    start_paused: Option<bool>,
 }
 
 struct Configuration {
@@ -32,6 +32,8 @@ struct Configuration {
     default_flavor: RuntimeFlavor,
     flavor: Option<RuntimeFlavor>,
     worker_threads: Option<(usize, Span)>,
+    start_paused: Option<(bool, Span)>,
+    is_test: bool,
 }
 
 impl Configuration {
@@ -44,6 +46,8 @@ impl Configuration {
             },
             flavor: None,
             worker_threads: None,
+            start_paused: None,
+            is_test,
         }
     }
 
@@ -79,31 +83,67 @@ 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 macro_name(&self) -> &'static str {
+        if self.is_test {
+            "tokio::test"
+        } else {
+            "tokio::main"
+        }
+    }
+
     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))) => {
+                let msg = format!(
+                    "The `worker_threads` option requires the `multi_thread` runtime flavor. Use `#[{}(flavor = \"multi_thread\")]`",
+                    self.macro_name(),
+                );
+                return Err(syn::Error::new(worker_threads_span, msg));
+            }
+            (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))) => {
+                let msg = format!(
+                    "The `start_paused` option requires the `current_thread` runtime flavor. Use `#[{}(flavor = \"current_thread\")]`",
+                    self.macro_name(),
+                );
+                return Err(syn::Error::new(start_paused_span, msg));
+            }
+            (CurrentThread, Some((start_paused, _))) => Some(start_paused),
+            (_, None) => None,
+        };
+
+        Ok(FinalConfig {
+            flavor,
+            worker_threads,
+            start_paused,
+        })
     }
 }
 
@@ -113,12 +153,12 @@ fn parse_int(int: syn::Lit, span: Span, field: &str) -> Result<usize, syn::Error
             Ok(value) => Ok(value),
             Err(e) => Err(syn::Error::new(
                 span,
-                format!("Failed to parse {} as integer: {}", field, e),
+                format!("Failed to parse value of `{}` as integer: {}", field, e),
             )),
         },
         _ => Err(syn::Error::new(
             span,
-            format!("Failed to parse {} as integer.", field),
+            format!("Failed to parse value of `{}` as integer.", field),
         )),
     }
 }
@@ -129,7 +169,17 @@ fn parse_string(int: syn::Lit, span: Span, field: &str) -> Result<String, syn::E
         syn::Lit::Verbatim(s) => Ok(s.to_string()),
         _ => Err(syn::Error::new(
             span,
-            format!("Failed to parse {} as string.", field),
+            format!("Failed to parse value of `{}` as string.", field),
+        )),
+    }
+}
+
+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 value of `{}` as bool.", field),
         )),
     }
 }
@@ -140,24 +190,13 @@ fn parse_knobs(
     is_test: bool,
     rt_multi_thread: bool,
 ) -> Result<TokenStream, syn::Error> {
-    let sig = &mut input.sig;
-    let body = &input.block;
-    let attrs = &input.attrs;
-    let vis = input.vis;
-
-    if sig.asyncness.is_none() {
-        let msg = "the async keyword is missing from the function declaration";
-        return Err(syn::Error::new_spanned(sig.fn_token, msg));
+    if input.sig.asyncness.take().is_none() {
+        let msg = "the `async` keyword is missing from the function declaration";
+        return Err(syn::Error::new_spanned(input.sig.fn_token, msg));
     }
 
-    sig.asyncness = None;
-
-    let macro_name = if is_test {
-        "tokio::test"
-    } else {
-        "tokio::main"
-    };
     let mut config = Configuration::new(is_test, rt_multi_thread);
+    let macro_name = config.macro_name();
 
     for arg in args {
         match arg {
@@ -169,17 +208,32 @@ fn parse_knobs(
                 }
                 match ident.unwrap().to_string().to_lowercase().as_str() {
                     "worker_threads" => {
-                        config.set_worker_threads(namevalue.lit.clone(), namevalue.span())?;
+                        config.set_worker_threads(
+                            namevalue.lit.clone(),
+                            syn::spanned::Spanned::span(&namevalue.lit),
+                        )?;
                     }
                     "flavor" => {
-                        config.set_flavor(namevalue.lit.clone(), namevalue.span())?;
+                        config.set_flavor(
+                            namevalue.lit.clone(),
+                            syn::spanned::Spanned::span(&namevalue.lit),
+                        )?;
+                    }
+                    "start_paused" => {
+                        config.set_start_paused(
+                            namevalue.lit.clone(),
+                            syn::spanned::Spanned::span(&namevalue.lit),
+                        )?;
                     }
                     "core_threads" => {
                         let msg = "Attribute `core_threads` is renamed to `worker_threads`";
                         return Err(syn::Error::new_spanned(namevalue, msg));
                     }
                     name => {
-                        let msg = format!("Unknown attribute {} is specified; expected one of: `flavor`, `worker_threads`", name);
+                        let msg = format!(
+                            "Unknown attribute {} is specified; expected one of: `flavor`, `worker_threads`, `start_paused`",
+                            name,
+                        );
                         return Err(syn::Error::new_spanned(namevalue, msg));
                     }
                 }
@@ -204,11 +258,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,21 +289,21 @@ 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 {
-            quote! {
-                #[::core::prelude::v1::test]
-            }
-        } else {
-            quote! {}
+    let header = if is_test {
+        quote! {
+            #[::core::prelude::v1::test]
         }
+    } else {
+        quote! {}
     };
 
-    let result = quote! {
-        #header
-        #(#attrs)*
-        #vis #sig {
+    let body = &input.block;
+    input.block = syn::parse_quote! {
+        {
             #rt
                 .enable_all()
                 .build()
@@ -258,6 +312,11 @@ fn parse_knobs(
         }
     };
 
+    let result = quote! {
+        #header
+        #input
+    };
+
     Ok(result.into())
 }
 
@@ -289,12 +348,5 @@ pub(crate) fn test(args: TokenStream, item: TokenStream, rt_multi_thread: bool)
         }
     }
 
-    if !input.sig.inputs.is_empty() {
-        let msg = "the test function cannot accept arguments";
-        return syn::Error::new_spanned(&input.sig.inputs, msg)
-            .to_compile_error()
-            .into();
-    }
-
     parse_knobs(input, args, true, rt_multi_thread).unwrap_or_else(|e| e.to_compile_error().into())
 }

tokio-macros/src/lib.rs

@@ -1,4 +1,3 @@
-#![doc(html_root_url = "https://docs.rs/tokio-macros/1.0.0")]
 #![allow(clippy::needless_doctest_main)]
 #![warn(
     missing_debug_implementations,
@@ -144,6 +143,32 @@ 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 that `start_paused` requires the `test-util` feature to be enabled.
+///
 /// ### NOTE:
 ///
 /// If you rename the Tokio crate in your dependencies this macro will not work.
@@ -225,6 +250,17 @@ 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 that `start_paused` requires the `test-util` feature to be enabled.
+///
 /// ### NOTE:
 ///
 /// If you rename the Tokio crate in your dependencies this macro will not work.

tokio-stream/CHANGELOG.md

@@ -1,8 +1,42 @@
+# 0.1.5 (March 20, 2021)
+
+### Fixed
+
+- stream: documentation note for throttle `Unpin` ([#3600])
+
+[#3600]: https://github.com/tokio-rs/tokio/pull/3600
+
+# 0.1.4 (March 9, 2021)
+
+Added
+
+- signal: add `Signal` wrapper ([#3510])
+
+Fixed
+
+- stream: remove duplicate `doc_cfg` declaration ([#3561])
+- sync: yield initial value in `WatchStream` ([#3576])
+
+[#3510]: https://github.com/tokio-rs/tokio/pull/3510
+[#3561]: https://github.com/tokio-rs/tokio/pull/3561
+[#3576]: https://github.com/tokio-rs/tokio/pull/3576
+
+# 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)
+ - docs: fix some wrappers missing in documentation ([#3378])
+
+[#3378]: https://github.com/tokio-rs/tokio/pull/3378
 
 # 0.1.1 (January 4, 2021)
 

tokio-stream/Cargo.toml

@@ -2,18 +2,17 @@
 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.2"
+version = "0.1.5"
 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.2/tokio_stream"
+documentation = "https://docs.rs/tokio-stream/0.1.5/tokio_stream"
 description = """
 Utilities to work with `Stream` and `tokio`.
 """
@@ -25,19 +24,22 @@ time = ["tokio/time"]
 net = ["tokio/net"]
 io-util = ["tokio/io-util"]
 fs = ["tokio/fs"]
+sync = ["tokio/sync", "tokio-util"]
+signal = ["tokio/signal"]
 
 [dependencies]
 futures-core = { version = "0.3.0" }
 pin-project-lite = "0.2.0"
-tokio = { version = "1.0", features = ["sync"] }
+tokio = { version = "1.2.0", path = "../tokio", features = ["sync"] }
+tokio-util = { version = "0.6.3", optional = true }
 
 [dev-dependencies]
-tokio = { version = "1.0", features = ["full", "test-util"] }
-tokio-test = { path = "../tokio-test" }
+tokio = { version = "1.2.0", path = "../tokio", features = ["full", "test-util"] }
 async-stream = "0.3"
+tokio-test = { path = "../tokio-test" }
 futures = { version = "0.3", default-features = false }
 
-proptest = "0.10.0"
+proptest = "1"
 
 [package.metadata.docs.rs]
 all-features = true

tokio-stream/LICENSE

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

tokio-stream/src/lib.rs

@@ -1,4 +1,3 @@
-#![doc(html_root_url = "https://docs.rs/tokio-stream/0.1.2")]
 #![allow(
     clippy::cognitive_complexity,
     clippy::large_enum_variant,
@@ -10,18 +9,12 @@
     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.
 //!

tokio-stream/src/macros.rs

@@ -38,6 +38,26 @@ macro_rules! cfg_time {
     }
 }
 
+macro_rules! cfg_sync {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "sync")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
+            $item
+        )*
+    }
+}
+
+macro_rules! cfg_signal {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "signal")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "signal")))]
+            $item
+        )*
+    }
+}
+
 macro_rules! ready {
     ($e:expr $(,)?) => {
         match $e {

tokio-stream/src/stream_ext/all.rs

@@ -38,18 +38,21 @@ where
 
     fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
         let me = self.project();
-        let next = futures_core::ready!(Pin::new(me.stream).poll_next(cx));
+        let mut stream = Pin::new(me.stream);
 
-        match next {
-            Some(v) => {
-                if !(me.f)(v) {
-                    Poll::Ready(false)
-                } else {
-                    cx.waker().wake_by_ref();
-                    Poll::Pending
+        // Take a maximum of 32 items from the stream before yielding.
+        for _ in 0..32 {
+            match futures_core::ready!(stream.as_mut().poll_next(cx)) {
+                Some(v) => {
+                    if !(me.f)(v) {
+                        return Poll::Ready(false);
+                    }
                 }
+                None => return Poll::Ready(true),
             }
-            None => Poll::Ready(true),
         }
+
+        cx.waker().wake_by_ref();
+        Poll::Pending
     }
 }

tokio-stream/src/stream_ext/any.rs

@@ -38,18 +38,21 @@ where
 
     fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
         let me = self.project();
-        let next = futures_core::ready!(Pin::new(me.stream).poll_next(cx));
+        let mut stream = Pin::new(me.stream);
 
-        match next {
-            Some(v) => {
-                if (me.f)(v) {
-                    Poll::Ready(true)
-                } else {
-                    cx.waker().wake_by_ref();
-                    Poll::Pending
+        // Take a maximum of 32 items from the stream before yielding.
+        for _ in 0..32 {
+            match futures_core::ready!(stream.as_mut().poll_next(cx)) {
+                Some(v) => {
+                    if (me.f)(v) {
+                        return Poll::Ready(true);
+                    }
                 }
+                None => return Poll::Ready(false),
             }
-            None => Poll::Ready(false),
         }
+
+        cx.waker().wake_by_ref();
+        Poll::Pending
     }
 }

tokio-stream/src/stream_ext/throttle.rs

@@ -23,7 +23,8 @@ where
 }
 
 pin_project! {
-    /// Stream for the [`throttle`](throttle) function.
+    /// Stream for the [`throttle`](throttle) function. This object is `!Unpin`. If you need it to
+    /// implement `Unpin` you can pin your throttle like this: `Box::pin(your_throttle)`.
     #[derive(Debug)]
     #[must_use = "streams do nothing unless polled"]
     pub struct Throttle<T> {

tokio-stream/src/wrappers.rs

@@ -1,4 +1,20 @@
 //! Wrappers for Tokio types that implement `Stream`.
+//!
+#![cfg_attr(
+    unix,
+    doc = "You are viewing documentation built under unix. To view windows-specific wrappers, change to the `x86_64-pc-windows-msvc` platform."
+)]
+#![cfg_attr(
+    windows,
+    doc = "You are viewing documentation built under windows. To view unix-specific wrappers, change to the `x86_64-unknown-linux-gnu` platform."
+)]
+
+/// Error types for the wrappers.
+pub mod errors {
+    cfg_sync! {
+        pub use crate::wrappers::broadcast::BroadcastStreamRecvError;
+    }
+}
 
 mod mpsc_bounded;
 pub use mpsc_bounded::ReceiverStream;
@@ -6,6 +22,26 @@ 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_signal! {
+    #[cfg(unix)]
+    mod signal_unix;
+    #[cfg(unix)]
+    pub use signal_unix::SignalStream;
+
+    #[cfg(windows)]
+    mod signal_windows;
+    #[cfg(windows)]
+    pub use signal_windows::{CtrlCStream, CtrlBreakStream};
+}
+
 cfg_time! {
     mod interval;
     pub use interval::IntervalStream;

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/signal_unix.rs

@@ -0,0 +1,46 @@
+use crate::Stream;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::signal::unix::Signal;
+
+/// A wrapper around [`Signal`] that implements [`Stream`].
+///
+/// [`Signal`]: struct@tokio::signal::unix::Signal
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(all(unix, feature = "signal"))))]
+pub struct SignalStream {
+    inner: Signal,
+}
+
+impl SignalStream {
+    /// Create a new `SignalStream`.
+    pub fn new(interval: Signal) -> Self {
+        Self { inner: interval }
+    }
+
+    /// Get back the inner `Signal`.
+    pub fn into_inner(self) -> Signal {
+        self.inner
+    }
+}
+
+impl Stream for SignalStream {
+    type Item = ();
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<()>> {
+        self.inner.poll_recv(cx)
+    }
+}
+
+impl AsRef<Signal> for SignalStream {
+    fn as_ref(&self) -> &Signal {
+        &self.inner
+    }
+}
+
+impl AsMut<Signal> for SignalStream {
+    fn as_mut(&mut self) -> &mut Signal {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/signal_windows.rs

@@ -0,0 +1,88 @@
+use crate::Stream;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::signal::windows::{CtrlBreak, CtrlC};
+
+/// A wrapper around [`CtrlC`] that implements [`Stream`].
+///
+/// [`CtrlC`]: struct@tokio::signal::windows::CtrlC
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(all(windows, feature = "signal"))))]
+pub struct CtrlCStream {
+    inner: CtrlC,
+}
+
+impl CtrlCStream {
+    /// Create a new `CtrlCStream`.
+    pub fn new(interval: CtrlC) -> Self {
+        Self { inner: interval }
+    }
+
+    /// Get back the inner `CtrlC`.
+    pub fn into_inner(self) -> CtrlC {
+        self.inner
+    }
+}
+
+impl Stream for CtrlCStream {
+    type Item = ();
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<()>> {
+        self.inner.poll_recv(cx)
+    }
+}
+
+impl AsRef<CtrlC> for CtrlCStream {
+    fn as_ref(&self) -> &CtrlC {
+        &self.inner
+    }
+}
+
+impl AsMut<CtrlC> for CtrlCStream {
+    fn as_mut(&mut self) -> &mut CtrlC {
+        &mut self.inner
+    }
+}
+
+/// A wrapper around [`CtrlBreak`] that implements [`Stream`].
+///
+/// [`CtrlBreak`]: struct@tokio::signal::windows::CtrlBreak
+/// [`Stream`]: trait@crate::Stream
+#[derive(Debug)]
+#[cfg_attr(docsrs, doc(cfg(all(windows, feature = "signal"))))]
+pub struct CtrlBreakStream {
+    inner: CtrlBreak,
+}
+
+impl CtrlBreakStream {
+    /// Create a new `CtrlBreakStream`.
+    pub fn new(interval: CtrlBreak) -> Self {
+        Self { inner: interval }
+    }
+
+    /// Get back the inner `CtrlBreak`.
+    pub fn into_inner(self) -> CtrlBreak {
+        self.inner
+    }
+}
+
+impl Stream for CtrlBreakStream {
+    type Item = ();
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<()>> {
+        self.inner.poll_recv(cx)
+    }
+}
+
+impl AsRef<CtrlBreak> for CtrlBreakStream {
+    fn as_ref(&self) -> &CtrlBreak {
+        &self.inner
+    }
+}
+
+impl AsMut<CtrlBreak> for CtrlBreakStream {
+    fn as_mut(&mut self) -> &mut CtrlBreak {
+        &mut self.inner
+    }
+}

tokio-stream/src/wrappers/watch.rs

@@ -0,0 +1,96 @@
+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`].
+///
+/// This stream will always start by yielding the current value when the WatchStream is polled,
+/// regardles of whether it was the initial value or sent afterwards.
+///
+/// # Examples
+///
+/// ```
+/// # #[tokio::main]
+/// # async fn main() {
+/// use tokio_stream::{StreamExt, wrappers::WatchStream};
+/// use tokio::sync::watch;
+///
+/// let (tx, rx) = watch::channel("hello");
+/// let mut rx = WatchStream::new(rx);
+///
+/// assert_eq!(rx.next().await, Some("hello"));
+///
+/// tx.send("goodbye").unwrap();
+/// assert_eq!(rx.next().await, Some("goodbye"));
+/// # }
+/// ```
+///
+/// ```
+/// # #[tokio::main]
+/// # async fn main() {
+/// use tokio_stream::{StreamExt, wrappers::WatchStream};
+/// use tokio::sync::watch;
+///
+/// let (tx, rx) = watch::channel("hello");
+/// let mut rx = WatchStream::new(rx);
+///
+/// tx.send("goodbye").unwrap();
+/// assert_eq!(rx.next().await, Some("goodbye"));
+/// # }
+/// ```
+///
+/// [`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(async move { (Ok(()), 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-test/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.4.1 (March 10, 2021)
+
+- Fix `io::Mock` to be `Send` and `Sync` ([#3594])
+
+[#3594]: https://github.com/tokio-rs/tokio/pull/3594
+
 # 0.4.0 (December 23, 2020)
 
 - Track `tokio` 1.0 release.

tokio-test/Cargo.toml

@@ -2,25 +2,24 @@
 name = "tokio-test"
 # When releasing to crates.io:
 # - Remove path dependencies
-# - Update html_root_url.
 # - Update doc url
 #   - Cargo.toml
 # - Update CHANGELOG.md.
 # - Create "tokio-test-0.4.x" git tag.
-version = "0.4.0"
+version = "0.4.1"
 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.4.0/tokio_test"
+documentation = "https://docs.rs/tokio-test/0.4.1/tokio_test"
 description = """
 Testing utilities for Tokio- and futures-based code
 """
 categories = ["asynchronous", "testing"]
 
 [dependencies]
-tokio = { version = "1.0.0", path = "../tokio", features = ["rt", "sync", "time", "test-util"] }
+tokio = { version = "1.2.0", path = "../tokio", features = ["rt", "sync", "time", "test-util"] }
 tokio-stream = { version = "0.1", path = "../tokio-stream" }
 async-stream = "0.3"
 
@@ -28,7 +27,7 @@ bytes = "1.0.0"
 futures-core = "0.3.0"
 
 [dev-dependencies]
-tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.2.0", path = "../tokio", features = ["full"] }
 futures-util = "0.3.0"
 
 [package.metadata.docs.rs]

tokio-test/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Tokio Contributors
+Copyright (c) 2021 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

@@ -21,6 +21,7 @@
 use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
 use tokio::sync::mpsc;
 use tokio::time::{self, Duration, Instant, Sleep};
+use tokio_stream::wrappers::UnboundedReceiverStream;
 
 use futures_core::{ready, Stream};
 use std::collections::VecDeque;
@@ -69,8 +70,7 @@ struct Inner {
     waiting: Option<Instant>,
     sleep: Option<Pin<Box<Sleep>>>,
     read_wait: Option<Waker>,
-    // rx: mpsc::UnboundedReceiver<Action>,
-    rx: Pin<Box<dyn Stream<Item = Action> + Send>>,
+    rx: UnboundedReceiverStream<Action>,
 }
 
 impl Builder {
@@ -185,13 +185,9 @@ impl Handle {
 
 impl Inner {
     fn new(actions: VecDeque<Action>) -> (Inner, Handle) {
-        let (tx, mut rx) = mpsc::unbounded_channel();
+        let (tx, rx) = mpsc::unbounded_channel();
 
-        let rx = Box::pin(async_stream::stream! {
-            while let Some(item) = rx.recv().await {
-                yield item;
-            }
-        });
+        let rx = UnboundedReceiverStream::new(rx);
 
         let inner = Inner {
             actions,

tokio-test/src/lib.rs

@@ -1,4 +1,3 @@
-#![doc(html_root_url = "https://docs.rs/tokio-test/0.4.0")]
 #![warn(
     missing_debug_implementations,
     missing_docs,
@@ -22,9 +21,9 @@ pub mod task;
 /// future completes.
 ///
 /// For more information, see the documentation for
-/// [`tokio::runtime::current_thread::Runtime::block_on`][runtime-block-on].
+/// [`tokio::runtime::Runtime::block_on`][runtime-block-on].
 ///
-/// [runtime-block-on]: https://docs.rs/tokio/0.2.0-alpha.2/tokio/runtime/current_thread/struct.Runtime.html#method.block_on
+/// [runtime-block-on]: https://docs.rs/tokio/1.3.0/tokio/runtime/struct.Runtime.html#method.block_on
 pub fn block_on<F: std::future::Future>(future: F) -> F::Output {
     use tokio::runtime;
 

tokio-util/CHANGELOG.md

@@ -1,4 +1,66 @@
-# 0.6.1 (January 12, 2020)
+# 0.6.6 (April 12, 2021)
+
+### Added
+
+- util: makes `Framed` and `FramedStream` resumable after eof ([#3272])
+- util: add `PollSemaphore::{add_permits, available_permits}` ([#3683])
+
+### Fixed
+
+- chore: avoid allocation if `PollSemaphore` is unused ([#3634])
+
+[#3272]: https://github.com/tokio-rs/tokio/pull/3272
+[#3634]: https://github.com/tokio-rs/tokio/pull/3634
+[#3683]: https://github.com/tokio-rs/tokio/pull/3683
+
+# 0.6.5 (March 20, 2021)
+
+### Fixed
+
+- util: annotate time module as requiring `time` feature ([#3606])
+
+[#3606]: https://github.com/tokio-rs/tokio/pull/3606
+
+# 0.6.4 (March 9, 2021)
+
+### Added
+
+- codec: `AnyDelimiter` codec ([#3406])
+- sync: add pollable `mpsc::Sender` ([#3490])
+
+### Fixed
+
+- codec: `LinesCodec` should only return `MaxLineLengthExceeded` once per line ([#3556])
+- sync: fuse PollSemaphore ([#3578])
+
+[#3406]: https://github.com/tokio-rs/tokio/pull/3406
+[#3490]: https://github.com/tokio-rs/tokio/pull/3490
+[#3556]: https://github.com/tokio-rs/tokio/pull/3556
+[#3578]: https://github.com/tokio-rs/tokio/pull/3578
+
+# 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
 
@@ -62,8 +124,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

@@ -2,18 +2,17 @@
 name = "tokio-util"
 # When releasing to crates.io:
 # - Remove path dependencies
-# - Update html_root_url.
 # - Update doc url
 #   - Cargo.toml
 # - Update CHANGELOG.md.
 # - Create "tokio-util-0.6.x" git tag.
-version = "0.6.1"
+version = "0.6.6"
 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.6.1/tokio_util"
+documentation = "https://docs.rs/tokio-util/0.6.6/tokio_util"
 description = """
 Additional utilities for working with Tokio.
 """
@@ -36,8 +35,7 @@ rt = ["tokio/rt"]
 __docs_rs = ["futures-util"]
 
 [dependencies]
-tokio = { version = "1.0.0" }
-tokio-stream = { version = "0.1" }
+tokio = { version = "1.0.0", features = ["sync"] }
 
 bytes = "1.0.0"
 futures-core = "0.3.0"
@@ -51,11 +49,11 @@ slab = { version = "0.4.1", optional = true } # Backs `DelayQueue`
 [dev-dependencies]
 tokio = { version = "1.0.0", features = ["full"] }
 tokio-test = { version = "0.4.0" }
-
-futures = "0.3.0"
-futures-test = "0.3.5"
+tokio-stream = { version = "0.1" }
 
 async-stream = "0.3.0"
+futures = "0.3.0"
+futures-test = "0.3.5"
 
 [package.metadata.docs.rs]
 all-features = true

tokio-util/LICENSE

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

tokio-util/src/cfg.rs

@@ -47,3 +47,13 @@ macro_rules! cfg_rt {
         )*
     }
 }
+
+macro_rules! cfg_time {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "time")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
+            $item
+        )*
+    }
+}

tokio-util/src/codec/any_delimiter_codec.rs

@@ -0,0 +1,263 @@
+use crate::codec::decoder::Decoder;
+use crate::codec::encoder::Encoder;
+
+use bytes::{Buf, BufMut, Bytes, BytesMut};
+use std::{cmp, fmt, io, str, usize};
+
+const DEFAULT_SEEK_DELIMITERS: &[u8] = b",;\n\r";
+const DEFAULT_SEQUENCE_WRITER: &[u8] = b",";
+/// A simple [`Decoder`] and [`Encoder`] implementation that splits up data into chunks based on any character in the given delimiter string.
+///
+/// [`Decoder`]: crate::codec::Decoder
+/// [`Encoder`]: crate::codec::Encoder
+///
+/// # Example
+/// Decode string of bytes containing various different delimiters.
+///
+/// [`BytesMut`]: bytes::BytesMut
+/// [`Error`]: std::io::Error
+///
+/// ```
+/// use tokio_util::codec::{AnyDelimiterCodec, Decoder};
+/// use bytes::{BufMut, BytesMut};
+///
+/// #
+/// # #[tokio::main(flavor = "current_thread")]
+/// # async fn main() -> Result<(), std::io::Error> {
+/// let mut codec = AnyDelimiterCodec::new(b",;\r\n".to_vec(),b";".to_vec());
+/// let buf = &mut BytesMut::new();
+/// buf.reserve(200);
+/// buf.put_slice(b"chunk 1,chunk 2;chunk 3\n\r");
+/// assert_eq!("chunk 1", codec.decode(buf).unwrap().unwrap());
+/// assert_eq!("chunk 2", codec.decode(buf).unwrap().unwrap());
+/// assert_eq!("chunk 3", codec.decode(buf).unwrap().unwrap());
+/// assert_eq!("", codec.decode(buf).unwrap().unwrap());
+/// assert_eq!(None, codec.decode(buf).unwrap());
+/// # Ok(())
+/// # }
+/// ```
+///
+#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub struct AnyDelimiterCodec {
+    // Stored index of the next index to examine for the delimiter character.
+    // This is used to optimize searching.
+    // For example, if `decode` was called with `abc` and the delimiter is '{}', it would hold `3`,
+    // because that is the next index to examine.
+    // The next time `decode` is called with `abcde}`, the method will
+    // only look at `de}` before returning.
+    next_index: usize,
+
+    /// The maximum length for a given chunk. If `usize::MAX`, chunks will be
+    /// read until a delimiter character is reached.
+    max_length: usize,
+
+    /// Are we currently discarding the remainder of a chunk which was over
+    /// the length limit?
+    is_discarding: bool,
+
+    /// The bytes that are using for search during decode
+    seek_delimiters: Vec<u8>,
+
+    /// The bytes that are using for encoding
+    sequence_writer: Vec<u8>,
+}
+
+impl AnyDelimiterCodec {
+    /// Returns a `AnyDelimiterCodec` for splitting up data into chunks.
+    ///
+    /// # Note
+    ///
+    /// The returned `AnyDelimiterCodec` will not have an upper bound on the length
+    /// of a buffered chunk. See the documentation for [`new_with_max_length`]
+    /// for information on why this could be a potential security risk.
+    ///
+    /// [`new_with_max_length`]: crate::codec::AnyDelimiterCodec::new_with_max_length()
+    pub fn new(seek_delimiters: Vec<u8>, sequence_writer: Vec<u8>) -> AnyDelimiterCodec {
+        AnyDelimiterCodec {
+            next_index: 0,
+            max_length: usize::MAX,
+            is_discarding: false,
+            seek_delimiters,
+            sequence_writer,
+        }
+    }
+
+    /// Returns a `AnyDelimiterCodec` with a maximum chunk length limit.
+    ///
+    /// If this is set, calls to `AnyDelimiterCodec::decode` will return a
+    /// [`AnyDelimiterCodecError`] when a chunk exceeds the length limit. Subsequent calls
+    /// will discard up to `limit` bytes from that chunk until a delimiter
+    /// character is reached, returning `None` until the delimiter over the limit
+    /// has been fully discarded. After that point, calls to `decode` will
+    /// function as normal.
+    ///
+    /// # Note
+    ///
+    /// Setting a length limit is highly recommended for any `AnyDelimiterCodec` which
+    /// will be exposed to untrusted input. Otherwise, the size of the buffer
+    /// that holds the chunk currently being read is unbounded. An attacker could
+    /// exploit this unbounded buffer by sending an unbounded amount of input
+    /// without any delimiter characters, causing unbounded memory consumption.
+    ///
+    /// [`AnyDelimiterCodecError`]: crate::codec::AnyDelimiterCodecError
+    pub fn new_with_max_length(
+        seek_delimiters: Vec<u8>,
+        sequence_writer: Vec<u8>,
+        max_length: usize,
+    ) -> Self {
+        AnyDelimiterCodec {
+            max_length,
+            ..AnyDelimiterCodec::new(seek_delimiters, sequence_writer)
+        }
+    }
+
+    /// Returns the maximum chunk length when decoding.
+    ///
+    /// ```
+    /// use std::usize;
+    /// use tokio_util::codec::AnyDelimiterCodec;
+    ///
+    /// let codec = AnyDelimiterCodec::new(b",;\n".to_vec(), b";".to_vec());
+    /// assert_eq!(codec.max_length(), usize::MAX);
+    /// ```
+    /// ```
+    /// use tokio_util::codec::AnyDelimiterCodec;
+    ///
+    /// let codec = AnyDelimiterCodec::new_with_max_length(b",;\n".to_vec(), b";".to_vec(), 256);
+    /// assert_eq!(codec.max_length(), 256);
+    /// ```
+    pub fn max_length(&self) -> usize {
+        self.max_length
+    }
+}
+
+impl Decoder for AnyDelimiterCodec {
+    type Item = Bytes;
+    type Error = AnyDelimiterCodecError;
+
+    fn decode(&mut self, buf: &mut BytesMut) -> Result<Option<Bytes>, AnyDelimiterCodecError> {
+        loop {
+            // Determine how far into the buffer we'll search for a delimiter. If
+            // there's no max_length set, we'll read to the end of the buffer.
+            let read_to = cmp::min(self.max_length.saturating_add(1), buf.len());
+
+            let new_chunk_offset = buf[self.next_index..read_to].iter().position(|b| {
+                self.seek_delimiters
+                    .iter()
+                    .any(|delimiter| *b == *delimiter)
+            });
+
+            match (self.is_discarding, new_chunk_offset) {
+                (true, Some(offset)) => {
+                    // If we found a new chunk, discard up to that offset and
+                    // then stop discarding. On the next iteration, we'll try
+                    // to read a chunk normally.
+                    buf.advance(offset + self.next_index + 1);
+                    self.is_discarding = false;
+                    self.next_index = 0;
+                }
+                (true, None) => {
+                    // Otherwise, we didn't find a new chunk, so we'll discard
+                    // everything we read. On the next iteration, we'll continue
+                    // discarding up to max_len bytes unless we find a new chunk.
+                    buf.advance(read_to);
+                    self.next_index = 0;
+                    if buf.is_empty() {
+                        return Ok(None);
+                    }
+                }
+                (false, Some(offset)) => {
+                    // Found a chunk!
+                    let new_chunk_index = offset + self.next_index;
+                    self.next_index = 0;
+                    let mut chunk = buf.split_to(new_chunk_index + 1);
+                    chunk.truncate(chunk.len() - 1);
+                    let chunk = chunk.freeze();
+                    return Ok(Some(chunk));
+                }
+                (false, None) if buf.len() > self.max_length => {
+                    // Reached the maximum length without finding a
+                    // new chunk, return an error and start discarding on the
+                    // next call.
+                    self.is_discarding = true;
+                    return Err(AnyDelimiterCodecError::MaxChunkLengthExceeded);
+                }
+                (false, None) => {
+                    // We didn't find a chunk or reach the length limit, so the next
+                    // call will resume searching at the current offset.
+                    self.next_index = read_to;
+                    return Ok(None);
+                }
+            }
+        }
+    }
+
+    fn decode_eof(&mut self, buf: &mut BytesMut) -> Result<Option<Bytes>, AnyDelimiterCodecError> {
+        Ok(match self.decode(buf)? {
+            Some(frame) => Some(frame),
+            None => {
+                // return remaining data, if any
+                if buf.is_empty() {
+                    None
+                } else {
+                    let chunk = buf.split_to(buf.len());
+                    self.next_index = 0;
+                    Some(chunk.freeze())
+                }
+            }
+        })
+    }
+}
+
+impl<T> Encoder<T> for AnyDelimiterCodec
+where
+    T: AsRef<str>,
+{
+    type Error = AnyDelimiterCodecError;
+
+    fn encode(&mut self, chunk: T, buf: &mut BytesMut) -> Result<(), AnyDelimiterCodecError> {
+        let chunk = chunk.as_ref();
+        buf.reserve(chunk.len() + 1);
+        buf.put(chunk.as_bytes());
+        buf.put(self.sequence_writer.as_ref());
+
+        Ok(())
+    }
+}
+
+impl Default for AnyDelimiterCodec {
+    fn default() -> Self {
+        Self::new(
+            DEFAULT_SEEK_DELIMITERS.to_vec(),
+            DEFAULT_SEQUENCE_WRITER.to_vec(),
+        )
+    }
+}
+
+/// An error occured while encoding or decoding a chunk.
+#[derive(Debug)]
+pub enum AnyDelimiterCodecError {
+    /// The maximum chunk length was exceeded.
+    MaxChunkLengthExceeded,
+    /// An IO error occurred.
+    Io(io::Error),
+}
+
+impl fmt::Display for AnyDelimiterCodecError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AnyDelimiterCodecError::MaxChunkLengthExceeded => {
+                write!(f, "max chunk length exceeded")
+            }
+            AnyDelimiterCodecError::Io(e) => write!(f, "{}", e),
+        }
+    }
+}
+
+impl From<io::Error> for AnyDelimiterCodecError {
+    fn from(e: io::Error) -> AnyDelimiterCodecError {
+        AnyDelimiterCodecError::Io(e)
+    }
+}
+
+impl std::error::Error for AnyDelimiterCodecError {}

tokio-util/src/codec/decoder.rs

@@ -16,6 +16,20 @@ use std::io;
 /// implementing stateful streaming parsers. In many cases, though, this type
 /// will simply be a unit struct (e.g. `struct HttpDecoder`).
 ///
+/// For some underlying data-sources, namely files and FIFOs,
+/// it's possible to temporarily read 0 bytes by reaching EOF.
+///
+/// In these cases `decode_eof` will be called until it signals
+/// fullfillment of all closing frames by returning `Ok(None)`.
+/// After that, repeated attempts to read from the [`Framed`] or [`FramedRead`]
+/// will not invoke `decode` or `decode_eof` again, until data can be read
+/// during a retry.
+///
+/// It is up to the Decoder to keep track of a restart after an EOF,
+/// and to decide how to handle such an event by, for example,
+/// allowing frames to cross EOF boundaries, re-emitting opening frames, or
+/// reseting the entire internal state.
+///
 /// [`Framed`]: crate::codec::Framed
 /// [`FramedRead`]: crate::codec::FramedRead
 pub trait Decoder {
@@ -115,13 +129,18 @@ pub trait Decoder {
     /// This method defaults to calling `decode` and returns an error if
     /// `Ok(None)` is returned while there is unconsumed data in `buf`.
     /// Typically this doesn't need to be implemented unless the framing
-    /// protocol differs near the end of the stream.
+    /// protocol differs near the end of the stream, or if you need to construct
+    /// frames _across_ eof boundaries on sources that can be resumed.
     ///
     /// Note that the `buf` argument may be empty. If a previous call to
     /// `decode_eof` consumed all the bytes in the buffer, `decode_eof` will be
     /// called again until it returns `None`, indicating that there are no more
     /// frames to yield. This behavior enables returning finalization frames
     /// that may not be based on inbound data.
+    ///
+    /// Once `None` has been returned, `decode_eof` won't be called again until
+    /// an attempt to resume the stream has been made, where the underlying stream
+    /// actually returned more data.
     fn decode_eof(&mut self, buf: &mut BytesMut) -> Result<Option<Self::Item>, Self::Error> {
         match self.decode(buf)? {
             Some(frame) => Ok(Some(frame)),
@@ -153,7 +172,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,8 +2,8 @@ use crate::codec::decoder::Decoder;
 use crate::codec::encoder::Encoder;
 use crate::codec::framed_impl::{FramedImpl, RWFrames, ReadFrame, WriteFrame};
 
+use futures_core::Stream;
 use tokio::io::{AsyncRead, AsyncWrite};
-use tokio_stream::Stream;
 
 use bytes::BytesMut;
 use futures_sink::Sink;
@@ -20,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()
@@ -52,7 +52,12 @@ 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
+    /// Note that, for some byte sources, the stream can be resumed after an EOF
+    /// by reading from it, even after it has returned `None`. Repeated attempts
+    /// to do so, without new data available, continue to return `None` without
+    /// creating more (closing) frames.
+    ///
+    /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`Decode`]: crate::codec::Decoder
     /// [`Encoder`]: crate::codec::Encoder
@@ -86,7 +91,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
@@ -131,7 +136,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

tokio-util/src/codec/framed_impl.rs

@@ -1,8 +1,8 @@
 use crate::codec::decoder::Decoder;
 use crate::codec::encoder::Encoder;
 
+use futures_core::Stream;
 use tokio::io::{AsyncRead, AsyncWrite};
-use tokio_stream::Stream;
 
 use bytes::BytesMut;
 use futures_core::ready;
@@ -120,42 +120,97 @@ where
 
         let mut pinned = self.project();
         let state: &mut ReadFrame = pinned.state.borrow_mut();
+        // The following loops implements a state machine with each state corresponding
+        // to a combination of the `is_readable` and `eof` flags. States persist across
+        // loop entries and most state transitions occur with a return.
+        //
+        // The intitial state is `reading`.
+        //
+        // | state   | eof   | is_readable |
+        // |---------|-------|-------------|
+        // | reading | false | false       |
+        // | framing | false | true        |
+        // | pausing | true  | true        |
+        // | paused  | true  | false       |
+        //
+        //                                 `decode_eof`
+        //                                 returns `Some`             read 0 bytes
+        //                                   │       │                 │      │
+        //                                   │       ▼                 │      ▼
+        //                                   ┌───────┐ `decode_eof`    ┌──────┐
+        //                 ┌──read 0 bytes──▶│pausing│─returns `None`─▶│paused│──┐
+        //                 │                 └───────┘                 └──────┘  │
+        // pending read┐   │                     ┌──────┐                  │  ▲  │
+        //      │      │   │                     │      │                  │  │  │
+        //      │      ▼   │                     │  `decode` returns `Some`│ pending read
+        //      │  ╔═══════╗                 ┌───────┐◀─┘                  │
+        //      └──║reading║─read n>0 bytes─▶│framing│                     │
+        //         ╚═══════╝                 └───────┘◀──────read n>0 bytes┘
+        //             ▲                         │
+        //             │                         │
+        //             └─`decode` returns `None`─┘
         loop {
-            // Repeatedly call `decode` or `decode_eof` as long as it is
-            // "readable". Readable is defined as not having returned `None`. If
-            // the upstream has returned EOF, and the decoder is no longer
-            // readable, it can be assumed that the decoder will never become
-            // readable again, at which point the stream is terminated.
+            // Repeatedly call `decode` or `decode_eof` while the buffer is "readable",
+            // i.e. it _might_ contain data consumable as a frame or closing frame.
+            // Both signal that there is no such data by returning `None`.
+            //
+            // If `decode` couldn't read a frame and the upstream source has returned eof,
+            // `decode_eof` will attemp to decode the remaining bytes as closing frames.
+            //
+            // If the underlying AsyncRead is resumable, we may continue after an EOF,
+            // but must finish emmiting all of it's associated `decode_eof` frames.
+            // Furthermore, we don't want to emit any `decode_eof` frames on retried
+            // reads after an EOF unless we've actually read more data.
             if state.is_readable {
+                // pausing or framing
                 if state.eof {
+                    // pausing
                     let frame = pinned.codec.decode_eof(&mut state.buffer)?;
+                    if frame.is_none() {
+                        state.is_readable = false; // prepare pausing -> paused
+                    }
+                    // implicit pausing -> pausing or pausing -> paused
                     return Poll::Ready(frame.map(Ok));
                 }
 
+                // framing
                 trace!("attempting to decode a frame");
 
                 if let Some(frame) = pinned.codec.decode(&mut state.buffer)? {
                     trace!("frame decoded from buffer");
+                    // implicit framing -> framing
                     return Poll::Ready(Some(Ok(frame)));
                 }
 
+                // framing -> reading
                 state.is_readable = false;
             }
-
-            assert!(!state.eof);
-
-            // Otherwise, try to read more data and try again. Make sure we've
-            // got room for at least one byte to read to ensure that we don't
-            // get a spurious 0 that looks like EOF
+            // reading or paused
+            // If we can't build a frame yet, try to read more data and try again.
+            // Make sure we've got room for at least one byte to read to ensure
+            // that we don't get a spurious 0 that looks like EOF.
             state.buffer.reserve(1);
             let bytect = match poll_read_buf(pinned.inner.as_mut(), cx, &mut state.buffer)? {
                 Poll::Ready(ct) => ct,
+                // implicit reading -> reading or implicit paused -> paused
                 Poll::Pending => return Poll::Pending,
             };
             if bytect == 0 {
+                if state.eof {
+                    // We're already at an EOF, and since we've reached this path
+                    // we're also not readable. This implies that we've already finished
+                    // our `decode_eof` handling, so we can simply return `None`.
+                    // implicit paused -> paused
+                    return Poll::Ready(None);
+                }
+                // prepare reading -> paused
                 state.eof = true;
+            } else {
+                // prepare paused -> framing or noop reading -> framing
+                state.eof = false;
             }
 
+            // paused -> framing or reading -> framing or reading -> pausing
             state.is_readable = true;
         }
     }

tokio-util/src/codec/framed_read.rs

@@ -1,8 +1,8 @@
 use crate::codec::framed_impl::{FramedImpl, ReadFrame};
 use crate::codec::Decoder;
 
+use futures_core::Stream;
 use tokio::io::AsyncRead;
-use tokio_stream::Stream;
 
 use bytes::BytesMut;
 use futures_sink::Sink;
@@ -14,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]

tokio-util/src/codec/framed_write.rs

@@ -1,8 +1,8 @@
 use crate::codec::encoder::Encoder;
 use crate::codec::framed_impl::{FramedImpl, WriteFrame};
 
+use futures_core::Stream;
 use tokio::io::AsyncWrite;
-use tokio_stream::Stream;
 
 use bytes::BytesMut;
 use futures_sink::Sink;

tokio-util/src/codec/length_delimited.rs

@@ -535,14 +535,14 @@ impl LengthDelimitedCodec {
         Ok(Some(n))
     }
 
-    fn decode_data(&self, n: usize, src: &mut BytesMut) -> io::Result<Option<BytesMut>> {
+    fn decode_data(&self, n: usize, src: &mut BytesMut) -> Option<BytesMut> {
         // At this point, the buffer has already had the required capacity
         // reserved. All there is to do is read.
         if src.len() < n {
-            return Ok(None);
+            return None;
         }
 
-        Ok(Some(src.split_to(n)))
+        Some(src.split_to(n))
     }
 }
 
@@ -562,7 +562,7 @@ impl Decoder for LengthDelimitedCodec {
             DecodeState::Data(n) => n,
         };
 
-        match self.decode_data(n, src)? {
+        match self.decode_data(n, src) {
             Some(data) => {
                 // Update the decode state
                 self.state = DecodeState::Head;

tokio-util/src/codec/lines_codec.rs

@@ -133,7 +133,7 @@ impl Decoder for LinesCodec {
                     buf.advance(read_to);
                     self.next_index = 0;
                     if buf.is_empty() {
-                        return Err(LinesCodecError::MaxLineLengthExceeded);
+                        return Ok(None);
                     }
                 }
                 (false, Some(offset)) => {

tokio-util/src/codec/mod.rs

@@ -246,7 +246,7 @@
 //!
 //! [`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
@@ -285,3 +285,6 @@ pub use self::length_delimited::{LengthDelimitedCodec, LengthDelimitedCodecError
 
 mod lines_codec;
 pub use self::lines_codec::{LinesCodec, LinesCodecError};
+
+mod any_delimiter_codec;
+pub use self::any_delimiter_codec::{AnyDelimiterCodec, AnyDelimiterCodecError};

tokio-util/src/io/reader_stream.rs

@@ -40,7 +40,7 @@ pin_project! {
     ///
     /// [`AsyncRead`]: tokio::io::AsyncRead
     /// [`StreamReader`]: crate::io::StreamReader
-    /// [`Stream`]: tokio_stream::Stream
+    /// [`Stream`]: futures_core::Stream
     #[derive(Debug)]
     pub struct ReaderStream<R> {
         // Reader itself.
@@ -58,7 +58,7 @@ impl<R: AsyncRead> ReaderStream<R> {
     /// `Result<Bytes, std::io::Error>`.
     ///
     /// [`AsyncRead`]: tokio::io::AsyncRead
-    /// [`Stream`]: tokio_stream::Stream
+    /// [`Stream`]: futures_core::Stream
     pub fn new(reader: R) -> Self {
         ReaderStream {
             reader: Some(reader),

tokio-util/src/io/stream_reader.rs

@@ -51,7 +51,7 @@ pin_project! {
     /// ```
     ///
     /// [`AsyncRead`]: tokio::io::AsyncRead
-    /// [`Stream`]: tokio_stream::Stream
+    /// [`Stream`]: futures_core::Stream
     /// [`ReaderStream`]: crate::io::ReaderStream
     #[derive(Debug)]
     pub struct StreamReader<S, B> {

tokio-util/src/lib.rs

@@ -1,4 +1,3 @@
-#![doc(html_root_url = "https://docs.rs/tokio-util/0.6.1")]
 #![allow(clippy::needless_doctest_main)]
 #![warn(
     missing_debug_implementations,
@@ -46,13 +45,14 @@ cfg_rt! {
     pub mod context;
 }
 
+cfg_time! {
+    pub mod time;
+}
+
 pub mod sync;
 
 pub mod either;
 
-#[cfg(feature = "time")]
-pub mod time;
-
 #[cfg(any(feature = "io", feature = "codec"))]
 mod util {
     use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};

tokio-util/src/sync/mod.rs

@@ -4,3 +4,12 @@ mod cancellation_token;
 pub use cancellation_token::{CancellationToken, WaitForCancellationFuture};
 
 mod intrusive_double_linked_list;
+
+mod mpsc;
+pub use mpsc::PollSender;
+
+mod poll_semaphore;
+pub use poll_semaphore::PollSemaphore;
+
+mod reusable_box;
+pub use reusable_box::ReusableBoxFuture;

tokio-util/src/sync/mpsc.rs

@@ -0,0 +1,221 @@
+use futures_core::ready;
+use futures_sink::Sink;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+use tokio::sync::mpsc::{error::SendError, Sender};
+
+use super::ReusableBoxFuture;
+
+// This implementation was chosen over something based on permits because to get a
+// `tokio::sync::mpsc::Permit` out of the `inner` future, you must transmute the
+// lifetime on the permit to `'static`.
+
+/// A wrapper around [`mpsc::Sender`] that can be polled.
+///
+/// [`mpsc::Sender`]: tokio::sync::mpsc::Sender
+#[derive(Debug)]
+pub struct PollSender<T> {
+    /// is none if closed
+    sender: Option<Arc<Sender<T>>>,
+    is_sending: bool,
+    inner: ReusableBoxFuture<Result<(), SendError<T>>>,
+}
+
+// By reusing the same async fn for both Some and None, we make sure every
+// future passed to ReusableBoxFuture has the same underlying type, and hence
+// the same size and alignment.
+async fn make_future<T>(data: Option<(Arc<Sender<T>>, T)>) -> Result<(), SendError<T>> {
+    match data {
+        Some((sender, value)) => sender.send(value).await,
+        None => unreachable!(
+            "This future should not be pollable, as is_sending should be set to false."
+        ),
+    }
+}
+
+impl<T: Send + 'static> PollSender<T> {
+    /// Create a new `PollSender`.
+    pub fn new(sender: Sender<T>) -> Self {
+        Self {
+            sender: Some(Arc::new(sender)),
+            is_sending: false,
+            inner: ReusableBoxFuture::new(make_future(None)),
+        }
+    }
+
+    /// Start sending a new item.
+    ///
+    /// This method panics if a send is currently in progress. To ensure that no
+    /// send is in progress, call `poll_send_done` first until it returns
+    /// `Poll::Ready`.
+    ///
+    /// If this method returns an error, that indicates that the channel is
+    /// closed. Note that this method is not guaranteed to return an error if
+    /// the channel is closed, but in that case the error would be reported by
+    /// the first call to `poll_send_done`.
+    pub fn start_send(&mut self, value: T) -> Result<(), SendError<T>> {
+        if self.is_sending {
+            panic!("start_send called while not ready.");
+        }
+        match self.sender.clone() {
+            Some(sender) => {
+                self.inner.set(make_future(Some((sender, value))));
+                self.is_sending = true;
+                Ok(())
+            }
+            None => Err(SendError(value)),
+        }
+    }
+
+    /// If a send is in progress, poll for its completion. If no send is in progress,
+    /// this method returns `Poll::Ready(Ok(()))`.
+    ///
+    /// This method can return the following values:
+    ///
+    ///  - `Poll::Ready(Ok(()))` if the in-progress send has been completed, or there is
+    ///    no send in progress (even if the channel is closed).
+    ///  - `Poll::Ready(Err(err))` if the in-progress send failed because the channel has
+    ///    been closed.
+    ///  - `Poll::Pending` if a send is in progress, but it could not complete now.
+    ///
+    /// When this method returns `Poll::Pending`, the current task is scheduled
+    /// to receive a wakeup when the message is sent, or when the entire channel
+    /// is closed (but not if just this sender is closed by
+    /// `close_this_sender`). Note that on multiple calls to `poll_send_done`,
+    /// only the `Waker` from the `Context` passed to the most recent call is
+    /// scheduled to receive a wakeup.
+    ///
+    /// If this method returns `Poll::Ready`, then `start_send` is guaranteed to
+    /// not panic.
+    pub fn poll_send_done(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), SendError<T>>> {
+        if !self.is_sending {
+            return Poll::Ready(Ok(()));
+        }
+
+        let result = self.inner.poll(cx);
+        if result.is_ready() {
+            self.is_sending = false;
+        }
+        if let Poll::Ready(Err(_)) = &result {
+            self.sender = None;
+        }
+        result
+    }
+
+    /// Check whether the channel is ready to send more messages now.
+    ///
+    /// If this method returns `true`, then `start_send` is guaranteed to not
+    /// panic.
+    ///
+    /// If the channel is closed, this method returns `true`.
+    pub fn is_ready(&self) -> bool {
+        !self.is_sending
+    }
+
+    /// Check whether the channel has been closed.
+    pub fn is_closed(&self) -> bool {
+        match &self.sender {
+            Some(sender) => sender.is_closed(),
+            None => true,
+        }
+    }
+
+    /// Clone the underlying `Sender`.
+    ///
+    /// If this method returns `None`, then the channel is closed. (But it is
+    /// not guaranteed to return `None` if the channel is closed.)
+    pub fn clone_inner(&self) -> Option<Sender<T>> {
+        self.sender.as_ref().map(|sender| (&**sender).clone())
+    }
+
+    /// Access the underlying `Sender`.
+    ///
+    /// If this method returns `None`, then the channel is closed. (But it is
+    /// not guaranteed to return `None` if the channel is closed.)
+    pub fn inner_ref(&self) -> Option<&Sender<T>> {
+        self.sender.as_deref()
+    }
+
+    // This operation is supported because it is required by the Sink trait.
+    /// Close this sender. No more messages can be sent from this sender.
+    ///
+    /// Note that this only closes the channel from the view-point of this
+    /// sender. The channel remains open until all senders have gone away, or
+    /// until the [`Receiver`] closes the channel.
+    ///
+    /// If there is a send in progress when this method is called, that send is
+    /// unaffected by this operation, and `poll_send_done` can still be called
+    /// to complete that send.
+    ///
+    /// [`Receiver`]: tokio::sync::mpsc::Receiver
+    pub fn close_this_sender(&mut self) {
+        self.sender = None;
+    }
+
+    /// Abort the current in-progress send, if any.
+    ///
+    /// Returns `true` if a send was aborted.
+    pub fn abort_send(&mut self) -> bool {
+        if self.is_sending {
+            self.inner.set(make_future(None));
+            self.is_sending = false;
+            true
+        } else {
+            false
+        }
+    }
+}
+
+impl<T> Clone for PollSender<T> {
+    /// Clones this `PollSender`. The resulting clone will not have any
+    /// in-progress send operations, even if the current `PollSender` does.
+    fn clone(&self) -> PollSender<T> {
+        Self {
+            sender: self.sender.clone(),
+            is_sending: false,
+            inner: ReusableBoxFuture::new(async { unreachable!() }),
+        }
+    }
+}
+
+impl<T: Send + 'static> Sink<T> for PollSender<T> {
+    type Error = SendError<T>;
+
+    /// This is equivalent to calling [`poll_send_done`].
+    ///
+    /// [`poll_send_done`]: PollSender::poll_send_done
+    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        Pin::into_inner(self).poll_send_done(cx)
+    }
+
+    /// This is equivalent to calling [`poll_send_done`].
+    ///
+    /// [`poll_send_done`]: PollSender::poll_send_done
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        Pin::into_inner(self).poll_send_done(cx)
+    }
+
+    /// This is equivalent to calling [`start_send`].
+    ///
+    /// [`start_send`]: PollSender::start_send
+    fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error> {
+        Pin::into_inner(self).start_send(item)
+    }
+
+    /// This method will first flush the `PollSender`, and then close it by
+    /// calling [`close_this_sender`].
+    ///
+    /// If a send fails while flushing because the [`Receiver`] has gone away,
+    /// then this function returns an error. The channel is still successfully
+    /// closed in this situation.
+    ///
+    /// [`close_this_sender`]: PollSender::close_this_sender
+    /// [`Receiver`]: tokio::sync::mpsc::Receiver
+    fn poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        ready!(self.as_mut().poll_flush(cx))?;
+
+        Pin::into_inner(self).close_this_sender();
+        Poll::Ready(Ok(()))
+    }
+}

tokio-util/src/sync/poll_semaphore.rs

@@ -0,0 +1,136 @@
+use futures_core::{ready, Stream};
+use std::fmt;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+use tokio::sync::{AcquireError, OwnedSemaphorePermit, Semaphore, TryAcquireError};
+
+use super::ReusableBoxFuture;
+
+/// A wrapper around [`Semaphore`] that provides a `poll_acquire` method.
+///
+/// [`Semaphore`]: tokio::sync::Semaphore
+pub struct PollSemaphore {
+    semaphore: Arc<Semaphore>,
+    permit_fut: Option<ReusableBoxFuture<Result<OwnedSemaphorePermit, AcquireError>>>,
+}
+
+impl PollSemaphore {
+    /// Create a new `PollSemaphore`.
+    pub fn new(semaphore: Arc<Semaphore>) -> Self {
+        Self {
+            semaphore,
+            permit_fut: None,
+        }
+    }
+
+    /// Closes the semaphore.
+    pub fn close(&self) {
+        self.semaphore.close()
+    }
+
+    /// Obtain a clone of the inner semaphore.
+    pub fn clone_inner(&self) -> Arc<Semaphore> {
+        self.semaphore.clone()
+    }
+
+    /// Get back the inner semaphore.
+    pub fn into_inner(self) -> Arc<Semaphore> {
+        self.semaphore
+    }
+
+    /// Poll to acquire a permit from the semaphore.
+    ///
+    /// This can return the following values:
+    ///
+    ///  - `Poll::Pending` if a permit is not currently available.
+    ///  - `Poll::Ready(Some(permit))` if a permit was acquired.
+    ///  - `Poll::Ready(None)` if the semaphore has been closed.
+    ///
+    /// When this method returns `Poll::Pending`, the current task is scheduled
+    /// to receive a wakeup when a permit becomes available, or when the
+    /// semaphore is closed. Note that on multiple calls to `poll_acquire`, only
+    /// the `Waker` from the `Context` passed to the most recent call is
+    /// scheduled to receive a wakeup.
+    pub fn poll_acquire(&mut self, cx: &mut Context<'_>) -> Poll<Option<OwnedSemaphorePermit>> {
+        let permit_future = match self.permit_fut.as_mut() {
+            Some(fut) => fut,
+            None => {
+                // avoid allocations completely if we can grab a permit immediately
+                match Arc::clone(&self.semaphore).try_acquire_owned() {
+                    Ok(permit) => return Poll::Ready(Some(permit)),
+                    Err(TryAcquireError::Closed) => return Poll::Ready(None),
+                    Err(TryAcquireError::NoPermits) => {}
+                }
+
+                let next_fut = Arc::clone(&self.semaphore).acquire_owned();
+                self.permit_fut
+                    .get_or_insert(ReusableBoxFuture::new(next_fut))
+            }
+        };
+
+        let result = ready!(permit_future.poll(cx));
+
+        let next_fut = Arc::clone(&self.semaphore).acquire_owned();
+        permit_future.set(next_fut);
+
+        match result {
+            Ok(permit) => Poll::Ready(Some(permit)),
+            Err(_closed) => {
+                self.permit_fut = None;
+                Poll::Ready(None)
+            }
+        }
+    }
+
+    /// Returns the current number of available permits.
+    ///
+    /// This is equivalent to the [`Semaphore::available_permits`] method on the
+    /// `tokio::sync::Semaphore` type.
+    ///
+    /// [`Semaphore::available_permits`]: tokio::sync::Semaphore::available_permits
+    pub fn available_permits(&self) -> usize {
+        self.semaphore.available_permits()
+    }
+
+    /// Adds `n` new permits to the semaphore.
+    ///
+    /// The maximum number of permits is `usize::MAX >> 3`, and this function
+    /// will panic if the limit is exceeded.
+    ///
+    /// This is equivalent to the [`Semaphore::add_permits`] method on the
+    /// `tokio::sync::Semaphore` type.
+    ///
+    /// [`Semaphore::add_permits`]: tokio::sync::Semaphore::add_permits
+    pub fn add_permits(&self, n: usize) {
+        self.semaphore.add_permits(n);
+    }
+}
+
+impl Stream for PollSemaphore {
+    type Item = OwnedSemaphorePermit;
+
+    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<OwnedSemaphorePermit>> {
+        Pin::into_inner(self).poll_acquire(cx)
+    }
+}
+
+impl Clone for PollSemaphore {
+    fn clone(&self) -> PollSemaphore {
+        PollSemaphore::new(self.clone_inner())
+    }
+}
+
+impl fmt::Debug for PollSemaphore {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("PollSemaphore")
+            .field("semaphore", &self.semaphore)
+            .finish()
+    }
+}
+
+impl AsRef<Semaphore> for PollSemaphore {
+    fn as_ref(&self) -> &Semaphore {
+        &*self.semaphore
+    }
+}

tokio-util/src/sync/reusable_box.rs

@@ -0,0 +1,151 @@
+use std::alloc::Layout;
+use std::future::Future;
+use std::panic::AssertUnwindSafe;
+use std::pin::Pin;
+use std::ptr::{self, NonNull};
+use std::task::{Context, Poll};
+use std::{fmt, panic};
+
+/// A reusable `Pin<Box<dyn Future<Output = T> + Send>>`.
+///
+/// This type lets you replace the future stored in the box without
+/// reallocating when the size and alignment permits this.
+pub struct ReusableBoxFuture<T> {
+    boxed: NonNull<dyn Future<Output = T> + Send>,
+}
+
+impl<T> ReusableBoxFuture<T> {
+    /// Create a new `ReusableBoxFuture<T>` containing the provided future.
+    pub fn new<F>(future: F) -> Self
+    where
+        F: Future<Output = T> + Send + 'static,
+    {
+        let boxed: Box<dyn Future<Output = T> + Send> = Box::new(future);
+
+        let boxed = Box::into_raw(boxed);
+
+        // SAFETY: Box::into_raw does not return null pointers.
+        let boxed = unsafe { NonNull::new_unchecked(boxed) };
+
+        Self { boxed }
+    }
+
+    /// Replace the future currently stored in this box.
+    ///
+    /// This reallocates if and only if the layout of the provided future is
+    /// different from the layout of the currently stored future.
+    pub fn set<F>(&mut self, future: F)
+    where
+        F: Future<Output = T> + Send + 'static,
+    {
+        if let Err(future) = self.try_set(future) {
+            *self = Self::new(future);
+        }
+    }
+
+    /// Replace the future currently stored in this box.
+    ///
+    /// This function never reallocates, but returns an error if the provided
+    /// future has a different size or alignment from the currently stored
+    /// future.
+    pub fn try_set<F>(&mut self, future: F) -> Result<(), F>
+    where
+        F: Future<Output = T> + Send + 'static,
+    {
+        // SAFETY: The pointer is not dangling.
+        let self_layout = {
+            let dyn_future: &(dyn Future<Output = T> + Send) = unsafe { self.boxed.as_ref() };
+            Layout::for_value(dyn_future)
+        };
+
+        if Layout::new::<F>() == self_layout {
+            // SAFETY: We just checked that the layout of F is correct.
+            unsafe {
+                self.set_same_layout(future);
+            }
+
+            Ok(())
+        } else {
+            Err(future)
+        }
+    }
+
+    /// Set the current future.
+    ///
+    /// # Safety
+    ///
+    /// This function requires that the layout of the provided future is the
+    /// same as `self.layout`.
+    unsafe fn set_same_layout<F>(&mut self, future: F)
+    where
+        F: Future<Output = T> + Send + 'static,
+    {
+        // Drop the existing future, catching any panics.
+        let result = panic::catch_unwind(AssertUnwindSafe(|| {
+            ptr::drop_in_place(self.boxed.as_ptr());
+        }));
+
+        // Overwrite the future behind the pointer. This is safe because the
+        // allocation was allocated with the same size and alignment as the type F.
+        let self_ptr: *mut F = self.boxed.as_ptr() as *mut F;
+        ptr::write(self_ptr, future);
+
+        // Update the vtable of self.boxed. The pointer is not null because we
+        // just got it from self.boxed, which is not null.
+        self.boxed = NonNull::new_unchecked(self_ptr);
+
+        // If the old future's destructor panicked, resume unwinding.
+        match result {
+            Ok(()) => {}
+            Err(payload) => {
+                panic::resume_unwind(payload);
+            }
+        }
+    }
+
+    /// Get a pinned reference to the underlying future.
+    pub fn get_pin(&mut self) -> Pin<&mut (dyn Future<Output = T> + Send)> {
+        // SAFETY: The user of this box cannot move the box, and we do not move it
+        // either.
+        unsafe { Pin::new_unchecked(self.boxed.as_mut()) }
+    }
+
+    /// Poll the future stored inside this box.
+    pub fn poll(&mut self, cx: &mut Context<'_>) -> Poll<T> {
+        self.get_pin().poll(cx)
+    }
+}
+
+impl<T> Future for ReusableBoxFuture<T> {
+    type Output = T;
+
+    /// Poll the future stored inside this box.
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
+        Pin::into_inner(self).get_pin().poll(cx)
+    }
+}
+
+// The future stored inside ReusableBoxFuture<T> must be Send.
+unsafe impl<T> Send for ReusableBoxFuture<T> {}
+
+// The only method called on self.boxed is poll, which takes &mut self, so this
+// struct being Sync does not permit any invalid access to the Future, even if
+// the future is not Sync.
+unsafe impl<T> Sync for ReusableBoxFuture<T> {}
+
+// Just like a Pin<Box<dyn Future>> is always Unpin, so is this type.
+impl<T> Unpin for ReusableBoxFuture<T> {}
+
+impl<T> Drop for ReusableBoxFuture<T> {
+    fn drop(&mut self) {
+        unsafe {
+            drop(Box::from_raw(self.boxed.as_ptr()));
+        }
+    }
+}
+
+impl<T> fmt::Debug for ReusableBoxFuture<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ReusableBoxFuture").finish()
+    }
+}

tokio-util/src/time/delay_queue.rs

@@ -30,24 +30,24 @@ use std::task::{self, Poll, Waker};
 ///
 /// Once delays have been configured, the `DelayQueue` is used via its
 /// [`Stream`] implementation. [`poll_expired`] is called. If an entry has reached its
-/// deadline, it is returned. If not, `Poll::Pending` indicating that the
+/// deadline, it is returned. If not, `Poll::Pending` is returned indicating that the
 /// current task will be notified once the deadline has been reached.
 ///
 /// # `Stream` implementation
 ///
 /// Items are retrieved from the queue via [`DelayQueue::poll_expired`]. If no delays have
-/// expired, no items are returned. In this case, `NotReady` is returned and the
+/// expired, no items are returned. In this case, `Poll::Pending` is returned and the
 /// current task is registered to be notified once the next item's delay has
 /// expired.
 ///
 /// If no items are in the queue, i.e. `is_empty()` returns `true`, then `poll`
-/// returns `Ready(None)`. This indicates that the stream has reached an end.
+/// returns `Poll::Ready(None)`. This indicates that the stream has reached an end.
 /// However, if a new item is inserted *after*, `poll` will once again start
-/// returning items or `NotReady.
+/// returning items or `Poll::Pending`.
 ///
 /// Items are returned ordered by their expirations. Items that are configured
 /// to expire first will be returned first. There are no ordering guarantees
-/// for items configured to expire the same instant. Also note that delays are
+/// for items configured to expire at the same instant. Also note that delays are
 /// rounded to the closest millisecond.
 ///
 /// # Implementation
@@ -152,7 +152,7 @@ pub struct DelayQueue<T> {
     waker: Option<Waker>,
 }
 
-/// An entry in `DelayQueue` that has expired and removed.
+/// An entry in `DelayQueue` that has expired and been removed.
 ///
 /// Values are returned by [`DelayQueue::poll_expired`].
 ///
@@ -211,7 +211,7 @@ struct Data<T> {
 const MAX_ENTRIES: usize = (1 << 30) - 1;
 
 impl<T> DelayQueue<T> {
-    /// Creates a new, empty, `DelayQueue`
+    /// Creates a new, empty, `DelayQueue`.
     ///
     /// The queue will not allocate storage until items are inserted into it.
     ///
@@ -239,15 +239,15 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::with_capacity(10);
+    /// let mut delay_queue = DelayQueue::with_capacity(10);
     ///
-    ///     // These insertions are done without further allocation
-    ///     for i in 0..10 {
-    ///         delay_queue.insert(i, Duration::from_secs(i));
-    ///     }
+    /// // These insertions are done without further allocation
+    /// for i in 0..10 {
+    ///     delay_queue.insert(i, Duration::from_secs(i));
+    /// }
     ///
-    ///     // This will make the queue allocate additional storage
-    ///     delay_queue.insert(11, Duration::from_secs(11));
+    /// // This will make the queue allocate additional storage
+    /// delay_queue.insert(11, Duration::from_secs(11));
     /// # }
     /// ```
     pub fn with_capacity(capacity: usize) -> DelayQueue<T> {
@@ -272,8 +272,8 @@ impl<T> DelayQueue<T> {
     /// `value` will be returned from [`poll_expired`]. If `when` has already been
     /// reached, then `value` is immediately made available to poll.
     ///
-    /// The return value represents the insertion and is used at an argument to
-    /// [`remove`] and [`reset`]. Note that [`Key`] is token and is reused once
+    /// The return value represents the insertion and is used as an argument to
+    /// [`remove`] and [`reset`]. Note that [`Key`] is a token and is reused once
     /// `value` is removed from the queue either by calling [`poll_expired`] after
     /// `when` is reached or by calling [`remove`]. At this point, the caller
     /// must take care to not use the returned [`Key`] again as it may reference
@@ -295,13 +295,13 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
-    ///     let key = delay_queue.insert_at(
-    ///         "foo", Instant::now() + Duration::from_secs(5));
+    /// let mut delay_queue = DelayQueue::new();
+    /// let key = delay_queue.insert_at(
+    ///     "foo", Instant::now() + Duration::from_secs(5));
     ///
-    ///     // Remove the entry
-    ///     let item = delay_queue.remove(&key);
-    ///     assert_eq!(*item.get_ref(), "foo");
+    /// // Remove the entry
+    /// let item = delay_queue.remove(&key);
+    /// assert_eq!(*item.get_ref(), "foo");
     /// # }
     /// ```
     ///
@@ -353,7 +353,7 @@ impl<T> DelayQueue<T> {
 
     /// Attempts to pull out the next value of the delay queue, registering the
     /// current task for wakeup if the value is not yet available, and returning
-    /// None if the queue is exhausted.
+    /// `None` if the queue is exhausted.
     pub fn poll_expired(
         &mut self,
         cx: &mut task::Context<'_>,
@@ -391,7 +391,7 @@ impl<T> DelayQueue<T> {
     ///
     /// `value` is stored in the queue until `timeout` duration has
     /// elapsed after `insert` was called. At that point, `value` will
-    /// be returned from [`poll_expired`]. If `timeout` a Duration of
+    /// be returned from [`poll_expired`]. If `timeout` is a `Duration` of
     /// zero, then `value` is immediately made available to poll.
     ///
     /// The return value represents the insertion and is used as an
@@ -419,12 +419,12 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
-    ///     let key = delay_queue.insert("foo", Duration::from_secs(5));
+    /// let mut delay_queue = DelayQueue::new();
+    /// let key = delay_queue.insert("foo", Duration::from_secs(5));
     ///
-    ///     // Remove the entry
-    ///     let item = delay_queue.remove(&key);
-    ///     assert_eq!(*item.get_ref(), "foo");
+    /// // Remove the entry
+    /// let item = delay_queue.remove(&key);
+    /// assert_eq!(*item.get_ref(), "foo");
     /// # }
     /// ```
     ///
@@ -452,11 +452,12 @@ impl<T> DelayQueue<T> {
         }
     }
 
-    /// Removes the key fom the expired queue or the timer wheel
-    /// depending on its expiration status
+    /// Removes the key from the expired queue or the timer wheel
+    /// depending on its expiration status.
     ///
     /// # Panics
-    /// Panics if the key is not contained in the expired queue or the wheel
+    ///
+    /// Panics if the key is not contained in the expired queue or the wheel.
     fn remove_key(&mut self, key: &Key) {
         use crate::time::wheel::Stack;
 
@@ -488,12 +489,12 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
-    ///     let key = delay_queue.insert("foo", Duration::from_secs(5));
+    /// let mut delay_queue = DelayQueue::new();
+    /// let key = delay_queue.insert("foo", Duration::from_secs(5));
     ///
-    ///     // Remove the entry
-    ///     let item = delay_queue.remove(&key);
-    ///     assert_eq!(*item.get_ref(), "foo");
+    /// // Remove the entry
+    /// let item = delay_queue.remove(&key);
+    /// assert_eq!(*item.get_ref(), "foo");
     /// # }
     /// ```
     pub fn remove(&mut self, key: &Key) -> Expired<T> {
@@ -531,14 +532,14 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
-    ///     let key = delay_queue.insert("foo", Duration::from_secs(5));
+    /// let mut delay_queue = DelayQueue::new();
+    /// let key = delay_queue.insert("foo", Duration::from_secs(5));
     ///
-    ///     // "foo" is scheduled to be returned in 5 seconds
+    /// // "foo" is scheduled to be returned in 5 seconds
     ///
-    ///     delay_queue.reset_at(&key, Instant::now() + Duration::from_secs(10));
+    /// delay_queue.reset_at(&key, Instant::now() + Duration::from_secs(10));
     ///
-    ///     // "foo"is now scheduled to be returned in 10 seconds
+    /// // "foo" is now scheduled to be returned in 10 seconds
     /// # }
     /// ```
     pub fn reset_at(&mut self, key: &Key, when: Instant) {
@@ -548,6 +549,8 @@ impl<T> DelayQueue<T> {
         let when = self.normalize_deadline(when);
 
         self.slab[key.index].when = when;
+        self.slab[key.index].expired = false;
+
         self.insert_idx(when, key.index);
 
         let next_deadline = self.next_deadline();
@@ -557,7 +560,7 @@ impl<T> DelayQueue<T> {
         }
     }
 
-    /// Returns the next time poll as determined by the wheel
+    /// Returns the next time to poll as determined by the wheel
     fn next_deadline(&mut self) -> Option<Instant> {
         self.wheel
             .poll_at()
@@ -589,14 +592,14 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
-    ///     let key = delay_queue.insert("foo", Duration::from_secs(5));
+    /// let mut delay_queue = DelayQueue::new();
+    /// let key = delay_queue.insert("foo", Duration::from_secs(5));
     ///
-    ///     // "foo" is scheduled to be returned in 5 seconds
+    /// // "foo" is scheduled to be returned in 5 seconds
     ///
-    ///     delay_queue.reset(&key, Duration::from_secs(10));
+    /// delay_queue.reset(&key, Duration::from_secs(10));
     ///
-    ///     // "foo"is now scheduled to be returned in 10 seconds
+    /// // "foo"is now scheduled to be returned in 10 seconds
     /// # }
     /// ```
     pub fn reset(&mut self, key: &Key, timeout: Duration) {
@@ -619,15 +622,15 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
+    /// let mut delay_queue = DelayQueue::new();
     ///
-    ///     delay_queue.insert("foo", Duration::from_secs(5));
+    /// delay_queue.insert("foo", Duration::from_secs(5));
     ///
-    ///     assert!(!delay_queue.is_empty());
+    /// assert!(!delay_queue.is_empty());
     ///
-    ///     delay_queue.clear();
+    /// delay_queue.clear();
     ///
-    ///     assert!(delay_queue.is_empty());
+    /// assert!(delay_queue.is_empty());
     /// # }
     /// ```
     pub fn clear(&mut self) {
@@ -661,10 +664,10 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue: DelayQueue<i32> = DelayQueue::with_capacity(10);
-    ///     assert_eq!(delay_queue.len(), 0);
-    ///     delay_queue.insert(3, Duration::from_secs(5));
-    ///     assert_eq!(delay_queue.len(), 1);
+    /// let mut delay_queue: DelayQueue<i32> = DelayQueue::with_capacity(10);
+    /// assert_eq!(delay_queue.len(), 0);
+    /// delay_queue.insert(3, Duration::from_secs(5));
+    /// assert_eq!(delay_queue.len(), 1);
     /// # }
     /// ```
     pub fn len(&self) -> usize {
@@ -696,12 +699,12 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
+    /// let mut delay_queue = DelayQueue::new();
     ///
-    ///     delay_queue.insert("hello", Duration::from_secs(10));
-    ///     delay_queue.reserve(10);
+    /// delay_queue.insert("hello", Duration::from_secs(10));
+    /// delay_queue.reserve(10);
     ///
-    ///     assert!(delay_queue.capacity() >= 11);
+    /// assert!(delay_queue.capacity() >= 11);
     /// # }
     /// ```
     pub fn reserve(&mut self, additional: usize) {
@@ -711,7 +714,7 @@ impl<T> DelayQueue<T> {
     /// Returns `true` if there are no items in the queue.
     ///
     /// Note that this function returns `false` even if all items have not yet
-    /// expired and a call to `poll` will return `NotReady`.
+    /// expired and a call to `poll` will return `Poll::Pending`.
     ///
     /// # Examples
     ///
@@ -721,11 +724,11 @@ impl<T> DelayQueue<T> {
     ///
     /// # #[tokio::main]
     /// # async fn main() {
-    ///     let mut delay_queue = DelayQueue::new();
-    ///     assert!(delay_queue.is_empty());
+    /// let mut delay_queue = DelayQueue::new();
+    /// assert!(delay_queue.is_empty());
     ///
-    ///     delay_queue.insert("hello", Duration::from_secs(5));
-    ///     assert!(!delay_queue.is_empty());
+    /// delay_queue.insert("hello", Duration::from_secs(5));
+    /// assert!(!delay_queue.is_empty());
     /// # }
     /// ```
     pub fn is_empty(&self) -> bool {

tokio-util/src/time/wheel/level.rs

@@ -233,14 +233,13 @@ fn slot_for(duration: u64, level: usize) -> usize {
     ((duration >> (level * 6)) % LEVEL_MULT as u64) as usize
 }
 
-/*
 #[cfg(all(test, not(loom)))]
 mod test {
     use super::*;
 
     #[test]
     fn test_slot_for() {
-        for pos in 1..64 {
+        for pos in 0..64 {
             assert_eq!(pos as usize, slot_for(pos, 0));
         }
 
@@ -252,4 +251,3 @@ mod test {
         }
     }
 }
-*/

tokio-util/src/time/wheel/mod.rs

@@ -116,9 +116,17 @@ where
         Ok(())
     }
 
-    /// Remove `item` from thee timing wheel.
+    /// Remove `item` from the timing wheel.
     pub(crate) fn remove(&mut self, item: &T::Borrowed, store: &mut T::Store) {
         let when = T::when(item, store);
+
+        assert!(
+            self.elapsed <= when,
+            "elapsed={}; when={}",
+            self.elapsed,
+            when
+        );
+
         let level = self.level_for(when);
 
         self.levels[level].remove_entry(when, item, store);
@@ -240,9 +248,11 @@ where
 }
 
 fn level_for(elapsed: u64, when: u64) -> usize {
-    let masked = elapsed ^ when;
+    const SLOT_MASK: u64 = (1 << 6) - 1;
 
-    assert!(masked != 0, "elapsed={}; when={}", elapsed, when);
+    // Mask in the trailing bits ignored by the level calculation in order to cap
+    // the possible leading zeros
+    let masked = elapsed ^ when | SLOT_MASK;
 
     let leading_zeros = masked.leading_zeros() as usize;
     let significant = 63 - leading_zeros;
@@ -255,7 +265,7 @@ mod test {
 
     #[test]
     fn test_level_for() {
-        for pos in 1..64 {
+        for pos in 0..64 {
             assert_eq!(
                 0,
                 level_for(0, pos),

tokio-util/src/udp/frame.rs

@@ -1,7 +1,7 @@
 use crate::codec::{Decoder, Encoder};
 
+use futures_core::Stream;
 use tokio::{io::ReadBuf, net::UdpSocket};
-use tokio_stream::Stream;
 
 use bytes::{BufMut, BytesMut};
 use futures_core::ready;
@@ -28,7 +28,7 @@ use std::{io, mem::MaybeUninit};
 /// calling [`split`] on the `UdpFramed` 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
 /// [`split`]: https://docs.rs/futures/0.3/futures/stream/trait.StreamExt.html#method.split
 #[must_use = "sinks do nothing unless polled"]

tokio-util/tests/codecs.rs

@@ -1,6 +1,6 @@
 #![warn(rust_2018_idioms)]
 
-use tokio_util::codec::{BytesCodec, Decoder, Encoder, LinesCodec};
+use tokio_util::codec::{AnyDelimiterCodec, BytesCodec, Decoder, Encoder, LinesCodec};
 
 use bytes::{BufMut, Bytes, BytesMut};
 
@@ -201,7 +201,26 @@ fn lines_decoder_discard_repeat() {
     buf.put_slice(b"aa");
     assert!(codec.decode(buf).is_err());
     buf.put_slice(b"a");
+    assert_eq!(None, codec.decode(buf).unwrap());
+}
+
+// Regression test for [subsequent calls to LinesCodec decode does not return the desired results bug](https://github.com/tokio-rs/tokio/issues/3555)
+#[test]
+fn lines_decoder_max_length_underrun_twice() {
+    const MAX_LENGTH: usize = 11;
+
+    let mut codec = LinesCodec::new_with_max_length(MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"line ");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"too very l");
     assert!(codec.decode(buf).is_err());
+    buf.put_slice(b"aaaaaaaaaaaaaaaaaaaaaaa");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"ong\nshort\n");
+    assert_eq!("short", codec.decode(buf).unwrap().unwrap());
 }
 
 #[test]
@@ -215,3 +234,228 @@ fn lines_encoder() {
     codec.encode("line 2", &mut buf).unwrap();
     assert_eq!("line 1\nline 2\n", buf);
 }
+
+#[test]
+fn any_delimiters_decoder_any_character() {
+    let mut codec = AnyDelimiterCodec::new(b",;\n\r".to_vec(), b",".to_vec());
+    let buf = &mut BytesMut::new();
+    buf.reserve(200);
+    buf.put_slice(b"chunk 1,chunk 2;chunk 3\n\r");
+    assert_eq!("chunk 1", codec.decode(buf).unwrap().unwrap());
+    assert_eq!("chunk 2", codec.decode(buf).unwrap().unwrap());
+    assert_eq!("chunk 3", codec.decode(buf).unwrap().unwrap());
+    assert_eq!("", codec.decode(buf).unwrap().unwrap());
+    assert_eq!(None, codec.decode(buf).unwrap());
+    assert_eq!(None, codec.decode_eof(buf).unwrap());
+    buf.put_slice(b"k");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    assert_eq!("k", codec.decode_eof(buf).unwrap().unwrap());
+    assert_eq!(None, codec.decode(buf).unwrap());
+    assert_eq!(None, codec.decode_eof(buf).unwrap());
+}
+
+#[test]
+fn any_delimiters_decoder_max_length() {
+    const MAX_LENGTH: usize = 7;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"chunk 1 is too long\nchunk 2\nchunk 3\r\nchunk 4\n\r\n");
+
+    assert!(codec.decode(buf).is_err());
+
+    let chunk = codec.decode(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("chunk 2", chunk);
+
+    let chunk = codec.decode(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("chunk 3", chunk);
+
+    // \r\n cause empty chunk
+    let chunk = codec.decode(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("", chunk);
+
+    let chunk = codec.decode(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("chunk 4", chunk);
+
+    let chunk = codec.decode(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("", chunk);
+
+    let chunk = codec.decode(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("", chunk);
+
+    assert_eq!(None, codec.decode(buf).unwrap());
+    assert_eq!(None, codec.decode_eof(buf).unwrap());
+    buf.put_slice(b"k");
+    assert_eq!(None, codec.decode(buf).unwrap());
+
+    let chunk = codec.decode_eof(buf).unwrap().unwrap();
+    assert!(
+        chunk.len() <= MAX_LENGTH,
+        "{:?}.len() <= {:?}",
+        chunk,
+        MAX_LENGTH
+    );
+    assert_eq!("k", chunk);
+
+    assert_eq!(None, codec.decode(buf).unwrap());
+    assert_eq!(None, codec.decode_eof(buf).unwrap());
+
+    // Delimiter that's one character too long. This could cause an out of bounds
+    // error if we peek at the next characters using slice indexing.
+    buf.put_slice(b"aaabbbcc");
+    assert!(codec.decode(buf).is_err());
+}
+
+#[test]
+fn any_delimiter_decoder_max_length_underrun() {
+    const MAX_LENGTH: usize = 7;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"chunk ");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"too l");
+    assert!(codec.decode(buf).is_err());
+    buf.put_slice(b"ong\n");
+    assert_eq!(None, codec.decode(buf).unwrap());
+
+    buf.put_slice(b"chunk 2");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b",");
+    assert_eq!("chunk 2", codec.decode(buf).unwrap().unwrap());
+}
+
+#[test]
+fn any_delimiter_decoder_max_length_underrun_twice() {
+    const MAX_LENGTH: usize = 11;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"chunk ");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"too very l");
+    assert!(codec.decode(buf).is_err());
+    buf.put_slice(b"aaaaaaaaaaaaaaaaaaaaaaa");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"ong\nshort\n");
+    assert_eq!("short", codec.decode(buf).unwrap().unwrap());
+}
+#[test]
+fn any_delimiter_decoder_max_length_bursts() {
+    const MAX_LENGTH: usize = 11;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"chunk ");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"too l");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"ong\n");
+    assert!(codec.decode(buf).is_err());
+}
+
+#[test]
+fn any_delimiter_decoder_max_length_big_burst() {
+    const MAX_LENGTH: usize = 11;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"chunk ");
+    assert_eq!(None, codec.decode(buf).unwrap());
+    buf.put_slice(b"too long!\n");
+    assert!(codec.decode(buf).is_err());
+}
+
+#[test]
+fn any_delimiter_decoder_max_length_delimiter_between_decodes() {
+    const MAX_LENGTH: usize = 5;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"hello");
+    assert_eq!(None, codec.decode(buf).unwrap());
+
+    buf.put_slice(b",world");
+    assert_eq!("hello", codec.decode(buf).unwrap().unwrap());
+}
+
+#[test]
+fn any_delimiter_decoder_discard_repeat() {
+    const MAX_LENGTH: usize = 1;
+
+    let mut codec =
+        AnyDelimiterCodec::new_with_max_length(b",;\n\r".to_vec(), b",".to_vec(), MAX_LENGTH);
+    let buf = &mut BytesMut::new();
+
+    buf.reserve(200);
+    buf.put_slice(b"aa");
+    assert!(codec.decode(buf).is_err());
+    buf.put_slice(b"a");
+    assert_eq!(None, codec.decode(buf).unwrap());
+}
+
+#[test]
+fn any_delimiter_encoder() {
+    let mut codec = AnyDelimiterCodec::new(b",".to_vec(), b";--;".to_vec());
+    let mut buf = BytesMut::new();
+
+    codec.encode("chunk 1", &mut buf).unwrap();
+    assert_eq!("chunk 1;--;", buf);
+
+    codec.encode("chunk 2", &mut buf).unwrap();
+    assert_eq!("chunk 1;--;chunk 2;--;", buf);
+}

tokio-util/tests/framed_read.rs

@@ -254,6 +254,29 @@ fn multi_frames_on_eof() {
     });
 }
 
+#[test]
+fn read_eof_then_resume() {
+    let mut task = task::spawn(());
+    let mock = mock! {
+        Ok(b"\x00\x00\x00\x01".to_vec()),
+        Ok(b"".to_vec()),
+        Ok(b"\x00\x00\x00\x02".to_vec()),
+        Ok(b"".to_vec()),
+        Ok(b"\x00\x00\x00\x03".to_vec()),
+    };
+    let mut framed = FramedRead::new(mock, U32Decoder);
+
+    task.enter(|cx, _| {
+        assert_read!(pin!(framed).poll_next(cx), 1);
+        assert!(assert_ready!(pin!(framed).poll_next(cx)).is_none());
+        assert_read!(pin!(framed).poll_next(cx), 2);
+        assert!(assert_ready!(pin!(framed).poll_next(cx)).is_none());
+        assert_read!(pin!(framed).poll_next(cx), 3);
+        assert!(assert_ready!(pin!(framed).poll_next(cx)).is_none());
+        assert!(assert_ready!(pin!(framed).poll_next(cx)).is_none());
+    });
+}
+
 // ===== Mock ======
 
 struct Mock {

tokio-util/tests/mpsc.rs

@@ -0,0 +1,95 @@
+use futures::future::poll_fn;
+use tokio::sync::mpsc::channel;
+use tokio_test::task::spawn;
+use tokio_test::{assert_pending, assert_ready, assert_ready_err, assert_ready_ok};
+use tokio_util::sync::PollSender;
+
+#[tokio::test]
+async fn test_simple() {
+    let (send, mut recv) = channel(3);
+    let mut send = PollSender::new(send);
+
+    for i in 1..=3i32 {
+        send.start_send(i).unwrap();
+        assert_ready_ok!(spawn(poll_fn(|cx| send.poll_send_done(cx))).poll());
+    }
+
+    send.start_send(4).unwrap();
+    let mut fourth_send = spawn(poll_fn(|cx| send.poll_send_done(cx)));
+    assert_pending!(fourth_send.poll());
+    assert_eq!(recv.recv().await.unwrap(), 1);
+    assert!(fourth_send.is_woken());
+    assert_ready_ok!(fourth_send.poll());
+
+    drop(recv);
+
+    // Here, start_send is not guaranteed to fail, but if it doesn't the first
+    // call to poll_send_done should.
+    if send.start_send(5).is_ok() {
+        assert_ready_err!(spawn(poll_fn(|cx| send.poll_send_done(cx))).poll());
+    }
+}
+
+#[tokio::test]
+async fn test_abort() {
+    let (send, mut recv) = channel(3);
+    let mut send = PollSender::new(send);
+    let send2 = send.clone_inner().unwrap();
+
+    for i in 1..=3i32 {
+        send.start_send(i).unwrap();
+        assert_ready_ok!(spawn(poll_fn(|cx| send.poll_send_done(cx))).poll());
+    }
+
+    send.start_send(4).unwrap();
+    {
+        let mut fourth_send = spawn(poll_fn(|cx| send.poll_send_done(cx)));
+        assert_pending!(fourth_send.poll());
+        assert_eq!(recv.recv().await.unwrap(), 1);
+        assert!(fourth_send.is_woken());
+    }
+
+    let mut send2_send = spawn(send2.send(5));
+    assert_pending!(send2_send.poll());
+    send.abort_send();
+    assert!(send2_send.is_woken());
+    assert_ready_ok!(send2_send.poll());
+
+    assert_eq!(recv.recv().await.unwrap(), 2);
+    assert_eq!(recv.recv().await.unwrap(), 3);
+    assert_eq!(recv.recv().await.unwrap(), 5);
+}
+
+#[tokio::test]
+async fn close_sender_last() {
+    let (send, mut recv) = channel::<i32>(3);
+    let mut send = PollSender::new(send);
+
+    let mut recv_task = spawn(recv.recv());
+    assert_pending!(recv_task.poll());
+
+    send.close_this_sender();
+
+    assert!(recv_task.is_woken());
+    assert!(assert_ready!(recv_task.poll()).is_none());
+}
+
+#[tokio::test]
+async fn close_sender_not_last() {
+    let (send, mut recv) = channel::<i32>(3);
+    let send2 = send.clone();
+    let mut send = PollSender::new(send);
+
+    let mut recv_task = spawn(recv.recv());
+    assert_pending!(recv_task.poll());
+
+    send.close_this_sender();
+
+    assert!(!recv_task.is_woken());
+    assert_pending!(recv_task.poll());
+
+    drop(send2);
+
+    assert!(recv_task.is_woken());
+    assert!(assert_ready!(recv_task.poll()).is_none());
+}

tokio-util/tests/poll_semaphore.rs

@@ -0,0 +1,36 @@
+use std::future::Future;
+use std::sync::Arc;
+use std::task::Poll;
+use tokio::sync::{OwnedSemaphorePermit, Semaphore};
+use tokio_util::sync::PollSemaphore;
+
+type SemRet = Option<OwnedSemaphorePermit>;
+
+fn semaphore_poll<'a>(
+    sem: &'a mut PollSemaphore,
+) -> tokio_test::task::Spawn<impl Future<Output = SemRet> + 'a> {
+    let fut = futures::future::poll_fn(move |cx| sem.poll_acquire(cx));
+    tokio_test::task::spawn(fut)
+}
+
+#[tokio::test]
+async fn it_works() {
+    let sem = Arc::new(Semaphore::new(1));
+    let mut poll_sem = PollSemaphore::new(sem.clone());
+
+    let permit = sem.acquire().await.unwrap();
+    let mut poll = semaphore_poll(&mut poll_sem);
+    assert!(poll.poll().is_pending());
+    drop(permit);
+
+    assert!(matches!(poll.poll(), Poll::Ready(Some(_))));
+    drop(poll);
+
+    sem.close();
+
+    assert!(semaphore_poll(&mut poll_sem).await.is_none());
+
+    // Check that it is fused.
+    assert!(semaphore_poll(&mut poll_sem).await.is_none());
+    assert!(semaphore_poll(&mut poll_sem).await.is_none());
+}

tokio-util/tests/reusable_box.rs

@@ -0,0 +1,72 @@
+use futures::future::FutureExt;
+use std::alloc::Layout;
+use std::future::Future;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio_util::sync::ReusableBoxFuture;
+
+#[test]
+fn test_different_futures() {
+    let fut = async move { 10 };
+    // Not zero sized!
+    assert_eq!(Layout::for_value(&fut).size(), 1);
+
+    let mut b = ReusableBoxFuture::new(fut);
+
+    assert_eq!(b.get_pin().now_or_never(), Some(10));
+
+    b.try_set(async move { 20 })
+        .unwrap_or_else(|_| panic!("incorrect size"));
+
+    assert_eq!(b.get_pin().now_or_never(), Some(20));
+
+    b.try_set(async move { 30 })
+        .unwrap_or_else(|_| panic!("incorrect size"));
+
+    assert_eq!(b.get_pin().now_or_never(), Some(30));
+}
+
+#[test]
+fn test_different_sizes() {
+    let fut1 = async move { 10 };
+    let val = [0u32; 1000];
+    let fut2 = async move { val[0] };
+    let fut3 = ZeroSizedFuture {};
+
+    assert_eq!(Layout::for_value(&fut1).size(), 1);
+    assert_eq!(Layout::for_value(&fut2).size(), 4004);
+    assert_eq!(Layout::for_value(&fut3).size(), 0);
+
+    let mut b = ReusableBoxFuture::new(fut1);
+    assert_eq!(b.get_pin().now_or_never(), Some(10));
+    b.set(fut2);
+    assert_eq!(b.get_pin().now_or_never(), Some(0));
+    b.set(fut3);
+    assert_eq!(b.get_pin().now_or_never(), Some(5));
+}
+
+struct ZeroSizedFuture {}
+impl Future for ZeroSizedFuture {
+    type Output = u32;
+    fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<u32> {
+        Poll::Ready(5)
+    }
+}
+
+#[test]
+fn test_zero_sized() {
+    let fut = ZeroSizedFuture {};
+    // Zero sized!
+    assert_eq!(Layout::for_value(&fut).size(), 0);
+
+    let mut b = ReusableBoxFuture::new(fut);
+
+    assert_eq!(b.get_pin().now_or_never(), Some(5));
+    assert_eq!(b.get_pin().now_or_never(), Some(5));
+
+    b.try_set(ZeroSizedFuture {})
+        .unwrap_or_else(|_| panic!("incorrect size"));
+
+    assert_eq!(b.get_pin().now_or_never(), Some(5));
+    assert_eq!(b.get_pin().now_or_never(), Some(5));
+}

tokio-util/tests/time_delay_queue.rs

@@ -245,6 +245,35 @@ async fn reset_twice() {
     assert!(queue.is_woken());
 }
 
+/// Regression test: Given an entry inserted with a deadline in the past, so
+/// that it is placed directly on the expired queue, reset the entry to a
+/// deadline in the future. Validate that this leaves the entry and queue in an
+/// internally consistent state by running an additional reset on the entry
+/// before polling it to completion.
+#[tokio::test]
+async fn repeatedly_reset_entry_inserted_as_expired() {
+    time::pause();
+    let mut queue = task::spawn(DelayQueue::new());
+    let now = Instant::now();
+
+    let key = queue.insert_at("foo", now - ms(100));
+
+    queue.reset_at(&key, now + ms(100));
+    queue.reset_at(&key, now + ms(50));
+
+    assert_pending!(poll!(queue));
+
+    time::sleep_until(now + ms(60)).await;
+
+    assert!(queue.is_woken());
+
+    let entry = assert_ready_ok!(poll!(queue)).into_inner();
+    assert_eq!(entry, "foo");
+
+    let entry = assert_ready!(poll!(queue));
+    assert!(entry.is_none());
+}
+
 #[tokio::test]
 async fn remove_expired_item() {
     time::pause();
@@ -261,6 +290,38 @@ async fn remove_expired_item() {
     assert_eq!(entry.into_inner(), "foo");
 }
 
+/// Regression test: it should be possible to remove entries which fall in the
+/// 0th slot of the internal timer wheel — that is, entries whose expiration
+/// (a) falls at the beginning of one of the wheel's hierarchical levels and (b)
+/// is equal to the wheel's current elapsed time.
+#[tokio::test]
+async fn remove_at_timer_wheel_threshold() {
+    time::pause();
+
+    let mut queue = task::spawn(DelayQueue::new());
+
+    let now = Instant::now();
+
+    let key1 = queue.insert_at("foo", now + ms(64));
+    let key2 = queue.insert_at("bar", now + ms(64));
+
+    sleep(ms(80)).await;
+
+    let entry = assert_ready_ok!(poll!(queue)).into_inner();
+
+    match entry {
+        "foo" => {
+            let entry = queue.remove(&key2).into_inner();
+            assert_eq!(entry, "bar");
+        }
+        "bar" => {
+            let entry = queue.remove(&key1).into_inner();
+            assert_eq!(entry, "foo");
+        }
+        other => panic!("other: {:?}", other),
+    }
+}
+
 #[tokio::test]
 async fn expires_before_last_insert() {
     time::pause();

tokio/CHANGELOG.md

@@ -1,3 +1,238 @@
+# 1.5.2 (July 19, 2021)
+
+Fixes a missed edge case from 1.5.1.
+
+### Fixed
+
+- runtime: drop canceled future on next poll (#3965)
+
+# 1.5.1 (July 6, 2021)
+
+### Fixed
+
+- runtime: remotely abort tasks on `JoinHandle::abort` ([#3934])
+
+[#3934]: https://github.com/tokio-rs/tokio/pull/3934
+
+# 1.5.0 (April 12, 2021)
+
+### Added
+
+- io: add `AsyncSeekExt::stream_position` ([#3650])
+- io: add `AsyncWriteExt::write_vectored` ([#3678])
+- io: add a `copy_bidirectional` utility ([#3572])
+- net: implement `IntoRawFd` for `TcpSocket` ([#3684])
+- sync: add `OnceCell` ([#3591])
+- sync: add `OwnedRwLockReadGuard` and `OwnedRwLockWriteGuard` ([#3340])
+- sync: add `Semaphore::is_closed` ([#3673])
+- sync: add `mpsc::Sender::capacity` ([#3690])
+- sync: allow configuring `RwLock` max reads ([#3644])
+- task: add `sync_scope` for `LocalKey` ([#3612])
+
+### Fixed
+
+- chore: try to avoid `noalias` attributes on intrusive linked list ([#3654])
+- rt: fix panic in `JoinHandle::abort()` when called from other threads ([#3672])
+- sync: don't panic in `oneshot::try_recv` ([#3674])
+- sync: fix notifications getting dropped on receiver drop ([#3652])
+
+### Documented
+
+- io: clarify requirements of `AsyncFd` ([#3635])
+- runtime: fix unclear docs for `{Handle,Runtime}::block_on` ([#3628])
+- sync: document that `Semaphore` is fair ([#3693])
+- sync: improve doc on blocking mutex ([#3645])
+
+[#3340]: https://github.com/tokio-rs/tokio/pull/3340
+[#3572]: https://github.com/tokio-rs/tokio/pull/3572
+[#3591]: https://github.com/tokio-rs/tokio/pull/3591
+[#3612]: https://github.com/tokio-rs/tokio/pull/3612
+[#3628]: https://github.com/tokio-rs/tokio/pull/3628
+[#3635]: https://github.com/tokio-rs/tokio/pull/3635
+[#3644]: https://github.com/tokio-rs/tokio/pull/3644
+[#3645]: https://github.com/tokio-rs/tokio/pull/3645
+[#3650]: https://github.com/tokio-rs/tokio/pull/3650
+[#3652]: https://github.com/tokio-rs/tokio/pull/3652
+[#3654]: https://github.com/tokio-rs/tokio/pull/3654
+[#3672]: https://github.com/tokio-rs/tokio/pull/3672
+[#3673]: https://github.com/tokio-rs/tokio/pull/3673
+[#3674]: https://github.com/tokio-rs/tokio/pull/3674
+[#3678]: https://github.com/tokio-rs/tokio/pull/3678
+[#3684]: https://github.com/tokio-rs/tokio/pull/3684
+[#3690]: https://github.com/tokio-rs/tokio/pull/3690
+[#3693]: https://github.com/tokio-rs/tokio/pull/3693
+
+# 1.4.0 (March 20, 2021)
+
+### Added
+
+- macros: introduce biased argument for `select!` ([#3603])
+- runtime: add `Handle::block_on` ([#3569])
+
+### Fixed
+
+- runtime: avoid unnecessary polling of `block_on` future ([#3582])
+- runtime: fix memory leak/growth when creating many runtimes ([#3564])
+- runtime: mark `EnterGuard` with `must_use` ([#3609])
+
+### Documented
+
+- chore: mention fix for building docs in contributing guide ([#3618])
+- doc: add link to `PollSender` ([#3613])
+- doc: alias sleep to delay ([#3604])
+- sync: improve `Mutex` FIFO explanation ([#3615])
+- timer: fix double newline in module docs ([#3617])
+
+[#3564]: https://github.com/tokio-rs/tokio/pull/3564
+[#3613]: https://github.com/tokio-rs/tokio/pull/3613
+[#3618]: https://github.com/tokio-rs/tokio/pull/3618
+[#3617]: https://github.com/tokio-rs/tokio/pull/3617
+[#3582]: https://github.com/tokio-rs/tokio/pull/3582
+[#3615]: https://github.com/tokio-rs/tokio/pull/3615
+[#3603]: https://github.com/tokio-rs/tokio/pull/3603
+[#3609]: https://github.com/tokio-rs/tokio/pull/3609
+[#3604]: https://github.com/tokio-rs/tokio/pull/3604
+[#3569]: https://github.com/tokio-rs/tokio/pull/3569
+
+# 1.3.0 (March 9, 2021)
+
+### Added
+
+- coop: expose an `unconstrained()` opt-out ([#3547])
+- net: add `into_std` for net types without it ([#3509])
+- sync: add `same_channel` method to `mpsc::Sender` ([#3532])
+- sync: add `{try_,}acquire_many_owned` to `Semaphore` ([#3535])
+- sync: add back `RwLockWriteGuard::map` and `RwLockWriteGuard::try_map` ([#3348])
+
+### Fixed
+
+- sync: allow `oneshot::Receiver::close` after successful `try_recv` ([#3552])
+- time: do not panic on `timeout(Duration::MAX)` ([#3551])
+
+### Documented
+
+- doc: doc aliases for pre-1.0 function names ([#3523])
+- io: fix typos ([#3541])
+- io: note the EOF behaviour of `read_until` ([#3536])
+- io: update `AsyncRead::poll_read` doc ([#3557])
+- net: update `UdpSocket` splitting doc ([#3517])
+- runtime: add link to `LocalSet` on `new_current_thread` ([#3508])
+- runtime: update documentation of thread limits ([#3527])
+- sync: do not recommend `join_all` for `Barrier` ([#3514])
+- sync: documentation for `oneshot` ([#3592])
+- sync: rename `notify` to `notify_one` ([#3526])
+- time: fix typo in `Sleep` doc ([#3515])
+- time: sync `interval.rs` and `time/mod.rs` docs ([#3533])
+
+[#3348]: https://github.com/tokio-rs/tokio/pull/3348
+[#3508]: https://github.com/tokio-rs/tokio/pull/3508
+[#3509]: https://github.com/tokio-rs/tokio/pull/3509
+[#3514]: https://github.com/tokio-rs/tokio/pull/3514
+[#3515]: https://github.com/tokio-rs/tokio/pull/3515
+[#3517]: https://github.com/tokio-rs/tokio/pull/3517
+[#3523]: https://github.com/tokio-rs/tokio/pull/3523
+[#3526]: https://github.com/tokio-rs/tokio/pull/3526
+[#3527]: https://github.com/tokio-rs/tokio/pull/3527
+[#3532]: https://github.com/tokio-rs/tokio/pull/3532
+[#3533]: https://github.com/tokio-rs/tokio/pull/3533
+[#3535]: https://github.com/tokio-rs/tokio/pull/3535
+[#3536]: https://github.com/tokio-rs/tokio/pull/3536
+[#3541]: https://github.com/tokio-rs/tokio/pull/3541
+[#3547]: https://github.com/tokio-rs/tokio/pull/3547
+[#3551]: https://github.com/tokio-rs/tokio/pull/3551
+[#3552]: https://github.com/tokio-rs/tokio/pull/3552
+[#3557]: https://github.com/tokio-rs/tokio/pull/3557
+[#3592]: https://github.com/tokio-rs/tokio/pull/3592
+
+# 1.2.0 (February 5, 2021)
+
+### Added
+
+- signal: make `Signal::poll_recv` method public ([#3383])
+
+### Fixed
+
+- time: make `test-util` paused time fully deterministic ([#3492])
+
+### Documented
+
+- sync: link to new broadcast and watch wrappers ([#3504])
+
+[#3383]: https://github.com/tokio-rs/tokio/pull/3383
+[#3492]: https://github.com/tokio-rs/tokio/pull/3492
+[#3504]: https://github.com/tokio-rs/tokio/pull/3504
+
+# 1.1.1 (January 29, 2021)
+
+Forward ports 1.0.3 fix.
+
+### Fixed
+- io: memory leak during shutdown ([#3477]).
+
+# 1.1.0 (January 22, 2021)
+
+### Added
+
+- net: add `try_read_buf` and `try_recv_buf` ([#3351])
+- mpsc: Add `Sender::try_reserve` function ([#3418])
+- sync: add `RwLock` `try_read` and `try_write` methods ([#3400])
+- io: add `ReadBuf::inner_mut` ([#3443])
+
+### Changed
+
+- macros: improve `select!` error message ([#3352])
+- io: keep track of initialized bytes in `read_to_end` ([#3426])
+- runtime: consolidate errors for context missing ([#3441])
+
+### Fixed
+
+- task: wake `LocalSet` on `spawn_local` ([#3369])
+- sync: fix panic in broadcast::Receiver drop ([#3434])
+
+### Documented
+- stream: link to new `Stream` wrappers in `tokio-stream` ([#3343])
+- docs: mention that `test-util` feature is not enabled with full ([#3397])
+- process: add documentation to process::Child fields ([#3437])
+- io: clarify `AsyncFd` docs about changes of the inner fd ([#3430])
+- net: update datagram docs on splitting ([#3448])
+- time: document that `Sleep` is not `Unpin` ([#3457])
+- sync: add link to `PollSemaphore` ([#3456])
+- task: add `LocalSet` example ([#3438])
+- sync: improve bounded `mpsc` documentation ([#3458])
+
+[#3343]: https://github.com/tokio-rs/tokio/pull/3343
+[#3351]: https://github.com/tokio-rs/tokio/pull/3351
+[#3352]: https://github.com/tokio-rs/tokio/pull/3352
+[#3369]: https://github.com/tokio-rs/tokio/pull/3369
+[#3397]: https://github.com/tokio-rs/tokio/pull/3397
+[#3400]: https://github.com/tokio-rs/tokio/pull/3400
+[#3418]: https://github.com/tokio-rs/tokio/pull/3418
+[#3426]: https://github.com/tokio-rs/tokio/pull/3426
+[#3430]: https://github.com/tokio-rs/tokio/pull/3430
+[#3434]: https://github.com/tokio-rs/tokio/pull/3434
+[#3437]: https://github.com/tokio-rs/tokio/pull/3437
+[#3438]: https://github.com/tokio-rs/tokio/pull/3438
+[#3441]: https://github.com/tokio-rs/tokio/pull/3441
+[#3443]: https://github.com/tokio-rs/tokio/pull/3443
+[#3448]: https://github.com/tokio-rs/tokio/pull/3448
+[#3456]: https://github.com/tokio-rs/tokio/pull/3456
+[#3457]: https://github.com/tokio-rs/tokio/pull/3457
+[#3458]: https://github.com/tokio-rs/tokio/pull/3458
+
+# 1.0.3 (January 28, 2021)
+
+### Fixed
+- io: memory leak during shutdown ([#3477]).
+
+[#3477]: https://github.com/tokio-rs/tokio/pull/3477
+
+# 1.0.2 (January 14, 2021)
+
+### Fixed
+- io: soundness in `read_to_end` ([#3428]).
+
+[#3428]: https://github.com/tokio-rs/tokio/pull/3428
+
 # 1.0.1 (December 25, 2020)
 
 This release fixes a soundness hole caused by the combination of `RwLockWriteGuard::map`

tokio/Cargo.toml

@@ -2,18 +2,17 @@
 name = "tokio"
 # When releasing to crates.io:
 # - Remove path dependencies
-# - Update html_root_url.
 # - Update doc url
 #   - Cargo.toml
 #   - README.md
 # - Update CHANGELOG.md.
 # - Create "v1.0.x" git tag.
-version = "1.0.1"
+version = "1.5.2"
 edition = "2018"
 authors = ["Tokio Contributors <[email protected]>"]
 license = "MIT"
 readme = "README.md"
-documentation = "https://docs.rs/tokio/1.0.1/tokio/"
+documentation = "https://docs.rs/tokio/1.5.2/tokio/"
 repository = "https://github.com/tokio-rs/tokio"
 homepage = "https://tokio.rs"
 description = """
@@ -86,7 +85,7 @@ test-util = []
 time = []
 
 [dependencies]
-tokio-macros = { version = "1.0.0", path = "../tokio-macros", optional = true }
+tokio-macros = { version = "1.1.0", path = "../tokio-macros", optional = true }
 
 pin-project-lite = "0.2.0"
 
@@ -120,12 +119,13 @@ optional = true
 tokio-test = { version = "0.4.0", path = "../tokio-test" }
 tokio-stream = { version = "0.1", path = "../tokio-stream" }
 futures = { version = "0.3.0", features = ["async-await"] }
-proptest = "0.10.0"
+proptest = "1"
+rand = "0.8.0"
 tempfile = "3.1.0"
 async-stream = "0.3"
 
 [target.'cfg(loom)'.dev-dependencies]
-loom = { version = "0.4", features = ["futures", "checkpoint"] }
+loom = { version = "0.5", features = ["futures", "checkpoint"] }
 
 [build-dependencies]
 autocfg = "1" # Needed for conditionally enabling `track-caller`

tokio/LICENSE

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

tokio/src/coop.rs

@@ -1,55 +1,33 @@
 #![cfg_attr(not(feature = "full"), allow(dead_code))]
 
-//! Opt-in yield points for improved cooperative scheduling.
+//! Yield points for improved cooperative scheduling.
 //!
-//! A single call to [`poll`] on a top-level task may potentially do a lot of
-//! work before it returns `Poll::Pending`. If a task runs for a long period of
-//! time without yielding back to the executor, it can starve other tasks
-//! waiting on that executor to execute them, or drive underlying resources.
-//! Since Rust does not have a runtime, it is difficult to forcibly preempt a
-//! long-running task. Instead, this module provides an opt-in mechanism for
-//! futures to collaborate with the executor to avoid starvation.
+//! Documentation for this can be found in the [`tokio::task`] module.
 //!
-//! Consider a future like this one:
-//!
-//! ```
-//! # use tokio_stream::{Stream, StreamExt};
-//! async fn drop_all<I: Stream + Unpin>(mut input: I) {
-//!     while let Some(_) = input.next().await {}
-//! }
-//! ```
-//!
-//! It may look harmless, but consider what happens under heavy load if the
-//! input stream is _always_ ready. If we spawn `drop_all`, the task will never
-//! yield, and will starve other tasks and resources on the same executor. With
-//! opt-in yield points, this problem is alleviated:
-//!
-//! ```ignore
-//! # use tokio_stream::{Stream, StreamExt};
-//! async fn drop_all<I: Stream + Unpin>(mut input: I) {
-//!     while let Some(_) = input.next().await {
-//!         tokio::coop::proceed().await;
-//!     }
-//! }
-//! ```
-//!
-//! The `proceed` future will coordinate with the executor to make sure that
-//! every so often control is yielded back to the executor so it can run other
-//! tasks.
-//!
-//! # Placing yield points
-//!
-//! Voluntary yield points should be placed _after_ at least some work has been
-//! done. If they are not, a future sufficiently deep in the task hierarchy may
-//! end up _never_ getting to run because of the number of yield points that
-//! inevitably appear before it is reached. In general, you will want yield
-//! points to only appear in "leaf" futures -- those that do not themselves poll
-//! other futures. By doing this, you avoid double-counting each iteration of
-//! the outer future against the cooperating budget.
-//!
-//! [`poll`]: method@std::future::Future::poll
+//! [`tokio::task`]: crate::task.
 
-// NOTE: The doctests in this module are ignored since the whole module is (currently) private.
+// ```ignore
+// # use tokio_stream::{Stream, StreamExt};
+// async fn drop_all<I: Stream + Unpin>(mut input: I) {
+//     while let Some(_) = input.next().await {
+//         tokio::coop::proceed().await;
+//     }
+// }
+// ```
+//
+// The `proceed` future will coordinate with the executor to make sure that
+// every so often control is yielded back to the executor so it can run other
+// tasks.
+//
+// # Placing yield points
+//
+// Voluntary yield points should be placed _after_ at least some work has been
+// done. If they are not, a future sufficiently deep in the task hierarchy may
+// end up _never_ getting to run because of the number of yield points that
+// inevitably appear before it is reached. In general, you will want yield
+// points to only appear in "leaf" futures -- those that do not themselves poll
+// other futures. By doing this, you avoid double-counting each iteration of
+// the outer future against the cooperating budget.
 
 use std::cell::Cell;
 
@@ -98,6 +76,13 @@ pub(crate) fn budget<R>(f: impl FnOnce() -> R) -> R {
     with_budget(Budget::initial(), f)
 }
 
+/// Run the given closure with an unconstrained task budget. When the function returns, the budget
+/// is reset to the value prior to calling the function.
+#[inline(always)]
+pub(crate) fn with_unconstrained<R>(f: impl FnOnce() -> R) -> R {
+    with_budget(Budget::unconstrained(), f)
+}
+
 #[inline(always)]
 fn with_budget<R>(budget: Budget, f: impl FnOnce() -> R) -> R {
     struct ResetGuard<'a> {

tokio/src/io/async_fd.rs

@@ -8,7 +8,8 @@ use std::{task::Context, task::Poll};
 /// Associates an IO object backed by a Unix file descriptor with the tokio
 /// reactor, allowing for readiness to be polled. The file descriptor must be of
 /// a type that can be used with the OS polling facilities (ie, `poll`, `epoll`,
-/// `kqueue`, etc), such as a network socket or pipe.
+/// `kqueue`, etc), such as a network socket or pipe, and the file descriptor
+/// must have the nonblocking mode set to true.
 ///
 /// Creating an AsyncFd registers the file descriptor with the current tokio
 /// Reactor, allowing you to directly await the file descriptor being readable
@@ -23,9 +24,11 @@ use std::{task::Context, task::Poll};
 /// to retake control from the tokio IO reactor.
 ///
 /// The inner object is required to implement [`AsRawFd`]. This file descriptor
-/// must not change while [`AsyncFd`] owns the inner object. Changing the file
-/// descriptor results in unspecified behavior in the IO driver, which may
-/// include breaking notifications for other sockets/etc.
+/// must not change while [`AsyncFd`] owns the inner object, i.e. the
+/// [`AsRawFd::as_raw_fd`] method on the inner type must always return the same
+/// file descriptor when called multiple times. Failure to uphold this results
+/// in unspecified behavior in the IO driver, which may include breaking
+/// notifications for other sockets/etc.
 ///
 /// Polling for readiness is done by calling the async functions [`readable`]
 /// and [`writable`]. These functions complete when the associated readiness
@@ -34,18 +37,19 @@ use std::{task::Context, task::Poll};
 ///
 /// On some platforms, the readiness detecting mechanism relies on
 /// edge-triggered notifications. This means that the OS will only notify Tokio
-/// when the file descriptor transitions from not-ready to ready. Tokio
-/// internally tracks when it has received a ready notification, and when
+/// when the file descriptor transitions from not-ready to ready. For this to
+/// work you should first try to read or write and only poll for readiness
+/// if that fails with an error of [`std::io::ErrorKind::WouldBlock`].
+///
+/// Tokio internally tracks when it has received a ready notification, and when
 /// readiness checking functions like [`readable`] and [`writable`] are called,
 /// if the readiness flag is set, these async functions will complete
-/// immediately.
-///
-/// This however does mean that it is critical to ensure that this ready flag is
-/// cleared when (and only when) the file descriptor ceases to be ready. The
-/// [`AsyncFdReadyGuard`] returned from readiness checking functions serves this
-/// function; after calling a readiness-checking async function, you must use
-/// this [`AsyncFdReadyGuard`] to signal to tokio whether the file descriptor is no
-/// longer in a ready state.
+/// immediately. This however does mean that it is critical to ensure that this
+/// ready flag is cleared when (and only when) the file descriptor ceases to be
+/// ready. The [`AsyncFdReadyGuard`] returned from readiness checking functions
+/// serves this function; after calling a readiness-checking async function,
+/// you must use this [`AsyncFdReadyGuard`] to signal to tokio whether the file
+/// descriptor is no longer in a ready state.
 ///
 /// ## Use with to a poll-based API
 ///
@@ -517,6 +521,8 @@ impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
     /// create this `AsyncFdReadyGuard`.
     ///
     /// [`WouldBlock`]: std::io::ErrorKind::WouldBlock
+    // Alias for old name in 0.x
+    #[cfg_attr(docsrs, doc(alias = "with_io"))]
     pub fn try_io<R>(
         &mut self,
         f: impl FnOnce(&AsyncFd<Inner>) -> io::Result<R>,

tokio/src/io/async_read.rs

@@ -43,9 +43,9 @@ use std::task::{Context, Poll};
 pub trait AsyncRead {
     /// Attempts to read from the `AsyncRead` into `buf`.
     ///
-    /// On success, returns `Poll::Ready(Ok(()))` and fills `buf` with data
-    /// read. If no data was read (`buf.filled().is_empty()`) it implies that
-    /// EOF has been reached.
+    /// On success, returns `Poll::Ready(Ok(()))` and places data in the
+    /// unfilled portion of `buf`. If no data was read (`buf.filled().len()` is
+    /// unchanged), it implies that EOF has been reached.
     ///
     /// If no data is available for reading, the method returns `Poll::Pending`
     /// and arranges for the current task (via `cx.waker()`) to receive a

tokio/src/io/driver/interest.rs

@@ -1,4 +1,4 @@
-#![cfg_attr(not(feature = "net"), allow(unreachable_pub))]
+#![cfg_attr(not(feature = "net"), allow(dead_code, unreachable_pub))]
 
 use crate::io::driver::Ready;
 

tokio/src/io/driver/mod.rs

@@ -259,8 +259,7 @@ cfg_rt! {
         /// This function panics if there is no current reactor set and `rt` feature
         /// flag is not enabled.
         pub(super) fn current() -> Self {
-            crate::runtime::context::io_handle()
-                .expect("there is no reactor running, must be called from the context of Tokio runtime")
+            crate::runtime::context::io_handle().expect("A Tokio 1.x context was found, but IO is disabled. Call `enable_io` on the runtime builder to enable IO.")
         }
     }
 }
@@ -274,7 +273,7 @@ cfg_not_rt! {
         /// This function panics if there is no current reactor set, or if the `rt`
         /// feature flag is not enabled.
         pub(super) fn current() -> Self {
-            panic!("there is no reactor running, must be called from the context of Tokio runtime with `rt` enabled.")
+            panic!(crate::util::error::CONTEXT_MISSING_ERROR)
         }
     }
 }

tokio/src/io/driver/registration.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(not(feature = "net"), allow(dead_code))]
+
 use crate::io::driver::{Direction, Handle, Interest, ReadyEvent, ScheduledIo};
 use crate::util::slab;
 
@@ -205,6 +207,19 @@ impl Registration {
     }
 }
 
+impl Drop for Registration {
+    fn drop(&mut self) {
+        // It is possible for a cycle to be created between wakers stored in
+        // `ScheduledIo` instances and `Arc<driver::Inner>`. To break this
+        // cycle, wakers are cleared. This is an imperfect solution as it is
+        // possible to store a `Registration` in a waker. In this case, the
+        // cycle would remain.
+        //
+        // See tokio-rs/tokio#3481 for more details.
+        self.shared.clear_wakers();
+    }
+}
+
 fn gone() -> io::Error {
     io::Error::new(io::ErrorKind::Other, "IO driver has terminated")
 }
@@ -220,7 +235,10 @@ cfg_io_readiness! {
 
             crate::future::poll_fn(|cx| {
                 if self.handle.inner().is_none() {
-                    return Poll::Ready(Err(io::Error::new(io::ErrorKind::Other, "reactor gone")));
+                    return Poll::Ready(Err(io::Error::new(
+                        io::ErrorKind::Other,
+                        crate::util::error::RUNTIME_SHUTTING_DOWN_ERROR
+                    )));
                 }
 
                 Pin::new(&mut fut).poll(cx).map(Ok)

tokio/src/io/driver/scheduled_io.rs

@@ -355,6 +355,12 @@ impl ScheduledIo {
         // result isn't important
         let _ = self.set_readiness(None, Tick::Clear(event.tick), |curr| curr - mask_no_closed);
     }
+
+    pub(crate) fn clear_wakers(&self) {
+        let mut waiters = self.waiters.lock();
+        waiters.reader.take();
+        waiters.writer.take();
+    }
 }
 
 impl Drop for ScheduledIo {
@@ -437,7 +443,7 @@ cfg_io_readiness! {
                             // Currently ready!
                             let tick = TICK.unpack(curr) as u8;
                             *state = State::Done;
-                            return Poll::Ready(ReadyEvent { ready, tick });
+                            return Poll::Ready(ReadyEvent { tick, ready });
                         }
 
                         // Wasn't ready, take the lock (and check again while locked).
@@ -456,7 +462,7 @@ cfg_io_readiness! {
                             // Currently ready!
                             let tick = TICK.unpack(curr) as u8;
                             *state = State::Done;
-                            return Poll::Ready(ReadyEvent { ready, tick });
+                            return Poll::Ready(ReadyEvent { tick, ready });
                         }
 
                         // Not ready even after locked, insert into list...

tokio/src/io/mod.rs

@@ -246,7 +246,7 @@ cfg_io_util! {
     pub(crate) mod seek;
     pub(crate) mod util;
     pub use util::{
-        copy, copy_buf, duplex, empty, repeat, sink, AsyncBufReadExt, AsyncReadExt, AsyncSeekExt, AsyncWriteExt,
+        copy, copy_bidirectional, copy_buf, duplex, empty, repeat, sink, AsyncBufReadExt, AsyncReadExt, AsyncSeekExt, AsyncWriteExt,
         BufReader, BufStream, BufWriter, DuplexStream, Empty, Lines, Repeat, Sink, Split, Take,
     };
 }

tokio/src/io/poll_evented.rs

@@ -121,12 +121,17 @@ impl<E: Source> PollEvented<E> {
     }
 
     /// Returns a reference to the registration
+    #[cfg(any(
+        feature = "net",
+        all(unix, feature = "process"),
+        all(unix, feature = "signal"),
+    ))]
     pub(crate) fn registration(&self) -> &Registration {
         &self.registration
     }
 
     /// Deregister the inner io from the registration and returns a Result containing the inner io
-    #[cfg(feature = "net")]
+    #[cfg(any(feature = "net", feature = "process"))]
     pub(crate) fn into_inner(mut self) -> io::Result<E> {
         let mut inner = self.io.take().unwrap(); // As io shouldn't ever be None, just unwrap here.
         self.registration.deregister(&mut inner)?;

tokio/src/io/read_buf.rs

@@ -113,6 +113,25 @@ impl<'a> ReadBuf<'a> {
         unsafe { mem::transmute::<&mut [MaybeUninit<u8>], &mut [u8]>(slice) }
     }
 
+    /// Returns a mutable reference to the entire buffer, without ensuring that it has been fully
+    /// initialized.
+    ///
+    /// The elements between 0 and `self.filled().len()` are filled, and those between 0 and
+    /// `self.initialized().len()` are initialized (and so can be transmuted to a `&mut [u8]`).
+    ///
+    /// The caller of this method must ensure that these invariants are upheld. For example, if the
+    /// caller initializes some of the uninitialized section of the buffer, it must call
+    /// [`assume_init`](Self::assume_init) with the number of bytes initialized.
+    ///
+    /// # Safety
+    ///
+    /// The caller must not de-initialize portions of the buffer that have already been initialized.
+    /// This includes any bytes in the region marked as uninitialized by `ReadBuf`.
+    #[inline]
+    pub unsafe fn inner_mut(&mut self) -> &mut [MaybeUninit<u8>] {
+        self.buf
+    }
+
     /// Returns a mutable reference to the unfilled part of the buffer without ensuring that it has been fully
     /// initialized.
     ///

tokio/src/io/util/async_buf_read_ext.rs

@@ -23,6 +23,8 @@ cfg_io_util! {
         ///
         /// If successful, this function will return the total number of bytes read.
         ///
+        /// If this function returns `Ok(0)`, the stream has reached EOF.
+        ///
         /// # Errors
         ///
         /// This function will ignore all instances of [`ErrorKind::Interrupted`] and

tokio/src/io/util/async_read_ext.rs

@@ -35,7 +35,7 @@ cfg_io_util! {
 
     /// Reads bytes from a source.
     ///
-    /// Implemented as an extention trait, adding utility methods to all
+    /// Implemented as an extension trait, adding utility methods to all
     /// [`AsyncRead`] types. Callers will tend to import this trait instead of
     /// [`AsyncRead`].
     ///

tokio/src/io/util/async_seek_ext.rs

@@ -66,6 +66,17 @@ cfg_io_util! {
         {
             seek(self, pos)
         }
+
+        /// Creates a future which will return the current seek position from the
+        /// start of the stream.
+        ///
+        /// This is equivalent to `self.seek(SeekFrom::Current(0))`.
+        fn stream_position(&mut self) -> Seek<'_, Self>
+        where
+            Self: Unpin,
+        {
+            self.seek(SeekFrom::Current(0))
+        }
     }
 }
 

tokio/src/io/util/async_write_ext.rs

@@ -11,7 +11,9 @@ use crate::io::util::write_int::{
     WriteU128, WriteU128Le, WriteU16, WriteU16Le, WriteU32, WriteU32Le, WriteU64, WriteU64Le,
     WriteU8,
 };
+use crate::io::util::write_vectored::{write_vectored, WriteVectored};
 use crate::io::AsyncWrite;
+use std::io::IoSlice;
 
 use bytes::Buf;
 
@@ -35,7 +37,7 @@ cfg_io_util! {
 
     /// Writes bytes to a sink.
     ///
-    /// Implemented as an extention trait, adding utility methods to all
+    /// Implemented as an extension trait, adding utility methods to all
     /// [`AsyncWrite`] types. Callers will tend to import this trait instead of
     /// [`AsyncWrite`].
     ///
@@ -116,6 +118,47 @@ cfg_io_util! {
             write(self, src)
         }
 
+        /// Like [`write`], except that it writes from a slice of buffers.
+        ///
+        /// Equivalent to:
+        ///
+        /// ```ignore
+        /// async fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize>;
+        /// ```
+        ///
+        /// See [`AsyncWrite::poll_write_vectored`] for more details.
+        ///
+        /// # Examples
+        ///
+        /// ```no_run
+        /// use tokio::io::{self, AsyncWriteExt};
+        /// use tokio::fs::File;
+        /// use std::io::IoSlice;
+        ///
+        /// #[tokio::main]
+        /// async fn main() -> io::Result<()> {
+        ///     let mut file = File::create("foo.txt").await?;
+        ///
+        ///     let bufs: &[_] = &[
+        ///         IoSlice::new(b"hello"),
+        ///         IoSlice::new(b" "),
+        ///         IoSlice::new(b"world"),
+        ///     ];
+        ///
+        ///     file.write_vectored(&bufs).await?;
+        ///
+        ///     Ok(())
+        /// }
+        /// ```
+        ///
+        /// [`write`]: AsyncWriteExt::write
+        fn write_vectored<'a, 'b>(&'a mut self, bufs: &'a [IoSlice<'b>]) -> WriteVectored<'a, 'b, Self>
+        where
+            Self: Unpin,
+        {
+            write_vectored(self, bufs)
+        }
+
 
         /// Writes a buffer into this writer, advancing the buffer's internal
         /// cursor.

tokio/src/io/util/copy.rs

@@ -5,18 +5,85 @@ use std::io;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
+#[derive(Debug)]
+pub(super) struct CopyBuffer {
+    read_done: bool,
+    pos: usize,
+    cap: usize,
+    amt: u64,
+    buf: Box<[u8]>,
+}
+
+impl CopyBuffer {
+    pub(super) fn new() -> Self {
+        Self {
+            read_done: false,
+            pos: 0,
+            cap: 0,
+            amt: 0,
+            buf: vec![0; 2048].into_boxed_slice(),
+        }
+    }
+
+    pub(super) fn poll_copy<R, W>(
+        &mut self,
+        cx: &mut Context<'_>,
+        mut reader: Pin<&mut R>,
+        mut writer: Pin<&mut W>,
+    ) -> Poll<io::Result<u64>>
+    where
+        R: AsyncRead + ?Sized,
+        W: AsyncWrite + ?Sized,
+    {
+        loop {
+            // If our buffer is empty, then we need to read some data to
+            // continue.
+            if self.pos == self.cap && !self.read_done {
+                let me = &mut *self;
+                let mut buf = ReadBuf::new(&mut me.buf);
+                ready!(reader.as_mut().poll_read(cx, &mut buf))?;
+                let n = buf.filled().len();
+                if n == 0 {
+                    self.read_done = true;
+                } else {
+                    self.pos = 0;
+                    self.cap = n;
+                }
+            }
+
+            // If our buffer has some data, let's write it out!
+            while self.pos < self.cap {
+                let me = &mut *self;
+                let i = ready!(writer.as_mut().poll_write(cx, &me.buf[me.pos..me.cap]))?;
+                if i == 0 {
+                    return Poll::Ready(Err(io::Error::new(
+                        io::ErrorKind::WriteZero,
+                        "write zero byte into writer",
+                    )));
+                } else {
+                    self.pos += i;
+                    self.amt += i as u64;
+                }
+            }
+
+            // If we've written all the data and we've seen EOF, flush out the
+            // data and finish the transfer.
+            if self.pos == self.cap && self.read_done {
+                ready!(writer.as_mut().poll_flush(cx))?;
+                return Poll::Ready(Ok(self.amt));
+            }
+        }
+    }
+}
+
 /// A future that asynchronously copies the entire contents of a reader into a
 /// writer.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 struct Copy<'a, R: ?Sized, W: ?Sized> {
     reader: &'a mut R,
-    read_done: bool,
     writer: &'a mut W,
-    pos: usize,
-    cap: usize,
-    amt: u64,
-    buf: Box<[u8]>,
+    buf: CopyBuffer,
 }
 
 cfg_io_util! {
@@ -35,8 +102,8 @@ cfg_io_util! {
     ///
     /// # Errors
     ///
-    /// The returned future will finish with an error will return an error
-    /// immediately if any call to `poll_read` or `poll_write` returns an error.
+    /// The returned future will return an error immediately if any call to
+    /// `poll_read` or `poll_write` returns an error.
     ///
     /// # Examples
     ///
@@ -60,12 +127,8 @@ cfg_io_util! {
     {
         Copy {
             reader,
-            read_done: false,
             writer,
-            amt: 0,
-            pos: 0,
-            cap: 0,
-            buf: vec![0; 2048].into_boxed_slice(),
+            buf: CopyBuffer::new()
         }.await
     }
 }
@@ -78,44 +141,9 @@ where
     type Output = io::Result<u64>;
 
     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<u64>> {
-        loop {
-            // If our buffer is empty, then we need to read some data to
-            // continue.
-            if self.pos == self.cap && !self.read_done {
-                let me = &mut *self;
-                let mut buf = ReadBuf::new(&mut me.buf);
-                ready!(Pin::new(&mut *me.reader).poll_read(cx, &mut buf))?;
-                let n = buf.filled().len();
-                if n == 0 {
-                    self.read_done = true;
-                } else {
-                    self.pos = 0;
-                    self.cap = n;
-                }
-            }
+        let me = &mut *self;
 
-            // If our buffer has some data, let's write it out!
-            while self.pos < self.cap {
-                let me = &mut *self;
-                let i = ready!(Pin::new(&mut *me.writer).poll_write(cx, &me.buf[me.pos..me.cap]))?;
-                if i == 0 {
-                    return Poll::Ready(Err(io::Error::new(
-                        io::ErrorKind::WriteZero,
-                        "write zero byte into writer",
-                    )));
-                } else {
-                    self.pos += i;
-                    self.amt += i as u64;
-                }
-            }
-
-            // If we've written all the data and we've seen EOF, flush out the
-            // data and finish the transfer.
-            if self.pos == self.cap && self.read_done {
-                let me = &mut *self;
-                ready!(Pin::new(&mut *me.writer).poll_flush(cx))?;
-                return Poll::Ready(Ok(self.amt));
-            }
-        }
+        me.buf
+            .poll_copy(cx, Pin::new(&mut *me.reader), Pin::new(&mut *me.writer))
     }
 }

tokio/src/io/util/copy_bidirectional.rs

@@ -0,0 +1,119 @@
+use super::copy::CopyBuffer;
+
+use crate::io::{AsyncRead, AsyncWrite};
+
+use std::future::Future;
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+enum TransferState {
+    Running(CopyBuffer),
+    ShuttingDown(u64),
+    Done(u64),
+}
+
+struct CopyBidirectional<'a, A: ?Sized, B: ?Sized> {
+    a: &'a mut A,
+    b: &'a mut B,
+    a_to_b: TransferState,
+    b_to_a: TransferState,
+}
+
+fn transfer_one_direction<A, B>(
+    cx: &mut Context<'_>,
+    state: &mut TransferState,
+    r: &mut A,
+    w: &mut B,
+) -> Poll<io::Result<u64>>
+where
+    A: AsyncRead + AsyncWrite + Unpin + ?Sized,
+    B: AsyncRead + AsyncWrite + Unpin + ?Sized,
+{
+    let mut r = Pin::new(r);
+    let mut w = Pin::new(w);
+
+    loop {
+        match state {
+            TransferState::Running(buf) => {
+                let count = ready!(buf.poll_copy(cx, r.as_mut(), w.as_mut()))?;
+                *state = TransferState::ShuttingDown(count);
+            }
+            TransferState::ShuttingDown(count) => {
+                ready!(w.as_mut().poll_shutdown(cx))?;
+
+                *state = TransferState::Done(*count);
+            }
+            TransferState::Done(count) => return Poll::Ready(Ok(*count)),
+        }
+    }
+}
+
+impl<'a, A, B> Future for CopyBidirectional<'a, A, B>
+where
+    A: AsyncRead + AsyncWrite + Unpin + ?Sized,
+    B: AsyncRead + AsyncWrite + Unpin + ?Sized,
+{
+    type Output = io::Result<(u64, u64)>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        // Unpack self into mut refs to each field to avoid borrow check issues.
+        let CopyBidirectional {
+            a,
+            b,
+            a_to_b,
+            b_to_a,
+        } = &mut *self;
+
+        let a_to_b = transfer_one_direction(cx, a_to_b, &mut *a, &mut *b)?;
+        let b_to_a = transfer_one_direction(cx, b_to_a, &mut *b, &mut *a)?;
+
+        // It is not a problem if ready! returns early because transfer_one_direction for the
+        // other direction will keep returning TransferState::Done(count) in future calls to poll
+        let a_to_b = ready!(a_to_b);
+        let b_to_a = ready!(b_to_a);
+
+        Poll::Ready(Ok((a_to_b, b_to_a)))
+    }
+}
+
+/// Copies data in both directions between `a` and `b`.
+///
+/// This function returns a future that will read from both streams,
+/// writing any data read to the opposing stream.
+/// This happens in both directions concurrently.
+///
+/// If an EOF is observed on one stream, [`shutdown()`] will be invoked on
+/// the other, and reading from that stream will stop. Copying of data in
+/// the other direction will continue.
+///
+/// The future will complete successfully once both directions of communication has been shut down.
+/// A direction is shut down when the reader reports EOF,
+/// at which point [`shutdown()`] is called on the corresponding writer. When finished,
+/// it will return a tuple of the number of bytes copied from a to b
+/// and the number of bytes copied from b to a, in that order.
+///
+/// [`shutdown()`]: crate::io::AsyncWriteExt::shutdown
+///
+/// # Errors
+///
+/// The future will immediately return an error if any IO operation on `a`
+/// or `b` returns an error. Some data read from either stream may be lost (not
+/// written to the other stream) in this case.
+///
+/// # Return value
+///
+/// Returns a tuple of bytes copied `a` to `b` and bytes copied `b` to `a`.
+pub async fn copy_bidirectional<A, B>(a: &mut A, b: &mut B) -> Result<(u64, u64), std::io::Error>
+where
+    A: AsyncRead + AsyncWrite + Unpin + ?Sized,
+    B: AsyncRead + AsyncWrite + Unpin + ?Sized,
+{
+    CopyBidirectional {
+        a,
+        b,
+        a_to_b: TransferState::Running(CopyBuffer::new()),
+        b_to_a: TransferState::Running(CopyBuffer::new()),
+    }
+    .await
+}

tokio/src/io/util/mod.rs

@@ -27,6 +27,9 @@ cfg_io_util! {
     mod copy;
     pub use copy::copy;
 
+    mod copy_bidirectional;
+    pub use copy_bidirectional::copy_bidirectional;
+
     mod copy_buf;
     pub use copy_buf::copy_buf;
 
@@ -48,6 +51,7 @@ cfg_io_util! {
     mod read_line;
 
     mod read_to_end;
+    mod vec_with_initialized;
     cfg_process! {
         pub(crate) use read_to_end::read_to_end;
     }
@@ -70,18 +74,20 @@ cfg_io_util! {
     pub use take::Take;
 
     mod write;
+    mod write_vectored;
     mod write_all;
     mod write_buf;
     mod write_int;
 
 
     // used by `BufReader` and `BufWriter`
-    // https://github.com/rust-lang/rust/blob/master/src/libstd/sys_common/io.rs#L1
+    // https://github.com/rust-lang/rust/blob/master/library/std/src/sys_common/io.rs#L1
     const DEFAULT_BUF_SIZE: usize = 8 * 1024;
 }
 
 cfg_not_io_util! {
     cfg_process! {
+        mod vec_with_initialized;
         mod read_to_end;
         // Used by process
         pub(crate) use read_to_end::read_to_end;

tokio/src/io/util/read_to_end.rs

@@ -1,10 +1,11 @@
-use crate::io::{AsyncRead, ReadBuf};
+use crate::io::util::vec_with_initialized::{into_read_buf_parts, VecU8, VecWithInitialized};
+use crate::io::AsyncRead;
 
 use pin_project_lite::pin_project;
 use std::future::Future;
 use std::io;
 use std::marker::PhantomPinned;
-use std::mem::{self, MaybeUninit};
+use std::mem;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
@@ -13,7 +14,7 @@ pin_project! {
     #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub struct ReadToEnd<'a, R: ?Sized> {
         reader: &'a mut R,
-        buf: &'a mut Vec<u8>,
+        buf: VecWithInitialized<&'a mut Vec<u8>>,
         // The number of bytes appended to buf. This can be less than buf.len() if
         // the buffer was not empty when the operation was started.
         read: usize,
@@ -29,20 +30,19 @@ where
 {
     ReadToEnd {
         reader,
-        buf: buffer,
+        buf: VecWithInitialized::new(buffer),
         read: 0,
         _pin: PhantomPinned,
     }
 }
 
-pub(super) fn read_to_end_internal<R: AsyncRead + ?Sized>(
-    buf: &mut Vec<u8>,
+pub(super) fn read_to_end_internal<V: VecU8, R: AsyncRead + ?Sized>(
+    buf: &mut VecWithInitialized<V>,
     mut reader: Pin<&mut R>,
     num_read: &mut usize,
     cx: &mut Context<'_>,
 ) -> Poll<io::Result<usize>> {
     loop {
-        // safety: The caller promised to prepare the buffer.
         let ret = ready!(poll_read_to_end(buf, reader.as_mut(), cx));
         match ret {
             Err(err) => return Poll::Ready(Err(err)),
@@ -57,8 +57,8 @@ pub(super) fn read_to_end_internal<R: AsyncRead + ?Sized>(
 /// Tries to read from the provided AsyncRead.
 ///
 /// The length of the buffer is increased by the number of bytes read.
-fn poll_read_to_end<R: AsyncRead + ?Sized>(
-    buf: &mut Vec<u8>,
+fn poll_read_to_end<V: VecU8, R: AsyncRead + ?Sized>(
+    buf: &mut VecWithInitialized<V>,
     read: Pin<&mut R>,
     cx: &mut Context<'_>,
 ) -> Poll<io::Result<usize>> {
@@ -68,38 +68,34 @@ fn poll_read_to_end<R: AsyncRead + ?Sized>(
     // of data to return. Simply tacking on an extra DEFAULT_BUF_SIZE space every
     // time is 4,500 times (!) slower than this if the reader has a very small
     // amount of data to return.
-    reserve(buf, 32);
+    buf.reserve(32);
 
-    let mut unused_capacity = ReadBuf::uninit(get_unused_capacity(buf));
+    // Get a ReadBuf into the vector.
+    let mut read_buf = buf.get_read_buf();
 
-    ready!(read.poll_read(cx, &mut unused_capacity))?;
+    let filled_before = read_buf.filled().len();
+    let poll_result = read.poll_read(cx, &mut read_buf);
+    let filled_after = read_buf.filled().len();
+    let n = filled_after - filled_before;
 
-    let n = unused_capacity.filled().len();
-    let new_len = buf.len() + n;
+    // Update the length of the vector using the result of poll_read.
+    let read_buf_parts = into_read_buf_parts(read_buf);
+    buf.apply_read_buf(read_buf_parts);
 
-    // This should no longer even be possible in safe Rust. An implementor
-    // would need to have unsafely *replaced* the buffer inside `ReadBuf`,
-    // which... yolo?
-    assert!(new_len <= buf.capacity());
-    unsafe {
-        buf.set_len(new_len);
+    match poll_result {
+        Poll::Pending => {
+            // In this case, nothing should have been read. However we still
+            // update the vector in case the poll_read call initialized parts of
+            // the vector's unused capacity.
+            debug_assert_eq!(filled_before, filled_after);
+            Poll::Pending
+        }
+        Poll::Ready(Err(err)) => {
+            debug_assert_eq!(filled_before, filled_after);
+            Poll::Ready(Err(err))
+        }
+        Poll::Ready(Ok(())) => Poll::Ready(Ok(n)),
     }
-    Poll::Ready(Ok(n))
-}
-
-/// Allocates more memory and ensures that the unused capacity is prepared for use
-/// with the `AsyncRead`.
-fn reserve(buf: &mut Vec<u8>, bytes: usize) {
-    if buf.capacity() - buf.len() >= bytes {
-        return;
-    }
-    buf.reserve(bytes);
-}
-
-/// Returns the unused capacity of the provided vector.
-fn get_unused_capacity(buf: &mut Vec<u8>) -> &mut [MaybeUninit<u8>] {
-    let uninit = bytes::BufMut::chunk_mut(buf);
-    unsafe { &mut *(uninit as *mut _ as *mut [MaybeUninit<u8>]) }
 }
 
 impl<A> Future for ReadToEnd<'_, A>

tokio/src/io/util/read_to_string.rs

@@ -1,5 +1,6 @@
 use crate::io::util::read_line::finish_string_read;
 use crate::io::util::read_to_end::read_to_end_internal;
+use crate::io::util::vec_with_initialized::VecWithInitialized;
 use crate::io::AsyncRead;
 
 use pin_project_lite::pin_project;
@@ -19,7 +20,7 @@ pin_project! {
         // while reading to postpone utf-8 handling until after reading.
         output: &'a mut String,
         // The actual allocation of the string is moved into this vector instead.
-        buf: Vec<u8>,
+        buf: VecWithInitialized<Vec<u8>>,
         // The number of bytes appended to buf. This can be less than buf.len() if
         // the buffer was not empty when the operation was started.
         read: usize,
@@ -39,27 +40,22 @@ where
     let buf = mem::replace(string, String::new()).into_bytes();
     ReadToString {
         reader,
-        buf,
+        buf: VecWithInitialized::new(buf),
         output: string,
         read: 0,
         _pin: PhantomPinned,
     }
 }
 
-/// # Safety
-///
-/// Before first calling this method, the unused capacity must have been
-/// prepared for use with the provided AsyncRead. This can be done using the
-/// `prepare_buffer` function in `read_to_end.rs`.
-unsafe fn read_to_string_internal<R: AsyncRead + ?Sized>(
+fn read_to_string_internal<R: AsyncRead + ?Sized>(
     reader: Pin<&mut R>,
     output: &mut String,
-    buf: &mut Vec<u8>,
+    buf: &mut VecWithInitialized<Vec<u8>>,
     read: &mut usize,
     cx: &mut Context<'_>,
 ) -> Poll<io::Result<usize>> {
     let io_res = ready!(read_to_end_internal(buf, reader, read, cx));
-    let utf8_res = String::from_utf8(mem::replace(buf, Vec::new()));
+    let utf8_res = String::from_utf8(buf.take());
 
     // At this point both buf and output are empty. The allocation is in utf8_res.
 
@@ -77,7 +73,6 @@ where
     fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
         let me = self.project();
 
-        // safety: The constructor of ReadToString called `prepare_buffer`.
-        unsafe { read_to_string_internal(Pin::new(*me.reader), me.output, me.buf, me.read, cx) }
+        read_to_string_internal(Pin::new(*me.reader), me.output, me.buf, me.read, cx)
     }
 }

tokio/src/io/util/vec_with_initialized.rs

@@ -0,0 +1,132 @@
+use crate::io::ReadBuf;
+use std::mem::MaybeUninit;
+
+mod private {
+    pub trait Sealed {}
+
+    impl Sealed for Vec<u8> {}
+    impl Sealed for &mut Vec<u8> {}
+}
+
+/// A sealed trait that constrains the generic type parameter in `VecWithInitialized<V>`.  That struct's safety relies
+/// on certain invariants upheld by `Vec<u8>`.
+pub(crate) trait VecU8: AsMut<Vec<u8>> + private::Sealed {}
+
+impl VecU8 for Vec<u8> {}
+impl VecU8 for &mut Vec<u8> {}
+/// This struct wraps a `Vec<u8>` or `&mut Vec<u8>`, combining it with a
+/// `num_initialized`, which keeps track of the number of initialized bytes
+/// in the unused capacity.
+///
+/// The purpose of this struct is to remember how many bytes were initialized
+/// through a `ReadBuf` from call to call.
+///
+/// This struct has the safety invariant that the first `num_initialized` of the
+/// vector's allocation must be initialized at any time.
+#[derive(Debug)]
+pub(crate) struct VecWithInitialized<V> {
+    vec: V,
+    // The number of initialized bytes in the vector.
+    // Always between `vec.len()` and `vec.capacity()`.
+    num_initialized: usize,
+}
+
+impl VecWithInitialized<Vec<u8>> {
+    #[cfg(feature = "io-util")]
+    pub(crate) fn take(&mut self) -> Vec<u8> {
+        self.num_initialized = 0;
+        std::mem::take(&mut self.vec)
+    }
+}
+
+impl<V> VecWithInitialized<V>
+where
+    V: VecU8,
+{
+    pub(crate) fn new(mut vec: V) -> Self {
+        // SAFETY: The safety invariants of vector guarantee that the bytes up
+        // to its length are initialized.
+        Self {
+            num_initialized: vec.as_mut().len(),
+            vec,
+        }
+    }
+
+    pub(crate) fn reserve(&mut self, num_bytes: usize) {
+        let vec = self.vec.as_mut();
+        if vec.capacity() - vec.len() >= num_bytes {
+            return;
+        }
+        // SAFETY: Setting num_initialized to `vec.len()` is correct as
+        // `reserve` does not change the length of the vector.
+        self.num_initialized = vec.len();
+        vec.reserve(num_bytes);
+    }
+
+    #[cfg(feature = "io-util")]
+    pub(crate) fn is_empty(&mut self) -> bool {
+        self.vec.as_mut().is_empty()
+    }
+
+    pub(crate) fn get_read_buf<'a>(&'a mut self) -> ReadBuf<'a> {
+        let num_initialized = self.num_initialized;
+
+        // SAFETY: Creating the slice is safe because of the safety invariants
+        // on Vec<u8>. The safety invariants of `ReadBuf` will further guarantee
+        // that no bytes in the slice are de-initialized.
+        let vec = self.vec.as_mut();
+        let len = vec.len();
+        let cap = vec.capacity();
+        let ptr = vec.as_mut_ptr().cast::<MaybeUninit<u8>>();
+        let slice = unsafe { std::slice::from_raw_parts_mut::<'a, MaybeUninit<u8>>(ptr, cap) };
+
+        // SAFETY: This is safe because the safety invariants of
+        // VecWithInitialized say that the first num_initialized bytes must be
+        // initialized.
+        let mut read_buf = ReadBuf::uninit(slice);
+        unsafe {
+            read_buf.assume_init(num_initialized);
+        }
+        read_buf.set_filled(len);
+
+        read_buf
+    }
+
+    pub(crate) fn apply_read_buf(&mut self, parts: ReadBufParts) {
+        let vec = self.vec.as_mut();
+        assert_eq!(vec.as_ptr(), parts.ptr);
+
+        // SAFETY:
+        // The ReadBufParts really does point inside `self.vec` due to the above
+        // check, and the safety invariants of `ReadBuf` guarantee that the
+        // first `parts.initialized` bytes of `self.vec` really have been
+        // initialized. Additionally, `ReadBuf` guarantees that `parts.len` is
+        // at most `parts.initialized`, so the first `parts.len` bytes are also
+        // initialized.
+        //
+        // Note that this relies on the fact that `V` is either `Vec<u8>` or
+        // `&mut Vec<u8>`, so the vector returned by `self.vec.as_mut()` cannot
+        // change from call to call.
+        unsafe {
+            self.num_initialized = parts.initialized;
+            vec.set_len(parts.len);
+        }
+    }
+}
+
+pub(crate) struct ReadBufParts {
+    // Pointer is only used to check that the ReadBuf actually came from the
+    // right VecWithInitialized.
+    ptr: *const u8,
+    len: usize,
+    initialized: usize,
+}
+
+// This is needed to release the borrow on `VecWithInitialized<V>`.
+pub(crate) fn into_read_buf_parts(rb: ReadBuf<'_>) -> ReadBufParts {
+    ReadBufParts {
+        ptr: rb.filled().as_ptr(),
+        len: rb.filled().len(),
+        initialized: rb.initialized().len(),
+    }
+}

tokio/src/io/util/write_vectored.rs

@@ -0,0 +1,47 @@
+use crate::io::AsyncWrite;
+
+use pin_project_lite::pin_project;
+use std::io;
+use std::marker::PhantomPinned;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use std::{future::Future, io::IoSlice};
+
+pin_project! {
+    /// A future to write a slice of buffers to an `AsyncWrite`.
+    #[derive(Debug)]
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
+    pub struct WriteVectored<'a, 'b, W: ?Sized> {
+        writer: &'a mut W,
+        bufs: &'a [IoSlice<'b>],
+        // Make this future `!Unpin` for compatibility with async trait methods.
+        #[pin]
+        _pin: PhantomPinned,
+    }
+}
+
+pub(crate) fn write_vectored<'a, 'b, W>(
+    writer: &'a mut W,
+    bufs: &'a [IoSlice<'b>],
+) -> WriteVectored<'a, 'b, W>
+where
+    W: AsyncWrite + Unpin + ?Sized,
+{
+    WriteVectored {
+        writer,
+        bufs,
+        _pin: PhantomPinned,
+    }
+}
+
+impl<W> Future for WriteVectored<'_, '_, W>
+where
+    W: AsyncWrite + Unpin + ?Sized,
+{
+    type Output = io::Result<usize>;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<usize>> {
+        let me = self.project();
+        Pin::new(&mut *me.writer).poll_write_vectored(cx, me.bufs)
+    }
+}

tokio/src/lib.rs

@@ -1,4 +1,3 @@
-#![doc(html_root_url = "https://docs.rs/tokio/1.0.1")]
 #![allow(
     clippy::cognitive_complexity,
     clippy::large_enum_variant,
@@ -77,7 +76,7 @@
 //!
 //! ### Authoring libraries
 //!
-//! As a library author your goal should be to provide the lighest weight crate
+//! As a library author your goal should be to provide the lightest weight crate
 //! that is based on Tokio. To achieve this you should ensure that you only enable
 //! the features you need. This allows users to pick up your crate without having
 //! to enable unnecessary features.
@@ -411,7 +410,7 @@ mod util;
 /// # Why was `Stream` not included in Tokio 1.0?
 ///
 /// Originally, we had planned to ship Tokio 1.0 with a stable `Stream` type
-/// but unfortunetly the [RFC] had not been merged in time for `Stream` to
+/// but unfortunately the [RFC] had not been merged in time for `Stream` to
 /// reach `std` on a stable compiler in time for the 1.0 release of Tokio. For
 /// this reason, the team has decided to move all `Stream` based utilities to
 /// the [`tokio-stream`] crate. While this is not ideal, once `Stream` has made

tokio/src/loom/std/mod.rs

@@ -74,7 +74,10 @@ pub(crate) mod sync {
         pub(crate) use crate::loom::std::atomic_u8::AtomicU8;
         pub(crate) use crate::loom::std::atomic_usize::AtomicUsize;
 
-        pub(crate) use std::sync::atomic::{fence, spin_loop_hint, AtomicBool, Ordering};
+        pub(crate) use std::sync::atomic::{fence, AtomicBool, Ordering};
+        // TODO: once we bump MSRV to 1.49+, use `hint::spin_loop` instead.
+        #[allow(deprecated)]
+        pub(crate) use std::sync::atomic::spin_loop_hint;
     }
 }
 

tokio/src/macros/cfg.rs

@@ -357,3 +357,21 @@ macro_rules! cfg_coop {
         )*
     }
 }
+
+macro_rules! cfg_not_coop {
+    ($($item:item)*) => {
+        $(
+            #[cfg(not(any(
+                    feature = "fs",
+                    feature = "io-std",
+                    feature = "net",
+                    feature = "process",
+                    feature = "rt",
+                    feature = "signal",
+                    feature = "sync",
+                    feature = "time",
+                    )))]
+            $item
+        )*
+    }
+}

tokio/src/macros/pin.rs

@@ -44,7 +44,7 @@
 /// Stream + Unpin`.
 ///
 /// [`Future`]: trait@std::future::Future
-/// [`Box::pin`]: #
+/// [`Box::pin`]: std::boxed::Box::pin
 ///
 /// # Usage
 ///

tokio/src/macros/select.rs

@@ -14,7 +14,7 @@
 /// branch, which evaluates if none of the other branches match their patterns:
 ///
 /// ```text
-/// else <expression>
+/// else => <expression>
 /// ```
 ///
 /// The macro aggregates all `<async expression>` expressions and runs them
@@ -129,8 +129,24 @@
 ///
 /// ### Fairness
 ///
-/// `select!` randomly picks a branch to check first. This provides some level
-/// of fairness when calling `select!` in a loop with branches that are always
+/// By default, `select!` randomly picks a branch to check first. This provides
+/// some level of fairness when calling `select!` in a loop with branches that
+/// are always ready.
+///
+/// This behavior can be overridden by adding `biased;` to the beginning of the
+/// macro usage. See the examples for details. This will cause `select` to poll
+/// the futures in the order they appear from top to bottom. There are a few
+/// reasons you may want this:
+///
+/// - The random number generation of `tokio::select!` has a non-zero CPU cost
+/// - Your futures may interact in a way where known polling order is significant
+///
+/// But there is an important caveat to this mode. It becomes your responsibility
+/// to ensure that the polling order of your futures is fair. If for example you
+/// are selecting between a stream and a shutdown future, and the stream has a
+/// huge volume of messages and zero or nearly zero time between them, you should
+/// place the shutdown future earlier in the `select!` list to ensure that it is
+/// always polled, and will not be ignored due to the stream being constantly
 /// ready.
 ///
 /// # Panics
@@ -283,6 +299,45 @@
 ///     assert_eq!(res.1, "second");
 /// }
 /// ```
+///
+/// Using the `biased;` mode to control polling order.
+///
+/// ```
+/// #[tokio::main]
+/// async fn main() {
+///     let mut count = 0u8;
+///
+///     loop {
+///         tokio::select! {
+///             // If you run this example without `biased;`, the polling order is
+///             // psuedo-random, and the assertions on the value of count will
+///             // (probably) fail.
+///             biased;
+///
+///             _ = async {}, if count < 1 => {
+///                 count += 1;
+///                 assert_eq!(count, 1);
+///             }
+///             _ = async {}, if count < 2 => {
+///                 count += 1;
+///                 assert_eq!(count, 2);
+///             }
+///             _ = async {}, if count < 3 => {
+///                 count += 1;
+///                 assert_eq!(count, 3);
+///             }
+///             _ = async {}, if count < 4 => {
+///                 count += 1;
+///                 assert_eq!(count, 4);
+///             }
+///
+///             else => {
+///                 break;
+///             }
+///         };
+///     }
+/// }
+/// ```
 #[macro_export]
 #[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
 macro_rules! select {
@@ -300,6 +355,10 @@ macro_rules! select {
 
     // All input is normalized, now transform.
     (@ {
+        // The index of the future to poll first (in bias mode), or the RNG
+        // expression to use to pick a future to poll first.
+        start=$start:expr;
+
         // One `_` for each branch in the `select!` macro. Passing this to
         // `count!` converts $skip to an integer.
         ( $($count:tt)* )
@@ -357,9 +416,11 @@ macro_rules! select {
                 // disabled.
                 let mut is_pending = false;
 
-                // Randomly generate a starting point. This makes `select!` a
-                // bit more fair and avoids always polling the first future.
-                let start = $crate::macros::support::thread_rng_n(BRANCHES);
+                // Choose a starting index to begin polling the futures at. In
+                // practice, this will either be a psuedo-randomly generrated
+                // number by default, or the constant 0 if `biased;` is
+                // supplied.
+                let start = $start;
 
                 for i in 0..BRANCHES {
                     let branch;
@@ -444,42 +505,48 @@ macro_rules! select {
     // These rules match a single `select!` branch and normalize it for
     // processing by the first rule.
 
-    (@ { $($t:tt)* } ) => {
+    (@ { start=$start:expr; $($t:tt)* } ) => {
         // No `else` branch
-        $crate::select!(@{ $($t)*; panic!("all branches are disabled and there is no else branch") })
+        $crate::select!(@{ start=$start; $($t)*; panic!("all branches are disabled and there is no else branch") })
     };
-    (@ { $($t:tt)* } else => $else:expr $(,)?) => {
-        $crate::select!(@{ $($t)*; $else })
+    (@ { start=$start:expr; $($t:tt)* } else => $else:expr $(,)?) => {
+        $crate::select!(@{ start=$start; $($t)*; $else })
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:block, $($r:tt)* ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, } $($r)*)
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:block, $($r:tt)* ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, } $($r)*)
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:block, $($r:tt)* ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, } $($r)*)
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:block, $($r:tt)* ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, } $($r)*)
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:block $($r:tt)* ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, } $($r)*)
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:block $($r:tt)* ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, } $($r)*)
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:block $($r:tt)* ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, } $($r)*)
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:block $($r:tt)* ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, } $($r)*)
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:expr ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, })
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:expr ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, })
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:expr ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, })
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:expr ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, })
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:expr, $($r:tt)* ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, } $($r)*)
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr, if $c:expr => $h:expr, $($r:tt)* ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if $c => $h, } $($r)*)
     };
-    (@ { ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:expr, $($r:tt)* ) => {
-        $crate::select!(@{ ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, } $($r)*)
+    (@ { start=$start:expr; ( $($s:tt)* ) $($t:tt)* } $p:pat = $f:expr => $h:expr, $($r:tt)* ) => {
+        $crate::select!(@{ start=$start; ($($s)* _) $($t)* ($($s)*) $p = $f, if true => $h, } $($r)*)
     };
 
     // ===== Entry point =====
 
+    (biased; $p:pat = $($t:tt)* ) => {
+        $crate::select!(@{ start=0; () } $p = $($t)*)
+    };
+
     ( $p:pat = $($t:tt)* ) => {
-        $crate::select!(@{ () } $p = $($t)*)
+        // Randomly generate a starting point. This makes `select!` a bit more
+        // fair and avoids always polling the first future.
+        $crate::select!(@{ start={ $crate::macros::support::thread_rng_n(BRANCHES) }; () } $p = $($t)*)
     };
     () => {
         compile_error!("select! requires at least one branch.")

tokio/src/net/addr.rs

@@ -8,8 +8,6 @@ use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV
 /// # DNS
 ///
 /// Implementations of `ToSocketAddrs` for string types require a DNS lookup.
-/// These implementations are only provided when Tokio is used with the
-/// **`net`** feature flag.
 ///
 /// # Calling
 ///

tokio/src/net/tcp/listener.rs

@@ -64,9 +64,6 @@ impl TcpListener {
     /// method.
     ///
     /// The address type can be any implementor of the [`ToSocketAddrs`] trait.
-    /// Note that strings only implement this trait when the **`net`** feature
-    /// is enabled, as strings may contain domain names that need to be resolved.
-    ///
     /// If `addr` yields multiple addresses, bind will be attempted with each of
     /// the addresses until one succeeds and returns the listener. If none of
     /// the addresses succeed in creating a listener, the error returned from
@@ -74,7 +71,11 @@ impl TcpListener {
     ///
     /// This function sets the `SO_REUSEADDR` option on the socket.
     ///
+    /// To configure the socket before binding, you can use the [`TcpSocket`]
+    /// type.
+    ///
     /// [`ToSocketAddrs`]: trait@crate::net::ToSocketAddrs
+    /// [`TcpSocket`]: struct@crate::net::TcpSocket
     ///
     /// # Examples
     ///
@@ -191,7 +192,6 @@ impl TcpListener {
     /// backing event loop. This allows configuration of options like
     /// `SO_REUSEPORT`, binding to multiple addresses, etc.
     ///
-    ///
     /// # Examples
     ///
     /// ```rust,no_run
@@ -220,6 +220,48 @@ impl TcpListener {
         Ok(TcpListener { io })
     }
 
+    /// Turn a [`tokio::net::TcpListener`] into a [`std::net::TcpListener`].
+    ///
+    /// The returned [`std::net::TcpListener`] will have nonblocking mode set as
+    /// `true`.  Use [`set_nonblocking`] to change the blocking mode if needed.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use std::error::Error;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> Result<(), Box<dyn Error>> {
+    ///     let tokio_listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
+    ///     let std_listener = tokio_listener.into_std()?;
+    ///     std_listener.set_nonblocking(false)?;
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
+    /// [`tokio::net::TcpListener`]: TcpListener
+    /// [`std::net::TcpListener`]: std::net::TcpListener
+    /// [`set_nonblocking`]: fn@std::net::TcpListener::set_nonblocking
+    pub fn into_std(self) -> io::Result<std::net::TcpListener> {
+        #[cfg(unix)]
+        {
+            use std::os::unix::io::{FromRawFd, IntoRawFd};
+            self.io
+                .into_inner()
+                .map(|io| io.into_raw_fd())
+                .map(|raw_fd| unsafe { std::net::TcpListener::from_raw_fd(raw_fd) })
+        }
+
+        #[cfg(windows)]
+        {
+            use std::os::windows::io::{FromRawSocket, IntoRawSocket};
+            self.io
+                .into_inner()
+                .map(|io| io.into_raw_socket())
+                .map(|raw_socket| unsafe { std::net::TcpListener::from_raw_socket(raw_socket) })
+        }
+    }
+
     pub(crate) fn new(listener: mio::net::TcpListener) -> io::Result<TcpListener> {
         let io = PollEvented::new(listener)?;
         Ok(TcpListener { io })

tokio/src/net/tcp/socket.rs

@@ -5,7 +5,7 @@ use std::io;
 use std::net::SocketAddr;
 
 #[cfg(unix)]
-use std::os::unix::io::{AsRawFd, FromRawFd, RawFd};
+use std::os::unix::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd};
 #[cfg(windows)]
 use std::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket};
 
@@ -448,7 +448,7 @@ impl TcpSocket {
     /// `backlog` defines the maximum number of pending connections are queued
     /// by the operating system at any given time. Connection are removed from
     /// the queue with [`TcpListener::accept`]. When the queue is full, the
-    /// operationg-system will start rejecting connections.
+    /// operating-system will start rejecting connections.
     ///
     /// [`TcpListener::accept`]: TcpListener::accept
     ///
@@ -511,6 +511,13 @@ impl FromRawFd for TcpSocket {
     }
 }
 
+#[cfg(unix)]
+impl IntoRawFd for TcpSocket {
+    fn into_raw_fd(self) -> RawFd {
+        self.inner.into_raw_fd()
+    }
+}
+
 #[cfg(windows)]
 impl IntoRawSocket for TcpSocket {
     fn into_raw_socket(self) -> RawSocket {