chore: prepare Tokio v1.4.0 (#3621)

Add `runtime::Handle::block_on`. The function enters the runtime context and
blocks the current thread while the future executes.

Refs: #3097
Fixes #2965, #3096

.cirrus.yml

@@ -1,17 +1,17 @@
 freebsd_instance:
-  image: freebsd-12-0-release-amd64
+  image: freebsd-12-2-release-amd64
 
 # Test FreeBSD in a full VM on cirrus-ci.com.  Test the i686 target too, in the
 # same VM.  The binary will be built in 32-bit mode, but will execute on a
 # 64-bit kernel and in a 64-bit environment.  Our tests don't execute any of
 # the system's binaries, so the environment shouldn't matter.
 task:
-  name: FreeBSD 12.0
+  name: FreeBSD
   env:
     LOOM_MAX_PREEMPTIONS: 2
     RUSTFLAGS: -Dwarnings
   setup_script:
-    - pkg install -y curl
+    - pkg install -y bash curl
     - curl https://sh.rustup.rs -sSf --output rustup.sh
     - sh rustup.sh -y --profile minimal --default-toolchain stable
     - . $HOME/.cargo/env
@@ -19,24 +19,11 @@ task:
     - |
       echo "~~~~ rustc --version ~~~~"
       rustc --version
-
-      # Remove any existing patch statements
-      mv Cargo.toml Cargo.toml.bck
-      sed -n '/\[patch.crates-io\]/q;p' Cargo.toml.bck > Cargo.toml
-
-      # Patch all crates
-      cat ci/patch.toml >> Cargo.toml
-
-      # Print `Cargo.toml` for debugging
-      echo "~~~~ Cargo.toml ~~~~"
-      cat Cargo.toml
-      echo "~~~~~~~~~~~~~~~~~~~~"
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --all
+    - cargo test --all --all-features
     - cargo doc --all --no-deps
-  # TODO: Re-enable
-  # i686_test_script:
-  #   - . $HOME/.cargo/env
-  #   - |
-  #     cargo test --all --exclude tokio-tls --exclude tokio-macros --target i686-unknown-freebsd
+  i686_test_script:
+    - . $HOME/.cargo/env
+    - |
+      cargo test --all --all-features --target i686-unknown-freebsd

.github/ISSUE_TEMPLATE.md

@@ -1,51 +0,0 @@
-<!--
-Thank you for reporting an issue.
-
-Please fill in as much of the template below as you're able.
--->
-
-## 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:
-
-`cargo tree | grep tokio`
--->
-
-## Platform
-
-<!---
-Output of `uname -a` (UNIX), or version and 32 or 64-bit (Windows)
--->
-
-## Subcrates
-
-<!--
-If known, please specify the affected Tokio sub crates. Otherwise, delete this
-section.
--->
-
-## Description
-
-<!--
-
-Enter your issue details below this comment.
-
-One way to structure the description:
-
-<short summary of the bug>
-
-I tried this code:
-
-<code sample that causes the bug>
-
-I expected to see this happen: <explanation>
-
-Instead, this happened: <explanation>
--->

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: A-tokio, C-bug
+assignees: ''
+
+---
+
+**Version**
+List the versions of all `tokio` crates you are using. The easiest way to get
+this information is using `cargo tree` subcommand:
+
+`cargo tree | grep tokio`
+
+**Platform**
+The output of `uname -a` (UNIX), or version and 32 or 64-bit (Windows)
+
+**Description**
+Enter your issue details here.
+One way to structure the description:
+
+[short summary of the bug]
+
+I tried this code:
+
+[code sample that causes the bug]
+
+I expected to see this happen: [explanation]
+
+Instead, this happened: [explanation]

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: A-tokio, C-feature-request
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,16 @@
+---
+name: Question
+about: Please use the discussions tab for questions
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+Please post your question as a discussion here:
+https://github.com/tokio-rs/tokio/discussions
+
+
+You may also be able to find help here:
+https://discord.gg/tokio
+https://users.rust-lang.org/

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,6 +5,9 @@ the requirements below.
 Bug fixes and new features should include tests.
 
 Contributors guide: https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md
+
+The contributors guide includes instructions for running rustfmt and building the
+documentation, which requires special commands beyond `cargo fmt` and `cargo doc`.
 -->
 
 ## Motivation

.github/workflows/audit.yml

@@ -0,0 +1,22 @@
+name: Security Audit
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '**/Cargo.toml'
+  schedule:
+    - cron: '0 2 * * *' # run at 2 AM UTC
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, 'ci skip')"
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Audit Check
+        uses: actions-rs/audit-check@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/bench.yml

@@ -0,0 +1,55 @@
+name: Benchmark
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  benchmark:
+    name: Benchmark
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        bench:
+          - rt_multi_threaded
+          - sync_mpsc
+          - sync_rwlock
+          - sync_semaphore
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update stable
+
+      # Run benchmark with `go test -bench` and stores the output to a file
+      - name: Run benchmark
+        run: cargo bench --bench ${{ matrix.bench }} | tee ../output.txt
+        working-directory: benches
+
+      # Download previous benchmark result from cache (if exists)
+      - name: Download previous benchmark data
+        uses: actions/cache@v1
+        with:
+          path: ./cache
+          key: ${{ runner.os }}-benchmark
+
+      # Run `github-action-benchmark` action
+      - name: Store benchmark result
+        uses: rhysd/github-action-benchmark@v1
+        with:
+          name: ${{ matrix.bench }}
+          # What benchmark tool the output.txt came from
+          tool: 'cargo'
+          # Where the output from the benchmark tool is stored
+          output-file-path: output.txt
+          # # Where the previous data file is stored
+          # external-data-json-path: ./cache/benchmark-data.json
+          # Workflow will fail when an alert happens
+          fail-on-alert: true
+          # GitHub API token to make a commit comment
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          # Enable alert commit comment
+          comment-on-alert: true
+          alert-comment-cc-users: '@tokio-rs/maintainers'
+          auto-push: true
+
+      # Upload the updated cache file for the next job by actions/cache

.github/workflows/ci.yml

@@ -0,0 +1,307 @@
+on:
+  push:
+    branches: ["master", "tokio-*.x"]
+  pull_request:
+    branches: ["master", "tokio-*.x"]
+
+name: CI
+
+env:
+  RUSTFLAGS: -Dwarnings
+  RUST_BACKTRACE: 1
+  nightly: nightly-2020-09-21
+  minrust: 1.45.2
+
+jobs:
+  # Depends on all action sthat are required for a "successful" CI run.
+  tests-pass:
+    name: all systems go
+    runs-on: ubuntu-latest
+    needs:
+      - test
+      - test-unstable
+      - miri
+      - cross
+      - features
+      - minrust
+      - fmt
+      - clippy
+      - docs
+      - loom
+      - valgrind
+    steps:
+      - run: exit 0
+
+  test:
+    name: test tokio full
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - windows-latest
+          - ubuntu-latest
+          - macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update stable
+      - name: Install cargo-hack
+        run: cargo install cargo-hack
+
+      # Run `tokio` with `full` features. This excludes testing utilities which
+      # can alter the runtime behavior of Tokio.
+      - name: test tokio full
+        run: cargo test --features full
+        working-directory: tokio
+
+      # Test **all** crates in the workspace with all features.
+      - name: test all --all-features
+        run: cargo test --workspace --all-features
+
+      # Run integration tests for each feature
+      - name: test tests-integration --each-feature
+        run: cargo hack test --each-feature
+        working-directory: tests-integration
+
+      # Run macro build tests
+      - name: test tests-build --each-feature
+        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 }}
+    strategy:
+      matrix:
+        os:
+          - windows-latest
+          - ubuntu-latest
+          - macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update stable
+
+      # Run `tokio` with "unstable" cfg flag.
+      - name: test tokio full --cfg unstable
+        run: cargo test --features full
+        working-directory: tokio
+        env:
+          RUSTFLAGS: --cfg tokio_unstable -Dwarnings
+
+  miri:
+    name: miri
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ env.nightly }}
+          override: true
+      - name: Install Miri
+        run: |
+          set -e
+          rustup component add miri
+          cargo miri setup
+          rm -rf tokio/tests
+
+      - name: miri
+        run: cargo miri test --features rt,rt-multi-thread,sync task
+        working-directory: tokio
+  san:
+    name: san
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ env.nightly }}
+          override: true
+      - name: asan
+        run: cargo test --all-features --target x86_64-unknown-linux-gnu --lib -- --test-threads 1
+        working-directory: tokio
+        env:
+          RUSTFLAGS: -Z sanitizer=address
+          ASAN_OPTIONS: detect_leaks=0
+
+  cross:
+    name: cross
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target:
+          - i686-unknown-linux-gnu
+          - powerpc-unknown-linux-gnu
+          - powerpc64-unknown-linux-gnu
+          - mips-unknown-linux-gnu
+          - arm-linux-androideabi
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          target: ${{ matrix.target }}
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          use-cross: true
+          command: check
+          args: --workspace --target ${{ matrix.target }}
+
+  features:
+    name: features
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ env.nightly }}
+          override: true
+      - name: Install cargo-hack
+        run: cargo install cargo-hack
+
+      - name: check --each-feature
+        run: cargo hack check --all --each-feature -Z avoid-dev-deps
+
+      # Try with unstable feature flags
+      - name: check --each-feature --unstable
+        run: cargo hack check --all --each-feature -Z avoid-dev-deps
+        env:
+          RUSTFLAGS: --cfg tokio_unstable -Dwarnings
+
+  minrust:
+    name: minrust
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ env.minrust }}
+          override: true
+
+      - name: "test --workspace --all-features"
+        run: cargo check --workspace --all-features
+
+  minimal-versions:
+    name: minimal-versions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ env.nightly }}
+          override: true
+      - name: Install cargo-hack
+        run: cargo install cargo-hack
+      - name: "check --all-features -Z minimal-versions"
+        run: |
+          # Remove dev-dependencies from Cargo.toml to prevent the next `cargo update`
+          # from determining minimal versions based on dev-dependencies.
+          cargo hack --remove-dev-deps --workspace
+          # Update Cargo.lock to minimal version dependencies.
+          cargo update -Z minimal-versions
+          cargo check --all-features
+
+  fmt:
+    name: fmt
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update stable
+      - name: Install rustfmt
+        run: rustup component add rustfmt
+
+      # Check fmt
+      - name: "rustfmt --check"
+        # Workaround for rust-lang/cargo#7732
+        run: |
+          if ! rustfmt --check --edition 2018 $(find . -name '*.rs' -print); then
+            printf "Please run \`rustfmt --edition 2018 \$(find . -name '*.rs' -print)\` to fix rustfmt errors.\nSee CONTRIBUTING.md for more details.\n" >&2
+            exit 1
+          fi
+
+  clippy:
+    name: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update ${{ env.minrust }} && rustup default ${{ env.minrust }}
+      - name: Install clippy
+        run: rustup component add clippy
+
+      # Run clippy
+      - name: "clippy --all"
+        run: cargo clippy --all --tests --all-features
+
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ env.nightly }}
+          override: true
+
+      - name: "doc --lib --all-features"
+        run: cargo doc --lib --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: --cfg docsrs
+
+  loom:
+    name: loom
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        scope:
+          - --skip loom_pool
+          - loom_pool::group_a
+          - loom_pool::group_b
+          - loom_pool::group_c
+          - loom_pool::group_d
+          - time::driver
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        run: rustup update stable
+
+      - name: loom ${{ matrix.scope }}
+        run: cargo test --lib --release --features full -- --nocapture $SCOPE
+        working-directory: tokio
+        env:
+          RUSTFLAGS: --cfg loom --cfg tokio_unstable -Dwarnings
+          LOOM_MAX_PREEMPTIONS: 2
+          SCOPE: ${{ matrix.scope }}

.github/workflows/pr-audit.yml

@@ -0,0 +1,32 @@
+name: Pull Request Security Audit
+
+on:
+  push:
+    paths:
+      - '**/Cargo.toml'
+  pull_request:
+    paths:
+      - '**/Cargo.toml'
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, 'ci skip')"
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install cargo-audit
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: cargo-audit
+
+      - name: Generate lockfile
+        uses: actions-rs/cargo@v1
+        with:
+          command: generate-lockfile
+
+      - name: Audit dependencies
+        uses: actions-rs/cargo@v1
+        with:
+          command: audit

.github/workflows/stress-test.yml

@@ -0,0 +1,32 @@
+name: Stress Test
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  stess-test:
+    name: Stress Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        stress-test:
+          - simple_echo_tcp
+    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
+
+      # Compiles each of the stress test examples.
+      - name: Compile stress test examples
+        run: cargo build -p stress-test --release --example ${{ matrix.stress-test }}
+
+      # Runs each of the examples using Valgrind. Detects leaks and displays them.
+      - name: Run valgrind
+        run: valgrind  --leak-check=full --show-leak-kinds=all ./target/release/examples/${{ matrix.stress-test }}

CONTRIBUTING.md

@@ -15,12 +15,14 @@ It should be considered a map to help you navigate the process.
 The [dev channel][dev] is available for any concerns not covered in this guide, please join
 us!
 
-[dev]: https://discord.gg/6yGkFeN
+[dev]: https://discord.gg/tokio
 
 ## Conduct
 
 The Tokio project adheres to the [Rust Code of Conduct][coc]. This describes
-the _minimum_ behavior expected from all contributors. Instances of violations of the Code of Conduct can be reported by contacting the project team at [[email protected]](mailto:[email protected]).
+the _minimum_ behavior expected from all contributors. Instances of violations of the
+Code of Conduct can be reported by contacting the project team at
+[[email protected]](mailto:[email protected]).
 
 [coc]: https://github.com/rust-lang/rust/blob/master/CODE_OF_CONDUCT.md
 
@@ -29,8 +31,8 @@ the _minimum_ behavior expected from all contributors. Instances of violations o
 For any issue, there are fundamentally three ways an individual can contribute:
 
 1. By opening the issue for discussion: For instance, if you believe that you
-   have uncovered a bug in Tokio, creating a new issue in the tokio-rs/tokio
-   issue tracker is the way to report it.
+   have discovered a bug in Tokio, creating a new issue in [the tokio-rs/tokio
+   issue tracker][issue] is the way to report it.
 
 2. By helping to triage the issue: This can be done by providing
    supporting details (a test case that demonstrates a bug), providing
@@ -42,21 +44,25 @@ For any issue, there are fundamentally three ways an individual can contribute:
    often, by opening a Pull Request that changes some bit of something in
    Tokio in a concrete and reviewable manner.
 
+[issue]: https://github.com/tokio-rs/tokio/issues
+
 **Anybody can participate in any stage of contribution**. We urge you to
 participate in the discussion around bugs and participate in reviewing PRs.
 
 ### Asking for General Help
 
 If you have reviewed existing documentation and still have questions or are
-having problems, you can open an issue asking for help.
+having problems, you can [open a discussion] asking for help.
 
 In exchange for receiving help, we ask that you contribute back a documentation
 PR that helps others avoid the problems that you encountered.
 
+[open a discussion]: https://github.com/tokio-rs/tokio/discussions/new
+
 ### Submitting a Bug Report
 
-When opening a new issue in the Tokio issue tracker, users will be presented
-with a [basic template][template] that should be filled in. If you believe that you have
+When opening a new issue in the Tokio issue tracker, you will be presented
+with a basic template that should be filled in. If you believe that you have
 uncovered a bug, please fill out this form, following the template to the best
 of your ability. Do not worry if you cannot answer every detail, just fill in
 what you can.
@@ -72,7 +78,6 @@ cases should be limited, as much as possible, to using only Tokio APIs.
 See [How to create a Minimal, Complete, and Verifiable example][mcve].
 
 [mcve]: https://stackoverflow.com/help/mcve
-[template]: .github/PULL_REQUEST_TEMPLATE.md
 
 ### Triaging a Bug Report
 
@@ -119,21 +124,36 @@ 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:
+
 ```
+# Mac or Linux
 rustfmt --check --edition 2018 $(find . -name '*.rs' -print)
+
+# Powershell
+Get-ChildItem . -Filter "*.rs" -Recurse | foreach { rustfmt --check --edition 2018 $_.FullName }
 ```
 The `--check` argument prints the things that need to be fixed. If you remove
 it, `rustfmt` will update your files locally instead.
@@ -250,7 +270,7 @@ That said, if you have a number of commits that are "checkpoints" and don't
 represent a single logical change, please squash those together.
 
 Note that multiple commits often get squashed when they are landed (see the
-notes about [commit squashing]).
+notes about [commit squashing](#commit-squashing)).
 
 #### Commit message guidelines
 
@@ -321,7 +341,7 @@ in order to evaluate whether the changes are correct and necessary.
 Keep an eye out for comments from code owners to provide guidance on conflicting
 feedback.
 
-**Once the PR is open, do not rebase the commits**. See [Commit Squashing] for
+**Once the PR is open, do not rebase the commits**. See [Commit Squashing](#commit-squashing) for
 more details.
 
 ### Commit Squashing
@@ -415,6 +435,120 @@ _Adapted from the [Node.js contributing guide][node]_.
 [hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment
 [documentation test]: https://doc.rust-lang.org/rustdoc/documentation-tests.html
 
+## Keeping track of issues and PRs
+
+The Tokio GitHub repository has a lot of issues and PRs to keep track of. This
+section explains the meaning of various labels, as well as our [GitHub
+project][project]. The section is primarily targeted at maintainers.  Most
+contributors aren't able to set these labels.
+
+### Area
+
+The area label describes the crates relevant to this issue or PR.
+
+ - **A-tokio** This issue concerns the main Tokio crate.
+ - **A-tokio-util** This issue concerns the `tokio-util` crate.
+ - **A-tokio-tls** This issue concerns the `tokio-tls` crate. Only used for
+   older issues, as the crate has been moved to another repository.
+ - **A-tokio-test** The issue concerns the `tokio-test` crate.
+ - **A-tokio-macros** This issue concerns the `tokio-macros` crate. Should only
+   be used for the procedural macros, and not `join!` or `select!`.
+ - **A-ci** This issue concerns our GitHub Actions setup.
+
+### Category
+
+ - **C-bug** This is a bug-report. Bug-fix PRs use `C-enhancement` instead.
+ - **C-enhancement** This is a PR that adds a new features.
+ - **C-maintenance** This is an issue or PR about stuff such as documentation,
+   GitHub Actions or code quality.
+ - **C-feature-request** This is a feature request. Implementations of feature
+   requests use `C-enhancement` instead.
+ - **C-feature-accepted** If you submit a PR for this feature request, we wont
+   close it with the reason "we don't want this". Issues with this label should
+   also have the `C-feature-request` label.
+ - **C-musing** Stuff like tracking issues or roadmaps. "musings about a better
+   world"
+ - **C-proposal** A proposal of some kind, and a request for comments.
+ - **C-question** A user question. Large overlap with GitHub discussions.
+ - **C-request** A non-feature request, e.g. "please add deprecation notices to
+   `-alpha.*` versions of crates"
+
+### Calls for participation
+
+ - **E-help-wanted** Stuff where we want help. Often seen together with `C-bug`
+   or `C-feature-accepted`.
+ - **E-easy** This is easy, ranging from quick documentation fixes to stuff you
+   can do after reading the tutorial on our website.
+ - **E-medium** This is not `E-easy` or `E-hard`.
+ - **E-hard** This either involves very tricky code, is something we don't know
+   how to solve, or is difficult for some other reason.
+ - **E-needs-mvce** This bug is missing a minimal complete and verifiable
+   example.
+
+The "E-" prefix is the same as used in the Rust compiler repository. Some
+issues are missing a difficulty rating, but feel free to ask on our Discord
+server if you want to know how difficult an issue likely is.
+
+### Module
+
+The module label provides a more fine grained categorization than **Area**.
+
+ - **M-blocking** Things relevant to `spawn_blocking`, `block_in_place`.
+ - **M-codec** The `tokio_util::codec` module.
+ - **M-compat** The `tokio_util::compat` module.
+ - **M-coop** Things relevant to coop.
+ - **M-fs** The `tokio::fs` module.
+ - **M-io** The `tokio::io` module.
+ - **M-macros** Issues about any kind of macro.
+ - **M-net** The `tokio::net` module.
+ - **M-process** The `tokio::process` module.
+ - **M-runtime** The `tokio::runtime` module.
+ - **M-signal** The `tokio::signal` module.
+ - **M-sync** The `tokio::sync` module.
+ - **M-task** The `tokio::task` module.
+ - **M-time** The `tokio::time` module.
+ - **M-tracing** Tracing support in Tokio.
+
+### Topic
+
+Some extra information.
+
+ - **T-docs** This is about documentation.
+ - **T-performance** This is about performance.
+ - **T-v0.1.x** This is about old Tokio.
+
+Any label not listed here is not in active use.
+
+[project]: https://github.com/orgs/tokio-rs/projects/1
+
+## LTS guarantees
+
+Tokio ≥1.0.0 comes with LTS guarantees:
+
+ * A minimum of 5 years of maintenance.
+ * A minimum of 3 years before a hypothetical 2.0 release.
+
+The goal of these guarantees is to provide stability to the ecosystem.
+
+## Mininum Supported Rust Version (MSRV)
+
+ * All Tokio ≥1.0.0 releases will support at least a 6-month old Rust
+   compiler release.
+ * The MSRV will only be increased on 1.x releases.
+
+## Versioning Policy
+
+With Tokio ≥1.0.0:
+
+ * Patch (1.\_.x) releases _should only_ contain bug fixes or documentation
+   changes. Besides this, these releases should not substantially change
+   runtime behavior.
+ * Minor (1.x) releases may contain new functionality, MSRV increases (see
+   above), minor dependency updates, deprecations, and larger internal
+   implementation changes.
+
+This is as defined by [Semantic Versioning 2.0](https://semver.org/).
+
 ## Releasing
 
 Since the Tokio project consists of a number of crates, many of which depend on
@@ -447,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

Cargo.toml

@@ -4,12 +4,13 @@ members = [
   "tokio",
   "tokio-macros",
   "tokio-test",
-  "tokio-tls",
+  "tokio-stream",
   "tokio-util",
 
   # Internal
   "benches",
   "examples",
+  "stress-test",
   "tests-build",
   "tests-integration",
 ]

README.md

@@ -14,22 +14,21 @@ the Rust programming language. It is:
 
 [![Crates.io][crates-badge]][crates-url]
 [![MIT licensed][mit-badge]][mit-url]
-[![Build Status][azure-badge]][azure-url]
+[![Build Status][actions-badge]][actions-url]
 [![Discord chat][discord-badge]][discord-url]
 
 [crates-badge]: https://img.shields.io/crates/v/tokio.svg
 [crates-url]: https://crates.io/crates/tokio
 [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
-[mit-url]: LICENSE
-[azure-badge]: https://dev.azure.com/tokio-rs/Tokio/_apis/build/status/tokio-rs.tokio?branchName=master
-[azure-url]: https://dev.azure.com/tokio-rs/Tokio/_build/latest?definitionId=1&branchName=master
+[mit-url]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
+[actions-badge]: https://github.com/tokio-rs/tokio/workflows/CI/badge.svg
+[actions-url]: https://github.com/tokio-rs/tokio/actions?query=workflow%3ACI+branch%3Amaster
 [discord-badge]: https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square
 [discord-url]: https://discord.gg/tokio
 
 [Website](https://tokio.rs) |
-[Guides](https://tokio.rs/docs/overview/) |
+[Guides](https://tokio.rs/tokio/tutorial) |
 [API Docs](https://docs.rs/tokio/latest/tokio) |
-[Roadmap](https://github.com/tokio-rs/tokio/blob/master/ROADMAP.md) |
 [Chat](https://discord.gg/tokio)
 
 ## Overview
@@ -55,7 +54,7 @@ A basic TCP echo server with Tokio:
 
 ```rust,no_run
 use tokio::net::TcpListener;
-use tokio::prelude::*;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -90,19 +89,27 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-More examples can be found [here](examples).
+More examples can be found [here][examples]. For a larger "real world" example, see the
+[mini-redis] repository.
+
+[examples]: https://github.com/tokio-rs/tokio/tree/master/examples
+[mini-redis]: https://github.com/tokio-rs/mini-redis/
+
+To see a list of the available features flags that can be enabled, check our
+[docs][feature-flag-docs].
 
 ## Getting Help
 
 First, see if the answer to your question can be found in the [Guides] or the
 [API documentation]. If the answer is not there, there is an active community in
 the [Tokio Discord server][chat]. We would be happy to try to answer your
-question. Last, if that doesn't work, try opening an [issue] with the question.
+question. You can also ask your question on [the discussions page][discussions].
 
-[Guides]: https://tokio.rs/docs/overview/
+[Guides]: https://tokio.rs/tokio/tutorial
 [API documentation]: https://docs.rs/tokio/latest/tokio
 [chat]: https://discord.gg/tokio
-[issue]: https://github.com/tokio-rs/tokio/issues/new
+[discussions]: https://github.com/tokio-rs/tokio/discussions
+[feature-flag-docs]: https://docs.rs/tokio/#feature-flags
 
 ## Contributing
 
@@ -149,15 +156,15 @@ several other libraries, including:
 
 ## Supported Rust Versions
 
-Tokio is built against the latest stable, nightly, and beta Rust releases. The
-minimum version supported is the stable release from three months before the
-current stable release version. For example, if the latest stable Rust is 1.29,
-the minimum version supported is 1.26. The current Tokio version is not
-guaranteed to build on Rust versions earlier than the minimum supported version.
+Tokio is built against the latest stable release. The minimum supported version is 1.45.
+The current Tokio version is not guaranteed to build on Rust versions earlier than the
+minimum supported version.
 
 ## License
 
-This project is licensed under the [MIT license](LICENSE).
+This project is licensed under the [MIT license].
+
+[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
 
 ### Contribution
 

ROADMAP.md

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

SECURITY.md

@@ -0,0 +1,13 @@
+## Report a security issue
+
+The Tokio project team welcomes security reports and is committed to providing prompt attention to security issues. Security issues should be reported privately via [[email protected]](mailto:[email protected]). Security issues should not be reported via the public Github Issue tracker.
+
+## Vulnerability coordination
+
+Remediation of security vulnerabilities is prioritized by the project team. The project team coordinates remediation with third-party project stakeholders via [Github Security Advisories](https://help.github.com/en/github/managing-security-vulnerabilities/about-github-security-advisories). Third-party stakeholders may include the reporter of the issue, affected direct or indirect users of Tokio, and maintainers of upstream dependencies if applicable.
+
+Downstream project maintainers and Tokio users can request participation in coordination of applicable security issues by sending your contact email address, Github username(s) and any other salient information to [[email protected]](mailto:[email protected]). Participation in security issue coordination processes is at the discretion of the Tokio team.
+
+## Security advisories
+
+The project team is committed to transparency in the security issue disclosure process. The Tokio team announces security issues via [project Github Release notes](https://github.com/tokio-rs/tokio/releases) and the [RustSec advisory database](https://github.com/RustSec/advisory-db) (i.e. `cargo-audit`).

azure-pipelines.yml

@@ -1,121 +0,0 @@
-trigger: ["master"]
-pr: ["master"]
-
-variables:
-  RUSTFLAGS: -Dwarnings
-  nightly: nightly-2020-01-25
-
-jobs:
-# Test top level crate
-- template: ci/azure-test-stable.yml
-  parameters:
-    name: test_tokio
-    rust: stable
-    displayName: Test tokio
-    cross: true
-    crates:
-      - tokio
-      - tests-integration
-
-# Test sub crates
-- template: ci/azure-test-stable.yml
-  parameters:
-    name: test_linux
-    displayName: Test sub crates -
-    rust: stable
-    crates:
-      - tokio-macros
-      - tokio-test
-      - tokio-tls
-      - tokio-util
-      - examples
-
-# Run integration tests
-- template: ci/azure-test-integration.yml
-  parameters:
-    name: test_integration
-    displayName: Integration tests
-    rust: stable
-
-# Run tests from `tests-build`. This requires a different process
-- template: ci/azure-test-build.yml
-  parameters:
-    name: test_build
-    displayName: Test build permutations
-    rust: stable
-
-# Run miri tests
-- template: ci/azure-miri.yml
-  parameters:
-    name: miri
-
-# Try cross compiling
-- template: ci/azure-cross-compile.yml
-  parameters:
-    name: cross
-    rust: stable
-
-# Check each feature works properly
-- template: ci/azure-check-features.yml
-  parameters:
-    rust: $(nightly)
-    name: check_features
-
-# This represents the minimum Rust version supported by
-# Tokio. Updating this should be done in a dedicated PR and
-# cannot be greater than two 0.x releases prior to the
-# current stable.
-#
-# Tests are not run as tests may require newer versions of
-# rust.
-- template: ci/azure-check-minrust.yml
-  parameters:
-    name: minrust
-    rust: 1.39.0
-
-# Check formatting
-- template: ci/azure-rustfmt.yml
-  parameters:
-    rust: stable
-    name: rustfmt
-
-# Apply clippy lints to all crates
-- template: ci/azure-clippy.yml
-  parameters:
-    rust: stable
-    name: clippy
-
-# Check doc generation
-- template: ci/azure-check-docs.yml
-  parameters:
-    rust: $(nightly)
-    name: docs
-
-# - template: ci/azure-tsan.yml
-#   parameters:
-#     name: tsan
-#     rust: stable
-
-# Run loom tests
-- template: ci/azure-loom.yml
-  parameters:
-    name: loom
-    rust: stable
-
-- template: ci/azure-deploy-docs.yml
-  parameters:
-    rust: stable
-    dependsOn:
-      - rustfmt
-      - docs
-      - clippy
-      - test_tokio
-      - test_linux
-      - test_integration
-      - test_build
-      - loom
-      - miri
-      - cross
-      - minrust
-      - check_features
-#      - tsan

benches/Cargo.toml

@@ -5,22 +5,25 @@ publish = false
 edition = "2018"
 
 [dependencies]
-tokio = { version = "0.2.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
 bencher = "0.1.5"
 
+[target.'cfg(unix)'.dependencies]
+libc = "0.2.42"
+
 [[bench]]
 name = "spawn"
 path = "spawn.rs"
 harness = false
 
 [[bench]]
-name = "mpsc"
-path = "mpsc.rs"
+name = "sync_mpsc"
+path = "sync_mpsc.rs"
 harness = false
 
 [[bench]]
-name = "scheduler"
-path = "scheduler.rs"
+name = "rt_multi_threaded"
+path = "rt_multi_threaded.rs"
 harness = false
 
 
@@ -33,3 +36,8 @@ harness = false
 name = "sync_semaphore"
 path = "sync_semaphore.rs"
 harness = false
+
+[[bench]]
+name = "signal"
+path = "signal.rs"
+harness = false

benches/rt_multi_threaded.rs

@@ -13,7 +13,7 @@ use std::sync::{mpsc, Arc};
 fn spawn_many(b: &mut Bencher) {
     const NUM_SPAWN: usize = 10_000;
 
-    let mut rt = rt();
+    let rt = rt();
 
     let (tx, rx) = mpsc::sync_channel(1000);
     let rem = Arc::new(AtomicUsize::new(0));
@@ -68,7 +68,7 @@ fn yield_many(b: &mut Bencher) {
 fn ping_pong(b: &mut Bencher) {
     const NUM_PINGS: usize = 1_000;
 
-    let mut rt = rt();
+    let rt = rt();
 
     let (done_tx, done_rx) = mpsc::sync_channel(1000);
     let rem = Arc::new(AtomicUsize::new(0));
@@ -111,7 +111,7 @@ fn ping_pong(b: &mut Bencher) {
 fn chained_spawn(b: &mut Bencher) {
     const ITER: usize = 1_000;
 
-    let mut rt = rt();
+    let rt = rt();
 
     fn iter(done_tx: mpsc::SyncSender<()>, n: usize) {
         if n == 0 {
@@ -139,9 +139,8 @@ fn chained_spawn(b: &mut Bencher) {
 }
 
 fn rt() -> Runtime {
-    runtime::Builder::new()
-        .threaded_scheduler()
-        .core_threads(4)
+    runtime::Builder::new_multi_thread()
+        .worker_threads(4)
         .enable_all()
         .build()
         .unwrap()

benches/signal.rs

@@ -0,0 +1,95 @@
+//! Benchmark the delay in propagating OS signals to any listeners.
+#![cfg(unix)]
+
+use bencher::{benchmark_group, benchmark_main, Bencher};
+use std::future::Future;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::runtime;
+use tokio::signal::unix::{signal, SignalKind};
+use tokio::sync::mpsc;
+
+struct Spinner {
+    count: usize,
+}
+
+impl Future for Spinner {
+    type Output = ();
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        if self.count > 3 {
+            Poll::Ready(())
+        } else {
+            self.count += 1;
+            cx.waker().wake_by_ref();
+            Poll::Pending
+        }
+    }
+}
+
+impl Spinner {
+    fn new() -> Self {
+        Self { count: 0 }
+    }
+}
+
+pub fn send_signal(signal: libc::c_int) {
+    use libc::{getpid, kill};
+
+    unsafe {
+        assert_eq!(kill(getpid(), signal), 0);
+    }
+}
+
+fn many_signals(bench: &mut Bencher) {
+    let num_signals = 10;
+    let (tx, mut rx) = mpsc::channel(num_signals);
+
+    // Intentionally single threaded to measure delays in propagating wakes
+    let rt = runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap();
+
+    let spawn_signal = |kind| {
+        let tx = tx.clone();
+        rt.spawn(async move {
+            let mut signal = signal(kind).expect("failed to create signal");
+
+            while signal.recv().await.is_some() {
+                if tx.send(()).await.is_err() {
+                    break;
+                }
+            }
+        });
+    };
+
+    for _ in 0..num_signals {
+        // Pick some random signals which don't terminate the test harness
+        spawn_signal(SignalKind::child());
+        spawn_signal(SignalKind::io());
+    }
+    drop(tx);
+
+    // Turn the runtime for a while to ensure that all the spawned
+    // tasks have been polled at least once
+    rt.block_on(Spinner::new());
+
+    bench.iter(|| {
+        rt.block_on(async {
+            send_signal(libc::SIGCHLD);
+            for _ in 0..num_signals {
+                rx.recv().await.expect("channel closed");
+            }
+
+            send_signal(libc::SIGIO);
+            for _ in 0..num_signals {
+                rx.recv().await.expect("channel closed");
+            }
+        });
+    });
+}
+
+benchmark_group!(signal_group, many_signals,);
+
+benchmark_main!(signal_group);

benches/spawn.rs

@@ -10,8 +10,7 @@ async fn work() -> usize {
 }
 
 fn basic_scheduler_local_spawn(bench: &mut Bencher) {
-    let mut runtime = tokio::runtime::Builder::new()
-        .basic_scheduler()
+    let runtime = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
     runtime.block_on(async {
@@ -23,8 +22,7 @@ fn basic_scheduler_local_spawn(bench: &mut Bencher) {
 }
 
 fn threaded_scheduler_local_spawn(bench: &mut Bencher) {
-    let mut runtime = tokio::runtime::Builder::new()
-        .threaded_scheduler()
+    let runtime = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
     runtime.block_on(async {
@@ -36,25 +34,21 @@ fn threaded_scheduler_local_spawn(bench: &mut Bencher) {
 }
 
 fn basic_scheduler_remote_spawn(bench: &mut Bencher) {
-    let runtime = tokio::runtime::Builder::new()
-        .basic_scheduler()
+    let runtime = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
-    let handle = runtime.handle();
+
     bench.iter(|| {
-        let h = handle.spawn(work());
+        let h = runtime.spawn(work());
         black_box(h);
     });
 }
 
 fn threaded_scheduler_remote_spawn(bench: &mut Bencher) {
-    let runtime = tokio::runtime::Builder::new()
-        .threaded_scheduler()
-        .build()
-        .unwrap();
-    let handle = runtime.handle();
+    let runtime = tokio::runtime::Builder::new_multi_thread().build().unwrap();
+
     bench.iter(|| {
-        let h = handle.spawn(work());
+        let h = runtime.spawn(work());
         black_box(h);
     });
 }

benches/sync_mpsc.rs

@@ -4,6 +4,13 @@ use tokio::sync::mpsc;
 type Medium = [usize; 64];
 type Large = [Medium; 64];
 
+fn rt() -> tokio::runtime::Runtime {
+    tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
+        .build()
+        .unwrap()
+}
+
 fn create_1_medium(b: &mut Bencher) {
     b.iter(|| {
         black_box(&mpsc::channel::<Medium>(1));
@@ -23,38 +30,38 @@ fn create_100_000_medium(b: &mut Bencher) {
 }
 
 fn send_medium(b: &mut Bencher) {
+    let rt = rt();
+
     b.iter(|| {
-        let (mut tx, mut rx) = mpsc::channel::<Medium>(1000);
+        let (tx, mut rx) = mpsc::channel::<Medium>(1000);
 
-        let _ = tx.try_send([0; 64]);
+        let _ = rt.block_on(tx.send([0; 64]));
 
-        rx.try_recv().unwrap();
+        rt.block_on(rx.recv()).unwrap();
     });
 }
 
 fn send_large(b: &mut Bencher) {
+    let rt = rt();
+
     b.iter(|| {
-        let (mut tx, mut rx) = mpsc::channel::<Large>(1000);
+        let (tx, mut rx) = mpsc::channel::<Large>(1000);
 
-        let _ = tx.try_send([[0; 64]; 64]);
+        let _ = rt.block_on(tx.send([[0; 64]; 64]));
 
-        rx.try_recv().unwrap();
+        rt.block_on(rx.recv()).unwrap();
     });
 }
 
 fn contention_bounded(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
-        .build()
-        .unwrap();
+    let rt = rt();
 
     b.iter(|| {
         rt.block_on(async move {
             let (tx, mut rx) = mpsc::channel::<usize>(1_000_000);
 
             for _ in 0..5 {
-                let mut tx = tx.clone();
+                let tx = tx.clone();
                 tokio::spawn(async move {
                     for i in 0..1000 {
                         tx.send(i).await.unwrap();
@@ -70,18 +77,14 @@ fn contention_bounded(b: &mut Bencher) {
 }
 
 fn contention_bounded_full(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
-        .build()
-        .unwrap();
+    let rt = rt();
 
     b.iter(|| {
         rt.block_on(async move {
             let (tx, mut rx) = mpsc::channel::<usize>(100);
 
             for _ in 0..5 {
-                let mut tx = tx.clone();
+                let tx = tx.clone();
                 tokio::spawn(async move {
                     for i in 0..1000 {
                         tx.send(i).await.unwrap();
@@ -97,11 +100,7 @@ fn contention_bounded_full(b: &mut Bencher) {
 }
 
 fn contention_unbounded(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
-        .build()
-        .unwrap();
+    let rt = rt();
 
     b.iter(|| {
         rt.block_on(async move {
@@ -124,15 +123,11 @@ fn contention_unbounded(b: &mut Bencher) {
 }
 
 fn uncontented_bounded(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
-        .build()
-        .unwrap();
+    let rt = rt();
 
     b.iter(|| {
         rt.block_on(async move {
-            let (mut tx, mut rx) = mpsc::channel::<usize>(1_000_000);
+            let (tx, mut rx) = mpsc::channel::<usize>(1_000_000);
 
             for i in 0..5000 {
                 tx.send(i).await.unwrap();
@@ -146,11 +141,7 @@ fn uncontented_bounded(b: &mut Bencher) {
 }
 
 fn uncontented_unbounded(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
-        .build()
-        .unwrap();
+    let rt = rt();
 
     b.iter(|| {
         rt.block_on(async move {

benches/sync_rwlock.rs

@@ -3,9 +3,8 @@ use std::sync::Arc;
 use tokio::{sync::RwLock, task};
 
 fn read_uncontended(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
         .build()
         .unwrap();
 
@@ -22,9 +21,8 @@ fn read_uncontended(b: &mut Bencher) {
 }
 
 fn read_concurrent_uncontended_multi(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
         .build()
         .unwrap();
 
@@ -51,8 +49,7 @@ fn read_concurrent_uncontended_multi(b: &mut Bencher) {
 }
 
 fn read_concurrent_uncontended(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .basic_scheduler()
+    let rt = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
 
@@ -78,9 +75,8 @@ fn read_concurrent_uncontended(b: &mut Bencher) {
 }
 
 fn read_concurrent_contended_multi(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
         .build()
         .unwrap();
 
@@ -108,8 +104,7 @@ fn read_concurrent_contended_multi(b: &mut Bencher) {
 }
 
 fn read_concurrent_contended(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .basic_scheduler()
+    let rt = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
 

benches/sync_semaphore.rs

@@ -3,9 +3,8 @@ use std::sync::Arc;
 use tokio::{sync::Semaphore, task};
 
 fn uncontended(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
         .build()
         .unwrap();
 
@@ -27,9 +26,8 @@ async fn task(s: Arc<Semaphore>) {
 }
 
 fn uncontended_concurrent_multi(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
         .build()
         .unwrap();
 
@@ -51,8 +49,7 @@ fn uncontended_concurrent_multi(b: &mut Bencher) {
 }
 
 fn uncontended_concurrent_single(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .basic_scheduler()
+    let rt = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
 
@@ -73,9 +70,8 @@ fn uncontended_concurrent_single(b: &mut Bencher) {
 }
 
 fn contended_concurrent_multi(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .core_threads(6)
-        .threaded_scheduler()
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(6)
         .build()
         .unwrap();
 
@@ -97,8 +93,7 @@ fn contended_concurrent_multi(b: &mut Bencher) {
 }
 
 fn contended_concurrent_single(b: &mut Bencher) {
-    let mut rt = tokio::runtime::Builder::new()
-        .basic_scheduler()
+    let rt = tokio::runtime::Builder::new_current_thread()
         .build()
         .unwrap();
 

ci/azure-cargo-check.yml

@@ -1,29 +0,0 @@
-parameters:
-  noDefaultFeatures: '--no-default-features'
-
-jobs:
-- job: ${{ parameters.name }}
-  displayName: ${{ parameters.displayName }}
-  pool:
-    vmImage: ubuntu-16.04
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - template: azure-is-release.yml
-
-  - ${{ each crate in parameters.crates }}:
-    - ${{ each feature in crate.value }}:
-      - script: cargo check ${{ parameters.noDefaultFeatures }} --features ${{ feature }}
-        displayName: Check `${{ crate.key }}`, features = ${{ feature }}
-        workingDirectory: $(Build.SourcesDirectory)/${{ crate.key }}
-        condition: and(succeeded(), not(variables['isRelease']))
-
-  - template: azure-patch-crates.yml
-
-  - ${{ each crate in parameters.crates }}:
-    - ${{ each feature in crate.value }}:
-      - script: cargo check ${{ parameters.noDefaultFeatures }} --features ${{ feature }}
-        displayName: Check `${{ crate.key }}`, features = ${{ feature }}
-        workingDirectory: $(Build.SourcesDirectory)/${{ crate.key }}

ci/azure-check-docs.yml

@@ -1,15 +0,0 @@
-jobs:
-# Check docs
-- job: ${{ parameters.name }}
-  displayName: Check docs
-  pool:
-    vmImage: ubuntu-16.04
-  steps:
-    - template: azure-install-rust.yml
-      parameters:
-        rust_version: ${{ parameters.rust }}
-
-    - script: |
-        RUSTDOCFLAGS="--cfg docsrs" cargo doc --lib --no-deps --all-features
-      displayName: Check docs
-

ci/azure-check-features.yml

@@ -1,32 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: Check features
-  strategy:
-    matrix:
-      Linux:
-        vmImage: ubuntu-16.04
-      MacOS:
-        vmImage: macos-latest
-      Windows:
-        vmImage: vs2017-win2016
-  pool:
-    vmImage: $(vmImage)
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - template: azure-patch-crates.yml
-
-  - script: cargo install cargo-hack
-    displayName: Install cargo-hack
-
-  # Check each feature works properly
-  # * --each-feature
-  #   run for each feature which includes --no-default-features and default features of package
-  # * -Z avoid-dev-deps
-  #   build without dev-dependencies to avoid https://github.com/rust-lang/cargo/issues/4866
-  #   tracking-issue: https://github.com/rust-lang/cargo/issues/5133
-  - script: cargo hack check --all --each-feature -Z avoid-dev-deps
-    displayName: cargo hack check --all --each-feature

ci/azure-check-minrust.yml

@@ -1,14 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: Min supported Rust version
-  pool:
-    vmImage: ubuntu-16.04
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - template: azure-patch-crates.yml
-
-  - script: cargo check --all
-    displayName: cargo check --all

ci/azure-clippy.yml

@@ -1,16 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: Clippy
-  pool:
-    vmImage: ubuntu-16.04
-  steps:
-    - template: azure-install-rust.yml
-      parameters:
-        rust_version: ${{ parameters.rust }}
-    - script: |
-        rustup component add clippy
-        cargo clippy --version
-      displayName: Install clippy
-    - script: |
-        cargo clippy --all --all-features
-      displayName: cargo clippy --all

ci/azure-cross-compile.yml

@@ -1,44 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: ${{ parameters.displayName }}
-  strategy:
-    matrix:
-      i686:
-        vmImage: ubuntu-16.04
-        target: i686-unknown-linux-gnu
-      powerpc:
-        vmImage: ubuntu-16.04
-        target: powerpc-unknown-linux-gnu
-      powerpc64:
-        vmImage: ubuntu-16.04
-        target: powerpc64-unknown-linux-gnu
-      mips:
-        vmImage: ubuntu-16.04
-        target: mips-unknown-linux-gnu
-      arm:
-        vmImage: ubuntu-16.04
-        target: arm-linux-androideabi
-  pool:
-    vmImage: $(vmImage)
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - script: sudo apt-get update
-    displayName: apt-get update
-
-  - script: sudo apt-get install gcc-multilib
-    displayName: Install gcc-multilib
-
-  - script: cargo install cross
-    displayName: Install cross
-
-  # Always patch
-  - template: azure-patch-crates.yml
-
-  - script: cross check --all --exclude tokio-tls --target $(target)
-    displayName: Check source
-
-  # - script: cross check --tests --all --exclude tokio-tls --target $(target)
-  #   displayName: Check tests

ci/azure-deploy-docs.yml

@@ -1,39 +0,0 @@
-parameters:
-  dependsOn: []
-
-jobs:
-- job: documentation
-  displayName: 'Deploy API Documentation'
-  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))
-  pool:
-    vmImage: 'Ubuntu 16.04'
-  dependsOn:
-    - ${{ parameters.dependsOn }}
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      # rust_version: stable
-      rust_version: ${{ parameters.rust }}
-  - script: |
-      cargo doc --all --no-deps --all-features
-      cp -R target/doc '$(Build.BinariesDirectory)'
-    displayName: 'Generate Documentation'
-  - script: |
-      set -e
-
-      git --version
-      ls -la
-      git init
-      git config user.name 'Deployment Bot (from Azure Pipelines)'
-      git config user.email '[email protected]'
-      git config --global credential.helper 'store --file ~/.my-credentials'
-      printf "protocol=https\nhost=github.com\nusername=carllerche\npassword=%s\n\n" "$GITHUB_TOKEN" | git credential-store --file ~/.my-credentials store
-      git remote add origin https://github.com/tokio-rs/tokio
-      git checkout -b gh-pages
-      git add .
-      git commit -m 'Deploy Tokio API documentation'
-      git push -f origin gh-pages
-    env:
-      GITHUB_TOKEN: $(githubPersonalToken)
-    workingDirectory: '$(Build.BinariesDirectory)'
-    displayName: 'Deploy Documentation'

ci/azure-install-rust.yml

@@ -1,40 +0,0 @@
-steps:
-  # Linux and macOS.
-  - script: |
-      set -e
-
-      if [ "$RUSTUP_TOOLCHAIN" == "nightly" ]; then
-        echo "++ getting latest miri version"
-        export RUSTUP_TOOLCHAIN="nightly-$(curl -s https://rust-lang.github.io/rustup-components-history/x86_64-unknown-linux-gnu/miri)"
-        echo "$RUSTUP_TOOLCHAIN"
-      fi
-
-      curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal --default-toolchain none
-      export PATH=$PATH:$HOME/.cargo/bin
-      rustup toolchain install $RUSTUP_TOOLCHAIN
-      rustup default $RUSTUP_TOOLCHAIN
-      echo "##vso[task.setvariable variable=PATH;]$PATH:$HOME/.cargo/bin"
-    env:
-      RUSTUP_TOOLCHAIN: ${{parameters.rust_version}}
-    displayName: "Install rust (*nix)"
-    condition: not(eq(variables['Agent.OS'], 'Windows_NT'))
-
-  # Windows.
-  - script: |
-      curl -sSf -o rustup-init.exe https://win.rustup.rs
-      rustup-init.exe -y --profile minimal --default-toolchain none
-      set PATH=%PATH%;%USERPROFILE%\.cargo\bin
-      rustup toolchain install %RUSTUP_TOOLCHAIN%
-      rustup default %RUSTUP_TOOLCHAIN%
-      echo "##vso[task.setvariable variable=PATH;]%PATH%;%USERPROFILE%\.cargo\bin"
-    env:
-      RUSTUP_TOOLCHAIN: ${{parameters.rust_version}}
-    displayName: "Install rust (windows)"
-    condition: eq(variables['Agent.OS'], 'Windows_NT')
-
-  # All platforms.
-  - script: |
-        rustup toolchain list
-        rustc -Vv
-        cargo -V
-    displayName: Query rust and cargo versions

ci/azure-is-release.yml

@@ -1,9 +0,0 @@
-steps:
-  - bash: |
-      set -e
-
-      if git log --no-merges -1 --format='%B' | grep -qF '[ci-release]'; then
-        echo "##vso[task.setvariable variable=isRelease]true"
-      fi
-    failOnStderr: true
-    displayName: Check if release commit

ci/azure-loom.yml

@@ -1,29 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: Loom tests
-  strategy:
-    matrix:
-      rest:
-        scope: --skip loom_pool
-      pool_group_a:
-        scope: loom_pool::group_a
-      pool_group_b:
-        scope: loom_pool::group_b
-      pool_group_c:
-        scope: loom_pool::group_c
-      pool_group_d:
-        scope: loom_pool::group_d
-  pool:
-    vmImage: ubuntu-16.04
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - script: RUSTFLAGS="--cfg loom" cargo test --lib --release --features "full" -- --nocapture $(scope)
-    env:
-      LOOM_MAX_PREEMPTIONS: 2
-      CI: 'True'
-    displayName: $(scope)
-    workingDirectory: $(Build.SourcesDirectory)/tokio

ci/azure-miri.yml

@@ -1,23 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: Miri
-  pool:
-    vmImage: ubuntu-16.04
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: nightly
-
-  - script: |
-      rustup component add miri
-      cargo miri setup
-      rm -rf $(Build.SourcesDirectory)/tokio/tests
-    displayName: Install miri
-
-  # TODO: enable all tests once they pass
-  - script: cargo miri test --features rt-core,rt-threaded,rt-util,sync -- -- task
-    env:
-      CI: 'True'
-    displayName: cargo miri test
-    workingDirectory: $(Build.SourcesDirectory)/tokio

ci/azure-patch-crates.yml

@@ -1,16 +0,0 @@
-steps:
-  - script: |
-      set -e
-
-      # Remove any existing patch statements
-      mv Cargo.toml Cargo.toml.bck
-      sed -n '/\[patch.crates-io\]/q;p' Cargo.toml.bck > Cargo.toml
-
-      # Patch all crates
-      cat ci/patch.toml >> Cargo.toml
-
-      # Print `Cargo.toml` for debugging
-      echo "~~~~ Cargo.toml ~~~~"
-      cat Cargo.toml
-      echo "~~~~~~~~~~~~~~~~~~~~"
-    displayName: Patch Cargo.toml

ci/azure-rustfmt.yml

@@ -1,18 +0,0 @@
-jobs:
-# Check formatting
-- job: ${{ parameters.name }}
-  displayName: Check rustfmt
-  pool:
-    vmImage: ubuntu-16.04
-  steps:
-    - template: azure-install-rust.yml
-      parameters:
-        rust_version: ${{ parameters.rust }}
-    - script: |
-        rustup component add rustfmt
-        cargo fmt --version
-      displayName: Install rustfmt
-    - script: |
-        # Workaround for rust-lang/cargo#7732
-        rustfmt --check --edition 2018 $(find . -name '*.rs' -print)
-      displayName: Check formatting

ci/azure-test-build.yml

@@ -1,17 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: ${{ parameters.displayName }}
-  pool:
-    vmImage: 'Ubuntu 16.04'
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - script: cargo install cargo-hack
-    displayName: Install cargo-hack
-
-  - script: cargo hack test --each-feature
-    displayName: cargo hack test --each-feature
-    workingDirectory: $(Build.SourcesDirectory)/tests-build

ci/azure-test-integration.yml

@@ -1,28 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: ${{ parameters.displayName }}
-  strategy:
-    matrix:
-      Linux:
-        vmImage: ubuntu-16.04
-      MacOS:
-        vmImage: macos-latest
-      Windows:
-        vmImage: vs2017-win2016
-  pool:
-    vmImage: $(vmImage)
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - script: cargo install cargo-hack
-    displayName: Install cargo-hack
-
-  # Run with all crate features
-  - script: cargo hack test --each-feature
-    env:
-      CI: 'True'
-    displayName: cargo hack test --each-feature
-    workingDirectory: $(Build.SourcesDirectory)/tests-integration

ci/azure-test-nightly.yml

@@ -1,19 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: ${{ parameters.displayName }}
-  pool:
-    vmImage: ubuntu-16.04
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - template: azure-patch-crates.yml
-
-  - script: cargo check --all
-    displayName: cargo check --all
-
-  # Check benches
-  - script: cargo check --benches --all
-    displayName: Check benchmarks

ci/azure-test-stable.yml

@@ -1,47 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: ${{ parameters.displayName }}
-  strategy:
-    matrix:
-      Linux:
-        vmImage: ubuntu-16.04
-
-      ${{ if parameters.cross }}:
-        MacOS:
-          vmImage: macos-latest
-        Windows:
-          vmImage: vs2017-win2016
-  pool:
-    vmImage: $(vmImage)
-
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - template: azure-is-release.yml
-
-  - ${{ each crate in parameters.crates }}:
-    # Run with all crate features
-    - script: cargo test --all-features
-      env:
-        RUST_BACKTRACE: 1
-        CI: 'True'
-      displayName: ${{ crate }} - cargo test --all-features
-      workingDirectory: $(Build.SourcesDirectory)/${{ crate }}
-
-    # Check benches
-    - script: cargo check --all-features --benches
-      displayName: ${{ crate }} - cargo check --benches
-      workingDirectory: $(Build.SourcesDirectory)/${{ crate }}
-
-  - template: azure-patch-crates.yml
-
-  - ${{ each crate in parameters.crates }}:
-    # Run with all crate features
-    - script: cargo test --all-features
-      env:
-        RUST_BACKTRACE: 1
-        CI: 'True'
-      displayName: ${{ crate }} - cargo test --all-features
-      workingDirectory: $(Build.SourcesDirectory)/${{ crate }}

ci/azure-tsan.yml

@@ -1,34 +0,0 @@
-jobs:
-- job: ${{ parameters.name }}
-  displayName: TSAN
-  strategy:
-    matrix:
-      Timer:
-        cmd: cargo test -p tokio-timer --test hammer
-  pool:
-    vmImage: ubuntu-16.04
-  steps:
-  - template: azure-install-rust.yml
-    parameters:
-      rust_version: ${{ parameters.rust }}
-
-  - template: azure-patch-crates.yml
-  - script: |
-        set -e
-
-        # Make sure the benchmarks compile
-        export ASAN_OPTIONS="detect_odr_violation=0 detect_leaks=0"
-        export TSAN_OPTIONS="suppressions=`pwd`/ci/tsan"
-        export RUST_BACKTRACE=1
-
-        # Run address sanitizer
-        RUSTFLAGS="-Z sanitizer=address" \
-        $(cmd) --target x86_64-unknown-linux-gnu
-
-        # Run thread sanitizer
-        RUSTFLAGS="-Z sanitizer=thread" \
-        $(cmd) --target x86_64-unknown-linux-gnu
-    displayName: TSAN / MSAN
-    env:
-      TSAN: yes
-

ci/patch.toml

@@ -1,8 +0,0 @@
-# Patch dependencies to run all tests against versions of the crate in the
-# repository.
-[patch.crates-io]
-tokio = { path = "tokio" }
-tokio-macros = { path = "tokio-macros" }
-tokio-test = { path = "tokio-test" }
-tokio-tls = { path = "tokio-tls" }
-tokio-util = { path = "tokio-util" }

ci/tsan

@@ -1,39 +0,0 @@
-# TSAN suppressions file for Tokio
-
-# TSAN does not understand fences and `Arc::drop` is implemented using a fence.
-# This causes many false positives.
-race:Arc*drop
-race:Weak*drop
-
-# `std` mpsc is not used in any Tokio code base. This race is triggered by some
-# rust runtime logic.
-race:std*mpsc_queue
-race:std*lang_start
-race:drop*std::thread*
-
-# Probably more fences in std.
-race:__call_tls_dtors
-
-# The epoch-based GC uses fences.
-race:crossbeam_epoch
-
-# Push and steal operations in crossbeam-deque may cause data races, but such
-# data races are safe. If a data race happens, the value read by `steal` is
-# forgotten and the steal operation is then retried.
-race:crossbeam_deque*push
-race:crossbeam_deque*steal
-
-# This filters out expected data race in the Treiber stack implementations.
-# Treiber stacks are inherently racy. The pop operation will attempt to access
-# the "next" pointer on the node it is attempting to pop. However, at this
-# point it has not gained ownership of the node and another thread might beat
-# it and take ownership of the node first (touching the next pointer). The
-# original pop operation will fail due to the ABA guard, but tsan still picks
-# up the access on the next pointer.
-race:Backup::next_sleeper
-race:Backup::set_next_sleeper
-race:WorkerEntry::set_next_sleeper
-
-# This ignores a false positive caused by `thread::park()`/`thread::unpark()`.
-# See: https://github.com/rust-lang/rust/pull/54806#issuecomment-436193353
-race:pthread_cond_destroy

examples/Cargo.toml

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

examples/README.md

@@ -13,8 +13,11 @@ A good starting point for the examples would be [`hello_world`](hello_world.rs)
 and [`echo`](echo.rs). Additionally [the tokio website][tokioweb] contains
 additional guides for some of the examples.
 
+For a larger "real world" example, see the [`mini-redis`][redis] repository.
+
 If you've got an example you'd like to see here, please feel free to open an
 issue. Otherwise if you've got an example you'd like to add, please feel free
 to make a PR!
 
-[tokioweb]: https://tokio.rs/docs/overview/
+[tokioweb]: https://tokio.rs/tokio/tutorial
+[redis]: https://github.com/tokio-rs/mini-redis

examples/chat.rs

@@ -27,9 +27,9 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::{TcpListener, TcpStream};
-use tokio::stream::{Stream, StreamExt};
 use tokio::sync::{mpsc, Mutex};
-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,12 +37,30 @@ 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>> {
+    use tracing_subscriber::{fmt::format::FmtSpan, EnvFilter};
+    // Configure a `tracing` subscriber that logs traces emitted by the chat
+    // server.
+    tracing_subscriber::fmt()
+        // Filter what traces are displayed based on the RUST_LOG environment
+        // variable.
+        //
+        // Traces emitted by the example code will always be displayed. You
+        // can set `RUST_LOG=tokio=trace` to enable additional traces emitted by
+        // Tokio itself.
+        .with_env_filter(EnvFilter::from_default_env().add_directive("chat=info".parse()?))
+        // Log events when `tracing` spans are created, entered, exited, or
+        // closed. When Tokio's internal tracing support is enabled (as
+        // described above), this can be used to track the lifecycle of spawned
+        // tasks on the Tokio runtime.
+        .with_span_events(FmtSpan::FULL)
+        // Set this subscriber as the default, to collect all traces emitted by
+        // the program.
+        .init();
+
     // Create the shared state. This is how all the peers communicate.
     //
     // The server task will hold a handle to this. For every new client, the
@@ -57,9 +75,9 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Bind a TCP listener to the socket address.
     //
     // Note that this is the Tokio TcpListener, which is fully async.
-    let mut listener = TcpListener::bind(&addr).await?;
+    let listener = TcpListener::bind(&addr).await?;
 
-    println!("server running on {}", addr);
+    tracing::info!("server running on {}", addr);
 
     loop {
         // Asynchronously wait for an inbound TcpStream.
@@ -70,8 +88,9 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
         // Spawn our handler to be run asynchronously.
         tokio::spawn(async move {
+            tracing::debug!("accepted connection");
             if let Err(e) = process(state, stream, addr).await {
-                println!("an error occurred; error = {:?}", e);
+                tracing::info!("an error occurred; error = {:?}", e);
             }
         });
     }
@@ -147,43 +166,6 @@ impl Peer {
     }
 }
 
-#[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>>,
@@ -200,7 +182,7 @@ async fn process(
         Some(Ok(line)) => line,
         // We didn't get a line so we return early here.
         _ => {
-            println!("Failed to get username from {}. Client disconnected.", addr);
+            tracing::error!("Failed to get username from {}. Client disconnected.", addr);
             return Ok(());
         }
     };
@@ -212,32 +194,37 @@ async fn process(
     {
         let mut state = state.lock().await;
         let msg = format!("{} has joined the chat", username);
-        println!("{}", msg);
+        tracing::info!("{}", msg);
         state.broadcast(addr, &msg).await;
     }
 
     // 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) => {
-                println!(
-                    "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,
+            },
         }
     }
 
@@ -248,7 +235,7 @@ async fn process(
         state.peers.remove(&addr);
 
         let msg = format!("{} has left the chat", username);
-        println!("{}", msg);
+        tracing::info!("{}", msg);
         state.broadcast(addr, &msg).await;
     }
 

examples/connect.rs

@@ -92,11 +92,10 @@ mod tcp {
 
 mod udp {
     use bytes::Bytes;
-    use futures::{future, Sink, SinkExt, Stream, StreamExt};
+    use futures::{Sink, SinkExt, Stream, StreamExt};
     use std::error::Error;
     use std::io;
     use std::net::SocketAddr;
-    use tokio::net::udp::{RecvHalf, SendHalf};
     use tokio::net::UdpSocket;
 
     pub async fn connect(
@@ -114,16 +113,15 @@ mod udp {
 
         let socket = UdpSocket::bind(&bind_addr).await?;
         socket.connect(addr).await?;
-        let (mut r, mut w) = socket.split();
 
-        future::try_join(send(stdin, &mut w), recv(stdout, &mut r)).await?;
+        tokio::try_join!(send(stdin, &socket), recv(stdout, &socket))?;
 
         Ok(())
     }
 
     async fn send(
         mut stdin: impl Stream<Item = Result<Bytes, io::Error>> + Unpin,
-        writer: &mut SendHalf,
+        writer: &UdpSocket,
     ) -> Result<(), io::Error> {
         while let Some(item) = stdin.next().await {
             let buf = item?;
@@ -135,7 +133,7 @@ mod udp {
 
     async fn recv(
         mut stdout: impl Sink<Bytes, Error = io::Error> + Unpin,
-        reader: &mut RecvHalf,
+        reader: &UdpSocket,
     ) -> Result<(), io::Error> {
         loop {
             let mut buf = vec![0; 1024];

examples/custom-executor-tokio-context.rs

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

examples/custom-executor.rs

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

examples/echo-udp.rs

@@ -15,7 +15,6 @@
 use std::error::Error;
 use std::net::SocketAddr;
 use std::{env, io};
-use tokio;
 use tokio::net::UdpSocket;
 
 struct Server {
@@ -27,7 +26,7 @@ struct Server {
 impl Server {
     async fn run(self) -> Result<(), io::Error> {
         let Server {
-            mut socket,
+            socket,
             mut buf,
             mut to_send,
         } = self;

examples/echo.rs

@@ -21,7 +21,6 @@
 
 #![warn(rust_2018_idioms)]
 
-use tokio;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio::net::TcpListener;
 
@@ -40,7 +39,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Next up we create a TCP listener which will listen for incoming
     // connections. This TCP listener is bound to the address we determined
     // above and must be associated with an event loop.
-    let mut listener = TcpListener::bind(&addr).await?;
+    let listener = TcpListener::bind(&addr).await?;
     println!("Listening on: {}", addr);
 
     loop {
@@ -56,7 +55,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
         // which will allow all of our clients to be processed concurrently.
 
         tokio::spawn(async move {
-            let mut buf = [0; 1024];
+            let mut buf = vec![0; 1024];
 
             // In a loop, read data from the socket and write the data back.
             loop {

examples/print_each_packet.rs

@@ -55,7 +55,7 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::TcpListener;
-use tokio::stream::StreamExt;
+use tokio_stream::StreamExt;
 use tokio_util::codec::{BytesCodec, Decoder};
 
 use std::env;
@@ -74,7 +74,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // above and must be associated with an event loop, so we pass in a handle
     // to our event loop. After the socket's created we inform that we're ready
     // to go and start accepting connections.
-    let mut listener = TcpListener::bind(&addr).await?;
+    let listener = TcpListener::bind(&addr).await?;
     println!("Listening on: {}", addr);
 
     loop {

examples/proxy.rs

@@ -23,9 +23,9 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::io;
+use tokio::io::AsyncWriteExt;
 use tokio::net::{TcpListener, TcpStream};
 
-use futures::future::try_join;
 use futures::FutureExt;
 use std::env;
 use std::error::Error;
@@ -42,7 +42,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     println!("Listening on: {}", listen_addr);
     println!("Proxying to: {}", server_addr);
 
-    let mut listener = TcpListener::bind(listen_addr).await?;
+    let listener = TcpListener::bind(listen_addr).await?;
 
     while let Ok((inbound, _)) = listener.accept().await {
         let transfer = transfer(inbound, server_addr.clone()).map(|r| {
@@ -63,10 +63,17 @@ async fn transfer(mut inbound: TcpStream, proxy_addr: String) -> Result<(), Box<
     let (mut ri, mut wi) = inbound.split();
     let (mut ro, mut wo) = outbound.split();
 
-    let client_to_server = io::copy(&mut ri, &mut wo);
-    let server_to_client = io::copy(&mut ro, &mut wi);
+    let client_to_server = async {
+        io::copy(&mut ri, &mut wo).await?;
+        wo.shutdown().await
+    };
 
-    try_join(client_to_server, server_to_client).await?;
+    let server_to_client = async {
+        io::copy(&mut ro, &mut wi).await?;
+        wi.shutdown().await
+    };
+
+    tokio::try_join!(client_to_server, server_to_client)?;
 
     Ok(())
 }

examples/tinydb.rs

@@ -42,7 +42,7 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::TcpListener;
-use tokio::stream::StreamExt;
+use tokio_stream::StreamExt;
 use tokio_util::codec::{Framed, LinesCodec};
 
 use futures::SinkExt;
@@ -89,7 +89,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
         .nth(1)
         .unwrap_or_else(|| "127.0.0.1:8080".to_string());
 
-    let mut listener = TcpListener::bind(&addr).await?;
+    let listener = TcpListener::bind(&addr).await?;
     println!("Listening on: {}", addr);
 
     // Create the shared state of this server that will be shared amongst all

examples/tinyhttp.rs

@@ -18,10 +18,9 @@ use futures::SinkExt;
 use http::{header::HeaderValue, Request, Response, StatusCode};
 #[macro_use]
 extern crate serde_derive;
-use serde_json;
 use std::{env, error::Error, fmt, io};
 use tokio::net::{TcpListener, TcpStream};
-use tokio::stream::StreamExt;
+use tokio_stream::StreamExt;
 use tokio_util::codec::{Decoder, Encoder, Framed};
 
 #[tokio::main]
@@ -31,19 +30,17 @@ async fn main() -> Result<(), Box<dyn Error>> {
     let addr = env::args()
         .nth(1)
         .unwrap_or_else(|| "127.0.0.1:8080".to_string());
-    let mut server = TcpListener::bind(&addr).await?;
-    let mut incoming = server.incoming();
+    let server = TcpListener::bind(&addr).await?;
     println!("Listening on: {}", addr);
 
-    while let Some(Ok(stream)) = incoming.next().await {
+    loop {
+        let (stream, _) = server.accept().await?;
         tokio::spawn(async move {
             if let Err(e) = process(stream).await {
                 println!("failed to process connection; error = {}", e);
             }
         });
     }
-
-    Ok(())
 }
 
 async fn process(stream: TcpStream) -> Result<(), Box<dyn Error>> {

examples/udp-client.rs

@@ -55,7 +55,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     }
     .parse()?;
 
-    let mut socket = UdpSocket::bind(local_addr).await?;
+    let socket = UdpSocket::bind(local_addr).await?;
     const MAX_DATAGRAM_SIZE: usize = 65_507;
     socket.connect(&remote_addr).await?;
     let data = get_stdin_data()?;

examples/udp-codec.rs

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

stress-test/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "stress-test"
+version = "0.1.0"
+authors = ["Tokio Contributors <[email protected]>"]
+edition = "2018"
+publish = false
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+tokio = { path = "../tokio/", features = ["full"] }
+
+[dev-dependencies]
+rand = "0.8"

stress-test/examples/simple_echo_tcp.rs

@@ -0,0 +1,58 @@
+//! Simple TCP echo server to check memory leaks using Valgrind.
+use std::{thread::sleep, time::Duration};
+
+use tokio::{
+    io::{AsyncReadExt, AsyncWriteExt},
+    net::{TcpListener, TcpSocket},
+    runtime::Builder,
+    sync::oneshot,
+};
+
+const TCP_ENDPOINT: &str = "127.0.0.1:8080";
+const NUM_MSGS: usize = 100;
+const MSG_SIZE: usize = 1024;
+
+fn main() {
+    let rt = Builder::new_multi_thread().enable_io().build().unwrap();
+    let rt2 = Builder::new_multi_thread().enable_io().build().unwrap();
+
+    rt.spawn(async {
+        let listener = TcpListener::bind(TCP_ENDPOINT).await.unwrap();
+        let (mut socket, _) = listener.accept().await.unwrap();
+        let (mut rd, mut wr) = socket.split();
+        while tokio::io::copy(&mut rd, &mut wr).await.is_ok() {}
+    });
+
+    // wait a bit so that the listener binds.
+    sleep(Duration::from_millis(100));
+
+    // create a channel to let the main thread know that all the messages were sent and received.
+    let (tx, mut rx) = oneshot::channel();
+
+    rt2.spawn(async {
+        let addr = TCP_ENDPOINT.parse().unwrap();
+        let socket = TcpSocket::new_v4().unwrap();
+        let mut stream = socket.connect(addr).await.unwrap();
+
+        let mut buff = [0; MSG_SIZE];
+        for _ in 0..NUM_MSGS {
+            let one_mega_random_bytes: Vec<u8> =
+                (0..MSG_SIZE).map(|_| rand::random::<u8>()).collect();
+            stream
+                .write_all(one_mega_random_bytes.as_slice())
+                .await
+                .unwrap();
+            stream.read(&mut buff).await.unwrap();
+        }
+        tx.send(()).unwrap();
+    });
+
+    loop {
+        // check that we're done.
+        match rx.try_recv() {
+            Err(oneshot::error::TryRecvError::Empty) => (),
+            Err(oneshot::error::TryRecvError::Closed) => panic!("channel got closed..."),
+            Ok(()) => break,
+        }
+    }
+}

tests-build/Cargo.toml

@@ -7,6 +7,7 @@ publish = false
 
 [features]
 full = ["tokio/full"]
+rt = ["tokio/rt", "tokio/macros"]
 
 [dependencies]
 tokio = { path = "../tokio", optional = true }

tests-build/tests/fail/macros_core_no_default.rs

@@ -0,0 +1,6 @@
+use tests_build::tokio;
+
+#[tokio::main]
+async fn my_fn() {}
+
+fn main() {}

tests-build/tests/fail/macros_core_no_default.stderr

@@ -0,0 +1,7 @@
+error: The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled.
+ --> $DIR/macros_core_no_default.rs:3:1
+  |
+3 | #[tokio::main]
+  | ^^^^^^^^^^^^^^
+  |
+  = note: this error originates in an attribute macro (in Nightly builds, run with -Z macro-backtrace for more info)

tests-build/tests/fail/macros_invalid_input.stderr

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

tests-build/tests/macros.rs

@@ -1,9 +1,12 @@
 #[test]
-fn compile_fail() {
+fn compile_fail_full() {
     let t = trybuild::TestCases::new();
 
     #[cfg(feature = "full")]
     t.compile_fail("tests/fail/macros_invalid_input.rs");
 
+    #[cfg(all(feature = "rt", not(feature = "full")))]
+    t.compile_fail("tests/fail/macros_core_no_default.rs");
+
     drop(t);
 }

tests-integration/Cargo.toml

@@ -5,24 +5,38 @@ 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-core",
-    "rt-threaded",
+    "rt",
+    "rt-multi-thread",
 
     "tokio/full",
     "tokio-test"
 ]
 macros = ["tokio/macros"]
 sync = ["tokio/sync"]
-rt-core = ["tokio/rt-core"]
-rt-threaded = ["rt-core", "tokio/rt-threaded"]
+rt = ["tokio/rt"]
+rt-multi-thread = ["rt", "tokio/rt-multi-thread"]
 
 [dependencies]
 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/macros_main.rs

@@ -1,4 +1,4 @@
-#![cfg(feature = "macros")]
+#![cfg(all(feature = "macros", feature = "rt"))]
 
 #[tokio::main]
 async fn basic_main() -> usize {
@@ -10,18 +10,15 @@ async fn generic_fun<T: Default>() -> T {
     T::default()
 }
 
-#[cfg(feature = "rt-core")]
-mod spawn {
-    #[tokio::main]
-    async fn spawning() -> usize {
-        let join = tokio::spawn(async { 1 });
-        join.await.unwrap()
-    }
+#[tokio::main]
+async fn spawning() -> usize {
+    let join = tokio::spawn(async { 1 });
+    join.await.unwrap()
+}
 
-    #[test]
-    fn main_with_spawn() {
-        assert_eq!(1, spawning());
-    }
+#[test]
+fn main_with_spawn() {
+    assert_eq!(1, spawning());
 }
 
 #[test]

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
 }
@@ -72,7 +65,7 @@ async fn feed_cat(mut cat: Child, n: usize) -> io::Result<ExitStatus> {
     };
 
     // Compose reading and writing concurrently.
-    future::join3(write, read, cat)
+    future::join3(write, read, cat.wait())
         .map(|(_, _, status)| status)
         .await
 }
@@ -125,3 +118,75 @@ async fn status_closes_any_pipes() {
 
     assert_ok!(child.await);
 }
+
+#[tokio::test]
+async fn try_wait() {
+    let mut child = cat().spawn().unwrap();
+
+    let id = child.id().expect("missing id");
+    assert!(id > 0);
+
+    assert_eq!(None, assert_ok!(child.try_wait()));
+
+    // Drop the child's stdio handles so it can terminate
+    drop(child.stdin.take());
+    drop(child.stderr.take());
+    drop(child.stdout.take());
+
+    assert_ok!(child.wait().await);
+
+    // test that the `.try_wait()` method is fused just like the stdlib
+    assert!(assert_ok!(child.try_wait()).unwrap().success());
+
+    // 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());
+}

tests-integration/tests/rt_shell.rs

@@ -1,32 +0,0 @@
-#![warn(rust_2018_idioms)]
-#![cfg(feature = "sync")]
-
-use tokio::runtime;
-use tokio::sync::oneshot;
-
-use std::sync::mpsc;
-use std::thread;
-
-#[test]
-fn basic_shell_rt() {
-    let (feed_tx, feed_rx) = mpsc::channel::<oneshot::Sender<()>>();
-
-    let th = thread::spawn(move || {
-        for tx in feed_rx.iter() {
-            tx.send(()).unwrap();
-        }
-    });
-
-    for _ in 0..1_000 {
-        let mut rt = runtime::Builder::new().build().unwrap();
-
-        let (tx, rx) = oneshot::channel();
-
-        feed_tx.send(tx).unwrap();
-
-        rt.block_on(rx).unwrap();
-    }
-
-    drop(feed_tx);
-    th.join().unwrap();
-}

tokio-macros/CHANGELOG.md

@@ -1,15 +1,37 @@
+# 1.1.0 (February 5, 2021)
+
+- add `start_paused` option to macros ([#3492])
+
+# 1.0.0 (December 23, 2020)
+
+- track `tokio` 1.0 release.
+
+# 0.3.1 (October 25, 2020)
+
+### Fixed
+
+- fix incorrect docs regarding `max_threads` option ([#3038])
+
+# 0.3.0 (October 15, 2020)
+
+- Track `tokio` 0.3 release.
+
+### Changed
+- options are renamed to track `tokio` runtime builder fn names.
+- `#[tokio::main]` macro requires `rt-multi-thread` when no `flavor` is specified.
+
 # 0.2.5 (February 27, 2019)
 
 ### Fixed
-- doc improvements (#2225).
+- doc improvements ([#2225]).
 
 # 0.2.4 (January 27, 2019)
 
 ### Fixed
-- generics on `#[tokio::main]` function (#2177).
+- generics on `#[tokio::main]` function ([#2177]).
 
 ### Added
-- support for `tokio::select!` (#2152).
+- support for `tokio::select!` ([#2152]).
 
 # 0.2.3 (January 7, 2019)
 
@@ -19,13 +41,22 @@
 # 0.2.2 (January 7, 2019)
 
 ### Added
-- General refactoring and inclusion of additional runtime options (#2022 and #2038)
+- General refactoring and inclusion of additional runtime options ([#2022] and [#2038])
 
 # 0.2.1 (December 18, 2019)
 
 ### Fixes
-- inherit visibility when wrapping async fn (#1954).
+- inherit visibility when wrapping async fn ([#1954]).
 
 # 0.2.0 (November 26, 2019)
 
 - Initial release
+
+[#1954]: https://github.com/tokio-rs/tokio/pull/1954
+[#2022]: https://github.com/tokio-rs/tokio/pull/2022
+[#2038]: https://github.com/tokio-rs/tokio/pull/2038
+[#2152]: https://github.com/tokio-rs/tokio/pull/2152
+[#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 "v0.1.x" git tag.
-version = "0.2.5"
+# - Create "tokio-macros-1.0.x" git tag.
+version = "1.1.0"
 edition = "2018"
 authors = ["Tokio Contributors <[email protected]>"]
 license = "MIT"
 repository = "https://github.com/tokio-rs/tokio"
 homepage = "https://tokio.rs"
-documentation = "https://docs.rs/tokio-macros/0.2.5/tokio_macros"
+documentation = "https://docs.rs/tokio-macros/1.1.0/tokio_macros"
 description = """
 Tokio's proc macros.
 """
@@ -30,7 +29,7 @@ quote = "1"
 syn = { version = "1.0.3", features = ["full"] }
 
 [dev-dependencies]
-tokio = { version = "0.2.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
 
 [package.metadata.docs.rs]
 all-features = true

tokio-macros/LICENSE

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

tokio-macros/src/entry.rs

@@ -1,18 +1,183 @@
 use proc_macro::TokenStream;
+use proc_macro2::Span;
 use quote::quote;
-use std::num::NonZeroUsize;
+use syn::spanned::Spanned;
 
 #[derive(Clone, Copy, PartialEq)]
-enum Runtime {
-    Basic,
+enum RuntimeFlavor {
+    CurrentThread,
     Threaded,
 }
 
+impl RuntimeFlavor {
+    fn from_str(s: &str) -> Result<RuntimeFlavor, String> {
+        match s {
+            "current_thread" => Ok(RuntimeFlavor::CurrentThread),
+            "multi_thread" => Ok(RuntimeFlavor::Threaded),
+            "single_thread" => Err("The single threaded runtime flavor is called `current_thread`.".to_string()),
+            "basic_scheduler" => Err("The `basic_scheduler` runtime flavor has been renamed to `current_thread`.".to_string()),
+            "threaded_scheduler" => Err("The `threaded_scheduler` runtime flavor has been renamed to `multi_thread`.".to_string()),
+            _ => Err(format!("No such runtime flavor `{}`. The runtime flavors are `current_thread` and `multi_thread`.", s)),
+        }
+    }
+}
+
+struct FinalConfig {
+    flavor: RuntimeFlavor,
+    worker_threads: Option<usize>,
+    start_paused: Option<bool>,
+}
+
+struct Configuration {
+    rt_multi_thread_available: bool,
+    default_flavor: RuntimeFlavor,
+    flavor: Option<RuntimeFlavor>,
+    worker_threads: Option<(usize, Span)>,
+    start_paused: Option<(bool, Span)>,
+}
+
+impl Configuration {
+    fn new(is_test: bool, rt_multi_thread: bool) -> Self {
+        Configuration {
+            rt_multi_thread_available: rt_multi_thread,
+            default_flavor: match is_test {
+                true => RuntimeFlavor::CurrentThread,
+                false => RuntimeFlavor::Threaded,
+            },
+            flavor: None,
+            worker_threads: None,
+            start_paused: None,
+        }
+    }
+
+    fn set_flavor(&mut self, runtime: syn::Lit, span: Span) -> Result<(), syn::Error> {
+        if self.flavor.is_some() {
+            return Err(syn::Error::new(span, "`flavor` set multiple times."));
+        }
+
+        let runtime_str = parse_string(runtime, span, "flavor")?;
+        let runtime =
+            RuntimeFlavor::from_str(&runtime_str).map_err(|err| syn::Error::new(span, err))?;
+        self.flavor = Some(runtime);
+        Ok(())
+    }
+
+    fn set_worker_threads(
+        &mut self,
+        worker_threads: syn::Lit,
+        span: Span,
+    ) -> Result<(), syn::Error> {
+        if self.worker_threads.is_some() {
+            return Err(syn::Error::new(
+                span,
+                "`worker_threads` set multiple times.",
+            ));
+        }
+
+        let worker_threads = parse_int(worker_threads, span, "worker_threads")?;
+        if worker_threads == 0 {
+            return Err(syn::Error::new(span, "`worker_threads` may not be 0."));
+        }
+        self.worker_threads = Some((worker_threads, span));
+        Ok(())
+    }
+
+    fn set_start_paused(&mut self, start_paused: syn::Lit, span: Span) -> Result<(), syn::Error> {
+        if self.start_paused.is_some() {
+            return Err(syn::Error::new(span, "`start_paused` set multiple times."));
+        }
+
+        let start_paused = parse_bool(start_paused, span, "start_paused")?;
+        self.start_paused = Some((start_paused, span));
+        Ok(())
+    }
+
+    fn build(&self) -> Result<FinalConfig, syn::Error> {
+        let flavor = self.flavor.unwrap_or(self.default_flavor);
+        use RuntimeFlavor::*;
+
+        let worker_threads = match (flavor, self.worker_threads) {
+            (CurrentThread, Some((_, worker_threads_span))) => {
+                return Err(syn::Error::new(
+                    worker_threads_span,
+                    "The `worker_threads` option requires the `multi_thread` runtime flavor.",
+                ))
+            }
+            (CurrentThread, None) => None,
+            (Threaded, worker_threads) if self.rt_multi_thread_available => {
+                worker_threads.map(|(val, _span)| val)
+            }
+            (Threaded, _) => {
+                let msg = if self.flavor.is_none() {
+                    "The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled."
+                } else {
+                    "The runtime flavor `multi_thread` requires the `rt-multi-thread` feature."
+                };
+                return Err(syn::Error::new(Span::call_site(), msg));
+            }
+        };
+
+        let start_paused = match (flavor, self.start_paused) {
+            (Threaded, Some((_, start_paused_span))) => {
+                return Err(syn::Error::new(
+                    start_paused_span,
+                    "The `start_paused` option requires the `current_thread` runtime flavor.",
+                ));
+            }
+            (CurrentThread, Some((start_paused, _))) => Some(start_paused),
+            (_, None) => None,
+        };
+
+        Ok(FinalConfig {
+            flavor,
+            worker_threads,
+            start_paused,
+        })
+    }
+}
+
+fn parse_int(int: syn::Lit, span: Span, field: &str) -> Result<usize, syn::Error> {
+    match int {
+        syn::Lit::Int(lit) => match lit.base10_parse::<usize>() {
+            Ok(value) => Ok(value),
+            Err(e) => Err(syn::Error::new(
+                span,
+                format!("Failed to parse {} as integer: {}", field, e),
+            )),
+        },
+        _ => Err(syn::Error::new(
+            span,
+            format!("Failed to parse {} as integer.", field),
+        )),
+    }
+}
+
+fn parse_string(int: syn::Lit, span: Span, field: &str) -> Result<String, syn::Error> {
+    match int {
+        syn::Lit::Str(s) => Ok(s.value()),
+        syn::Lit::Verbatim(s) => Ok(s.to_string()),
+        _ => Err(syn::Error::new(
+            span,
+            format!("Failed to parse {} 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 {} as bool.", field),
+        )),
+    }
+}
+
 fn parse_knobs(
     mut input: syn::ItemFn,
     args: syn::AttributeArgs,
     is_test: bool,
-    rt_threaded: bool,
+    rt_multi_thread: bool,
 ) -> Result<TokenStream, syn::Error> {
     let sig = &mut input.sig;
     let body = &input.block;
@@ -26,9 +191,12 @@ fn parse_knobs(
 
     sig.asyncness = None;
 
-    let mut runtime = None;
-    let mut core_threads = None;
-    let mut max_threads = None;
+    let macro_name = if is_test {
+        "tokio::test"
+    } else {
+        "tokio::main"
+    };
+    let mut config = Configuration::new(is_test, rt_multi_thread);
 
     for arg in args {
         match arg {
@@ -39,65 +207,21 @@ fn parse_knobs(
                     return Err(syn::Error::new_spanned(namevalue, msg));
                 }
                 match ident.unwrap().to_string().to_lowercase().as_str() {
-                    "core_threads" => {
-                        if rt_threaded {
-                            match &namevalue.lit {
-                                syn::Lit::Int(expr) => {
-                                    let num = expr.base10_parse::<NonZeroUsize>().unwrap();
-                                    if num.get() > 1 {
-                                        runtime = Some(Runtime::Threaded);
-                                    } else {
-                                        runtime = Some(Runtime::Basic);
-                                    }
-
-                                    if let Some(v) = max_threads {
-                                        if v < num {
-                                            return Err(syn::Error::new_spanned(
-                                                namevalue,
-                                                "max_threads cannot be less than core_threads",
-                                            ));
-                                        }
-                                    }
-
-                                    core_threads = Some(num);
-                                }
-                                _ => {
-                                    return Err(syn::Error::new_spanned(
-                                        namevalue,
-                                        "core_threads argument must be an int",
-                                    ))
-                                }
-                            }
-                        } else {
-                            return Err(syn::Error::new_spanned(
-                                namevalue,
-                                "core_threads can only be set with rt-threaded feature flag enabled",
-                            ));
-                        }
+                    "worker_threads" => {
+                        config.set_worker_threads(namevalue.lit.clone(), namevalue.span())?;
+                    }
+                    "flavor" => {
+                        config.set_flavor(namevalue.lit.clone(), namevalue.span())?;
+                    }
+                    "start_paused" => {
+                        config.set_start_paused(namevalue.lit.clone(), namevalue.span())?;
+                    }
+                    "core_threads" => {
+                        let msg = "Attribute `core_threads` is renamed to `worker_threads`";
+                        return Err(syn::Error::new_spanned(namevalue, msg));
                     }
-                    "max_threads" => match &namevalue.lit {
-                        syn::Lit::Int(expr) => {
-                            let num = expr.base10_parse::<NonZeroUsize>().unwrap();
-
-                            if let Some(v) = core_threads {
-                                if num < v {
-                                    return Err(syn::Error::new_spanned(
-                                        namevalue,
-                                        "max_threads cannot be less than core_threads",
-                                    ));
-                                }
-                            }
-                            max_threads = Some(num);
-                        }
-                        _ => {
-                            return Err(syn::Error::new_spanned(
-                                namevalue,
-                                "max_threads argument must be an int",
-                            ))
-                        }
-                    },
                     name => {
-                        let msg = format!("Unknown attribute pair {} is specified; expected one of: `core_threads`, `max_threads`", name);
+                        let msg = format!("Unknown attribute {} is specified; expected one of: `flavor`, `worker_threads`", name);
                         return Err(syn::Error::new_spanned(namevalue, msg));
                     }
                 }
@@ -108,16 +232,28 @@ fn parse_knobs(
                     let msg = "Must have specified ident";
                     return Err(syn::Error::new_spanned(path, msg));
                 }
-                match ident.unwrap().to_string().to_lowercase().as_str() {
-                    "threaded_scheduler" => {
-                        runtime = Some(runtime.unwrap_or_else(|| Runtime::Threaded))
+                let name = ident.unwrap().to_string().to_lowercase();
+                let msg = match name.as_str() {
+                    "threaded_scheduler" | "multi_thread" => {
+                        format!(
+                            "Set the runtime flavor with #[{}(flavor = \"multi_thread\")].",
+                            macro_name
+                        )
+                    }
+                    "basic_scheduler" | "current_thread" | "single_threaded" => {
+                        format!(
+                            "Set the runtime flavor with #[{}(flavor = \"current_thread\")].",
+                            macro_name
+                        )
+                    }
+                    "flavor" | "worker_threads" | "start_paused" => {
+                        format!("The `{}` attribute requires an argument.", name)
                     }
-                    "basic_scheduler" => runtime = Some(runtime.unwrap_or_else(|| Runtime::Basic)),
                     name => {
-                        let msg = format!("Unknown attribute {} is specified; expected `basic_scheduler` or `threaded_scheduler`", name);
-                        return Err(syn::Error::new_spanned(path, msg));
+                        format!("Unknown attribute {} is specified; expected one of: `flavor`, `worker_threads`, `start_paused`", name)
                     }
-                }
+                };
+                return Err(syn::Error::new_spanned(path, msg));
             }
             other => {
                 return Err(syn::Error::new_spanned(
@@ -128,21 +264,27 @@ fn parse_knobs(
         }
     }
 
-    let mut rt = quote! { tokio::runtime::Builder::new().basic_scheduler() };
-    if rt_threaded && (runtime == Some(Runtime::Threaded) || (runtime.is_none() && !is_test)) {
-        rt = quote! { #rt.threaded_scheduler() };
+    let config = config.build()?;
+
+    let mut rt = match config.flavor {
+        RuntimeFlavor::CurrentThread => quote! {
+            tokio::runtime::Builder::new_current_thread()
+        },
+        RuntimeFlavor::Threaded => quote! {
+            tokio::runtime::Builder::new_multi_thread()
+        },
+    };
+    if let Some(v) = config.worker_threads {
+        rt = quote! { #rt.worker_threads(#v) };
     }
-    if let Some(v) = core_threads.map(|v| v.get()) {
-        rt = quote! { #rt.core_threads(#v) };
-    }
-    if let Some(v) = max_threads.map(|v| v.get()) {
-        rt = quote! { #rt.max_threads(#v) };
+    if let Some(v) = config.start_paused {
+        rt = quote! { #rt.start_paused(#v) };
     }
 
     let header = {
         if is_test {
             quote! {
-                #[test]
+                #[::core::prelude::v1::test]
             }
         } else {
             quote! {}
@@ -157,7 +299,7 @@ fn parse_knobs(
                 .enable_all()
                 .build()
                 .unwrap()
-                .block_on(async { #body })
+                .block_on(async #body)
         }
     };
 
@@ -165,21 +307,21 @@ fn parse_knobs(
 }
 
 #[cfg(not(test))] // Work around for rust-lang/rust#62127
-pub(crate) fn main(args: TokenStream, item: TokenStream, rt_threaded: bool) -> TokenStream {
+pub(crate) fn main(args: TokenStream, item: TokenStream, rt_multi_thread: bool) -> TokenStream {
     let input = syn::parse_macro_input!(item as syn::ItemFn);
     let args = syn::parse_macro_input!(args as syn::AttributeArgs);
 
     if input.sig.ident == "main" && !input.sig.inputs.is_empty() {
         let msg = "the main function cannot accept arguments";
-        return syn::Error::new_spanned(&input.sig.inputs, msg)
+        return syn::Error::new_spanned(&input.sig.ident, msg)
             .to_compile_error()
             .into();
     }
 
-    parse_knobs(input, args, false, rt_threaded).unwrap_or_else(|e| e.to_compile_error().into())
+    parse_knobs(input, args, false, rt_multi_thread).unwrap_or_else(|e| e.to_compile_error().into())
 }
 
-pub(crate) fn test(args: TokenStream, item: TokenStream, rt_threaded: bool) -> TokenStream {
+pub(crate) fn test(args: TokenStream, item: TokenStream, rt_multi_thread: bool) -> TokenStream {
     let input = syn::parse_macro_input!(item as syn::ItemFn);
     let args = syn::parse_macro_input!(args as syn::AttributeArgs);
 
@@ -199,161 +341,5 @@ pub(crate) fn test(args: TokenStream, item: TokenStream, rt_threaded: bool) -> T
             .into();
     }
 
-    parse_knobs(input, args, true, rt_threaded).unwrap_or_else(|e| e.to_compile_error().into())
-}
-
-pub(crate) mod old {
-    use proc_macro::TokenStream;
-    use quote::quote;
-
-    enum Runtime {
-        Basic,
-        Threaded,
-        Auto,
-    }
-
-    #[cfg(not(test))] // Work around for rust-lang/rust#62127
-    pub(crate) fn main(args: TokenStream, item: TokenStream) -> TokenStream {
-        let mut input = syn::parse_macro_input!(item as syn::ItemFn);
-        let args = syn::parse_macro_input!(args as syn::AttributeArgs);
-
-        let sig = &mut input.sig;
-        let name = &sig.ident;
-        let inputs = &sig.inputs;
-        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 syn::Error::new_spanned(sig.fn_token, msg)
-                .to_compile_error()
-                .into();
-        } else if name == "main" && !inputs.is_empty() {
-            let msg = "the main function cannot accept arguments";
-            return syn::Error::new_spanned(&sig.inputs, msg)
-                .to_compile_error()
-                .into();
-        }
-
-        sig.asyncness = None;
-
-        let mut runtime = Runtime::Auto;
-
-        for arg in args {
-            if let syn::NestedMeta::Meta(syn::Meta::Path(path)) = arg {
-                let ident = path.get_ident();
-                if ident.is_none() {
-                    let msg = "Must have specified ident";
-                    return syn::Error::new_spanned(path, msg).to_compile_error().into();
-                }
-                match ident.unwrap().to_string().to_lowercase().as_str() {
-                    "threaded_scheduler" => runtime = Runtime::Threaded,
-                    "basic_scheduler" => runtime = Runtime::Basic,
-                    name => {
-                        let msg = format!("Unknown attribute {} is specified; expected `basic_scheduler` or `threaded_scheduler`", name);
-                        return syn::Error::new_spanned(path, msg).to_compile_error().into();
-                    }
-                }
-            }
-        }
-
-        let result = match runtime {
-            Runtime::Threaded | Runtime::Auto => quote! {
-                #(#attrs)*
-                #vis #sig {
-                    tokio::runtime::Runtime::new().unwrap().block_on(async { #body })
-                }
-            },
-            Runtime::Basic => quote! {
-                #(#attrs)*
-                #vis #sig {
-                    tokio::runtime::Builder::new()
-                        .basic_scheduler()
-                        .enable_all()
-                        .build()
-                        .unwrap()
-                        .block_on(async { #body })
-                }
-            },
-        };
-
-        result.into()
-    }
-
-    pub(crate) fn test(args: TokenStream, item: TokenStream) -> TokenStream {
-        let input = syn::parse_macro_input!(item as syn::ItemFn);
-        let args = syn::parse_macro_input!(args as syn::AttributeArgs);
-
-        let ret = &input.sig.output;
-        let name = &input.sig.ident;
-        let body = &input.block;
-        let attrs = &input.attrs;
-        let vis = input.vis;
-
-        for attr in attrs {
-            if attr.path.is_ident("test") {
-                let msg = "second test attribute is supplied";
-                return syn::Error::new_spanned(&attr, msg)
-                    .to_compile_error()
-                    .into();
-            }
-        }
-
-        if input.sig.asyncness.is_none() {
-            let msg = "the async keyword is missing from the function declaration";
-            return syn::Error::new_spanned(&input.sig.fn_token, msg)
-                .to_compile_error()
-                .into();
-        } else 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();
-        }
-
-        let mut runtime = Runtime::Auto;
-
-        for arg in args {
-            if let syn::NestedMeta::Meta(syn::Meta::Path(path)) = arg {
-                let ident = path.get_ident();
-                if ident.is_none() {
-                    let msg = "Must have specified ident";
-                    return syn::Error::new_spanned(path, msg).to_compile_error().into();
-                }
-                match ident.unwrap().to_string().to_lowercase().as_str() {
-                    "threaded_scheduler" => runtime = Runtime::Threaded,
-                    "basic_scheduler" => runtime = Runtime::Basic,
-                    name => {
-                        let msg = format!("Unknown attribute {} is specified; expected `basic_scheduler` or `threaded_scheduler`", name);
-                        return syn::Error::new_spanned(path, msg).to_compile_error().into();
-                    }
-                }
-            }
-        }
-
-        let result = match runtime {
-            Runtime::Threaded => quote! {
-                #[test]
-                #(#attrs)*
-                #vis fn #name() #ret {
-                    tokio::runtime::Runtime::new().unwrap().block_on(async { #body })
-                }
-            },
-            Runtime::Basic | Runtime::Auto => quote! {
-                #[test]
-                #(#attrs)*
-                #vis fn #name() #ret {
-                    tokio::runtime::Builder::new()
-                        .basic_scheduler()
-                        .enable_all()
-                        .build()
-                        .unwrap()
-                        .block_on(async { #body })
-                }
-            },
-        };
-
-        result.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/0.2.5")]
 #![allow(clippy::needless_doctest_main)]
 #![warn(
     missing_debug_implementations,
@@ -6,7 +5,7 @@
     rust_2018_idioms,
     unreachable_pub
 )]
-#![deny(intra_doc_link_resolution_failure)]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 #![doc(test(
     no_crate_inject,
     attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
@@ -24,13 +23,47 @@ mod select;
 
 use proc_macro::TokenStream;
 
-/// Marks async function to be executed by selected runtime.
+/// Marks async function to be executed by the selected runtime. This macro
+/// helps set up a `Runtime` without requiring the user to use
+/// [Runtime](../tokio/runtime/struct.Runtime.html) or
+/// [Builder](../tokio/runtime/struct.Builder.html) directly.
 ///
-/// ## Options:
+/// Note: This macro is designed to be simplistic and targets applications that
+/// do not require a complex setup. If the provided functionality is not
+/// sufficient, you may be interested in using
+/// [Builder](../tokio/runtime/struct.Builder.html), which provides a more
+/// powerful interface.
 ///
+/// Note: This macro can be used on any function and not just the `main`
+/// function. Using it on a non-main function makes the function behave as if it
+/// was synchronous by starting a new runtime each time it is called. If the
+/// function is called often, it is preferable to create the runtime using the
+/// runtime builder so the runtime can be reused across calls.
 ///
-/// - `core_threads=n` - Sets core threads to `n` (requires `rt-threaded` feature).
-/// - `max_threads=n` - Sets max threads to `n` (requires `rt-core` or `rt-threaded` feature).
+/// # Multi-threaded runtime
+///
+/// To use the multi-threaded runtime, the macro can be configured using
+///
+/// ```
+/// #[tokio::main(flavor = "multi_thread", worker_threads = 10)]
+/// # async fn main() {}
+/// ```
+///
+/// The `worker_threads` option configures the number of worker threads, and
+/// defaults to the number of cpus on the system. This is the default flavor.
+///
+/// Note: The multi-threaded runtime requires the `rt-multi-thread` feature
+/// flag.
+///
+/// # Current thread runtime
+///
+/// To use the single-threaded runtime known as the `current_thread` runtime,
+/// the macro can be configured using
+///
+/// ```
+/// #[tokio::main(flavor = "current_thread")]
+/// # async fn main() {}
+/// ```
 ///
 /// ## Function arguments:
 ///
@@ -38,7 +71,7 @@ use proc_macro::TokenStream;
 ///
 /// ## Usage
 ///
-/// ### Using default
+/// ### Using the multi-thread runtime
 ///
 /// ```rust
 /// #[tokio::main]
@@ -47,61 +80,108 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Set number of core threads
+/// Equivalent code not using `#[tokio::main]`
 ///
 /// ```rust
-/// #[tokio::main(core_threads = 1)]
-/// async fn main() {
-///     println!("Hello world");
+/// fn main() {
+///     tokio::runtime::Builder::new_multi_thread()
+///         .enable_all()
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
 /// }
 /// ```
-#[proc_macro_attribute]
-#[cfg(not(test))] // Work around for rust-lang/rust#62127
-pub fn main_threaded(args: TokenStream, item: TokenStream) -> TokenStream {
-    entry::main(args, item, true)
-}
-
-/// Marks async function to be executed by selected runtime.
 ///
-/// ## Options:
+/// ### Using current thread runtime
 ///
-/// - `basic_scheduler` - All tasks are executed on the current thread.
-/// - `threaded_scheduler` - Uses the multi-threaded scheduler. Used by default (requires `rt-threaded` feature).
-///
-/// ## Function arguments:
-///
-/// Arguments are allowed for any functions aside from `main` which is special
-///
-/// ## Usage
-///
-/// ### Using default
+/// The basic scheduler is single-threaded.
 ///
 /// ```rust
-/// #[tokio::main]
+/// #[tokio::main(flavor = "current_thread")]
 /// async fn main() {
 ///     println!("Hello world");
 /// }
 /// ```
 ///
-/// ### Select runtime
+/// Equivalent code not using `#[tokio::main]`
 ///
 /// ```rust
-/// #[tokio::main(basic_scheduler)]
+/// fn main() {
+///     tokio::runtime::Builder::new_current_thread()
+///         .enable_all()
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
+/// ### Set number of worker threads
+///
+/// ```rust
+/// #[tokio::main(worker_threads = 2)]
 /// async fn main() {
 ///     println!("Hello world");
 /// }
 /// ```
+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```rust
+/// fn main() {
+///     tokio::runtime::Builder::new_multi_thread()
+///         .worker_threads(2)
+///         .enable_all()
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
+/// ### Configure the runtime to start with time paused
+///
+/// ```rust
+/// #[tokio::main(flavor = "current_thread", start_paused = true)]
+/// async fn main() {
+///     println!("Hello world");
+/// }
+/// ```
+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```rust
+/// fn main() {
+///     tokio::runtime::Builder::new_current_thread()
+///         .enable_all()
+///         .start_paused(true)
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
+/// ### NOTE:
+///
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
 #[cfg(not(test))] // Work around for rust-lang/rust#62127
 pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
-    entry::old::main(args, item)
+    entry::main(args, item, true)
 }
 
-/// Marks async function to be executed by selected runtime.
-///
-/// ## Options:
-///
-/// - `max_threads=n` - Sets max threads to `n`.
+/// Marks async function to be executed by selected runtime. This macro helps set up a `Runtime`
+/// without requiring the user to use [Runtime](../tokio/runtime/struct.Runtime.html) or
+/// [Builder](../tokio/runtime/struct.builder.html) directly.
 ///
 /// ## Function arguments:
 ///
@@ -112,30 +192,46 @@ pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
 /// ### Using default
 ///
 /// ```rust
-/// #[tokio::main]
+/// #[tokio::main(flavor = "current_thread")]
 /// async fn main() {
 ///     println!("Hello world");
 /// }
 /// ```
+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```rust
+/// fn main() {
+///     tokio::runtime::Builder::new_current_thread()
+///         .enable_all()
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
+/// ### NOTE:
+///
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
 #[cfg(not(test))] // Work around for rust-lang/rust#62127
-pub fn main_basic(args: TokenStream, item: TokenStream) -> TokenStream {
+pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::main(args, item, false)
 }
 
 /// Marks async function to be executed by runtime, suitable to test environment
 ///
-/// ## Options:
-///
-/// - `core_threads=n` - Sets core threads to `n` (requires `rt-threaded` feature).
-/// - `max_threads=n` - Sets max threads to `n` (requires `rt-core` or `rt-threaded` feature).
-///
 /// ## Usage
 ///
-/// ### Select runtime
+/// ### Multi-thread runtime
 ///
 /// ```no_run
-/// #[tokio::test(core_threads = 1)]
+/// #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 /// async fn my_test() {
 ///     assert!(true);
 /// }
@@ -143,65 +239,83 @@ pub fn main_basic(args: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// ### Using default
 ///
+/// The default test runtime is single-threaded.
+///
 /// ```no_run
 /// #[tokio::test]
 /// async fn my_test() {
 ///     assert!(true);
 /// }
 /// ```
+///
+/// ### Configure the runtime to start with time paused
+///
+/// ```no_run
+/// #[tokio::test(start_paused = true)]
+/// async fn my_test() {
+///     assert!(true);
+/// }
+/// ```
+///
+/// ### NOTE:
+///
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
-pub fn test_threaded(args: TokenStream, item: TokenStream) -> TokenStream {
+pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::test(args, item, true)
 }
 
 /// Marks async function to be executed by runtime, suitable to test environment
 ///
-/// ## Options:
-///
-/// - `basic_scheduler` - All tasks are executed on the current thread. Used by default.
-/// - `threaded_scheduler` - Use multi-threaded scheduler (requires `rt-threaded` feature).
-///
 /// ## Usage
 ///
-/// ### Select runtime
-///
-/// ```no_run
-/// #[tokio::test(threaded_scheduler)]
-/// async fn my_test() {
-///     assert!(true);
-/// }
-/// ```
-///
-/// ### Using default
-///
 /// ```no_run
 /// #[tokio::test]
 /// async fn my_test() {
 ///     assert!(true);
 /// }
 /// ```
+///
+/// ### NOTE:
+///
+/// If you rename the Tokio crate in your dependencies this macro will not work.
+/// If you must rename the current version of Tokio because you're also using an
+/// older version of Tokio, you _must_ make the current version of Tokio
+/// available as `tokio` in the module where this macro is expanded.
 #[proc_macro_attribute]
-pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
-    entry::old::test(args, item)
+pub fn test_rt(args: TokenStream, item: TokenStream) -> TokenStream {
+    entry::test(args, item, false)
 }
 
-/// Marks async function to be executed by runtime, suitable to test environment
-///
-/// ## Options:
-///
-/// - `max_threads=n` - Sets max threads to `n`.
-///
-/// ## Usage
-///
-/// ```no_run
-/// #[tokio::test]
-/// async fn my_test() {
-///     assert!(true);
-/// }
+/// Always fails with the error message below.
+/// ```text
+/// The #[tokio::main] macro requires rt or rt-multi-thread.
 /// ```
 #[proc_macro_attribute]
-pub fn test_basic(args: TokenStream, item: TokenStream) -> TokenStream {
-    entry::test(args, item, false)
+pub fn main_fail(_args: TokenStream, _item: TokenStream) -> TokenStream {
+    syn::Error::new(
+        proc_macro2::Span::call_site(),
+        "The #[tokio::main] macro requires rt or rt-multi-thread.",
+    )
+    .to_compile_error()
+    .into()
+}
+
+/// Always fails with the error message below.
+/// ```text
+/// The #[tokio::test] macro requires rt or rt-multi-thread.
+/// ```
+#[proc_macro_attribute]
+pub fn test_fail(_args: TokenStream, _item: TokenStream) -> TokenStream {
+    syn::Error::new(
+        proc_macro2::Span::call_site(),
+        "The #[tokio::test] macro requires rt or rt-multi-thread.",
+    )
+    .to_compile_error()
+    .into()
 }
 
 /// Implementation detail of the `select!` macro. This macro is **not** intended

tokio-stream/CHANGELOG.md

@@ -0,0 +1,48 @@
+# 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])
+
+[#3378]: https://github.com/tokio-rs/tokio/pull/3378
+
+# 0.1.1 (January 4, 2021)
+
+Added
+
+ - add `Stream` wrappers ([#3343])
+
+Fixed
+
+ - move `async-stream` to `dev-dependencies` ([#3366])
+
+[#3366]: https://github.com/tokio-rs/tokio/pull/3366
+[#3343]: https://github.com/tokio-rs/tokio/pull/3343
+
+# 0.1.0 (December 23, 2020)
+
+ - Initial release

tokio-stream/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "tokio-stream"
+# When releasing to crates.io:
+# - Remove path dependencies
+# - Update doc url
+#   - Cargo.toml
+# - Update CHANGELOG.md.
+# - Create "tokio-stream-0.1.x" git tag.
+version = "0.1.4"
+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.4/tokio_stream"
+description = """
+Utilities to work with `Stream` and `tokio`.
+"""
+categories = ["asynchronous"]
+
+[features]
+default = ["time"]
+time = ["tokio/time"]
+net = ["tokio/net"]
+io-util = ["tokio/io-util"]
+fs = ["tokio/fs"]
+sync = ["tokio/sync", "tokio-util"]
+signal = ["tokio/signal"]
+
+[dependencies]
+futures-core = { version = "0.3.0" }
+pin-project-lite = "0.2.0"
+tokio = { version = "1.2.0", path = "../tokio", features = ["sync"] }
+tokio-util = { version = "0.6.3", optional = true }
+
+[dev-dependencies]
+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"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

tokio-stream/LICENSE

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

tokio-stream/src/empty.rs

@@ -1,10 +1,10 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::marker::PhantomData;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`empty`] function.
+/// Stream for the [`empty`](fn@empty) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Empty<T>(PhantomData<T>);
@@ -24,7 +24,7 @@ unsafe impl<T> Sync for Empty<T> {}
 /// Basic usage:
 ///
 /// ```
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// #[tokio::main]
 /// async fn main() {

tokio-stream/src/iter.rs

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

tokio-stream/src/lib.rs

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

tokio-stream/src/macros.rs

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

tokio-stream/src/once.rs

@@ -1,10 +1,10 @@
-use crate::stream::{self, Iter, Stream};
+use crate::{Iter, Stream};
 
 use core::option;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`once`] function.
+/// Stream for the [`once`](fn@once) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Once<T> {
@@ -20,7 +20,7 @@ impl<I> Unpin for Once<I> {}
 /// # Examples
 ///
 /// ```
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// #[tokio::main]
 /// async fn main() {
@@ -35,7 +35,7 @@ impl<I> Unpin for Once<I> {}
 /// ```
 pub fn once<T>(value: T) -> Once<T> {
     Once {
-        iter: stream::iter(Some(value).into_iter()),
+        iter: crate::iter(Some(value).into_iter()),
     }
 }
 

tokio-stream/src/pending.rs

@@ -1,10 +1,10 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::marker::PhantomData;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`pending`] function.
+/// Stream for the [`pending`](fn@pending) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Pending<T>(PhantomData<T>);
@@ -16,7 +16,7 @@ unsafe impl<T> Sync for Pending<T> {}
 /// Creates a stream that is never ready
 ///
 /// The returned stream is never ready. Attempting to call
-/// [`next()`](crate::stream::StreamExt::next) will never complete. Use
+/// [`next()`](crate::StreamExt::next) will never complete. Use
 /// [`stream::empty()`](super::empty()) to obtain a stream that is is
 /// immediately empty but returns no values.
 ///
@@ -25,7 +25,7 @@ unsafe impl<T> Sync for Pending<T> {}
 /// Basic usage:
 ///
 /// ```no_run
-/// use tokio::stream::{self, StreamExt};
+/// use tokio_stream::{self as stream, StreamExt};
 ///
 /// #[tokio::main]
 /// async fn main() {

tokio-stream/src/stream_ext.rs

@@ -1,8 +1,4 @@
-//! Stream utilities for Tokio.
-//!
-//! A `Stream` is an asynchronous sequence of values. It can be thought of as an asynchronous version of the standard library's `Iterator` trait.
-//!
-//! This module provides helpers to work with them.
+use futures_core::Stream;
 
 mod all;
 use all::AllFuture;
@@ -13,12 +9,8 @@ use any::AnyFuture;
 mod chain;
 use chain::Chain;
 
-mod collect;
-use collect::Collect;
-pub use collect::FromStream;
-
-mod empty;
-pub use empty::{empty, Empty};
+pub(crate) mod collect;
+use collect::{Collect, FromStream};
 
 mod filter;
 use filter::Filter;
@@ -32,9 +24,6 @@ use fold::FoldFuture;
 mod fuse;
 use fuse::Fuse;
 
-mod iter;
-pub use iter::{iter, Iter};
-
 mod map;
 use map::Map;
 
@@ -44,15 +33,6 @@ use merge::Merge;
 mod next;
 use next::Next;
 
-mod once;
-pub use once::{once, Once};
-
-mod pending;
-pub use pending::{pending, Pending};
-
-mod stream_map;
-pub use stream_map::StreamMap;
-
 mod skip;
 use skip::Skip;
 
@@ -71,13 +51,44 @@ use take_while::TakeWhile;
 cfg_time! {
     mod timeout;
     use timeout::Timeout;
-    use std::time::Duration;
+    use tokio::time::Duration;
+    mod throttle;
+    use throttle::{throttle, Throttle};
 }
 
-pub use futures_core::Stream;
-
-/// An extension trait for `Stream`s that provides a variety of convenient
-/// combinator functions.
+/// An extension trait for the [`Stream`] trait that provides a variety of
+/// convenient combinator functions.
+///
+/// Be aware that the `Stream` trait in Tokio is a re-export of the trait found
+/// in the [futures] crate, however both Tokio and futures provide separate
+/// `StreamExt` utility traits, and some utilities are only available on one of
+/// these traits. Click [here][futures-StreamExt] to see the other `StreamExt`
+/// trait in the futures crate.
+///
+/// If you need utilities from both `StreamExt` traits, you should prefer to
+/// import one of them, and use the other through the fully qualified call
+/// syntax. For example:
+/// ```
+/// // import one of the traits:
+/// use futures::stream::StreamExt;
+/// # #[tokio::main(flavor = "current_thread")]
+/// # async fn main() {
+///
+/// let a = tokio_stream::iter(vec![1, 3, 5]);
+/// let b = tokio_stream::iter(vec![2, 4, 6]);
+///
+/// // use the fully qualified call syntax for the other trait:
+/// let merged = tokio_stream::StreamExt::merge(a, b);
+///
+/// // use normal call notation for futures::stream::StreamExt::collect
+/// let output: Vec<_> = merged.collect().await;
+/// assert_eq!(output, vec![1, 2, 3, 4, 5, 6]);
+/// # }
+/// ```
+///
+/// [`Stream`]: crate::Stream
+/// [futures]: https://docs.rs/futures
+/// [futures-StreamExt]: https://docs.rs/futures/0.3/futures/stream/trait.StreamExt.html
 pub trait StreamExt: Stream {
     /// Consumes and returns the next value in the stream or `None` if the
     /// stream is finished.
@@ -100,7 +111,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=3);
     ///
@@ -136,7 +147,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(vec![Ok(1), Ok(2), Err("nope")]);
     ///
@@ -168,7 +179,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let stream = stream::iter(1..=3);
     /// let mut stream = stream.map(|x| x + 3);
@@ -192,29 +203,48 @@ pub trait StreamExt: Stream {
     /// Values are produced from the merged stream in the order they arrive from
     /// the two source streams. If both source streams provide values
     /// simultaneously, the merge stream alternates between them. This provides
-    /// some level of fairness.
+    /// some level of fairness. You should not chain calls to `merge`, as this
+    /// will break the fairness of the merging.
     ///
     /// The merged stream completes once **both** source streams complete. When
     /// one source stream completes before the other, the merge stream
     /// exclusively polls the remaining stream.
     ///
+    /// For merging multiple streams, consider using [`StreamMap`] instead.
+    ///
+    /// [`StreamMap`]: crate::StreamMap
+    ///
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::StreamExt;
+    /// use tokio_stream::{StreamExt, Stream};
     /// use tokio::sync::mpsc;
     /// use tokio::time;
     ///
     /// use std::time::Duration;
+    /// use std::pin::Pin;
     ///
     /// # /*
     /// #[tokio::main]
     /// # */
-    /// # #[tokio::main(basic_scheduler)]
+    /// # #[tokio::main(flavor = "current_thread")]
     /// async fn main() {
     /// # time::pause();
-    ///     let (mut tx1, rx1) = mpsc::channel(10);
-    ///     let (mut tx2, rx2) = mpsc::channel(10);
+    ///     let (tx1, mut rx1) = mpsc::channel::<usize>(10);
+    ///     let (tx2, mut rx2) = mpsc::channel::<usize>(10);
+    ///
+    ///     // Convert the channels to a `Stream`.
+    ///     let rx1 = Box::pin(async_stream::stream! {
+    ///           while let Some(item) = rx1.recv().await {
+    ///               yield item;
+    ///           }
+    ///     }) as Pin<Box<dyn Stream<Item = usize> + Send>>;
+    ///
+    ///     let rx2 = Box::pin(async_stream::stream! {
+    ///           while let Some(item) = rx2.recv().await {
+    ///               yield item;
+    ///           }
+    ///     }) as Pin<Box<dyn Stream<Item = usize> + Send>>;
     ///
     ///     let mut rx = rx1.merge(rx2);
     ///
@@ -224,18 +254,18 @@ pub trait StreamExt: Stream {
     ///         tx1.send(2).await.unwrap();
     ///
     ///         // Let the other task send values
-    ///         time::delay_for(Duration::from_millis(20)).await;
+    ///         time::sleep(Duration::from_millis(20)).await;
     ///
     ///         tx1.send(4).await.unwrap();
     ///     });
     ///
     ///     tokio::spawn(async move {
     ///         // Wait for the first task to send values
-    ///         time::delay_for(Duration::from_millis(5)).await;
+    ///         time::sleep(Duration::from_millis(5)).await;
     ///
     ///         tx2.send(3).await.unwrap();
     ///
-    ///         time::delay_for(Duration::from_millis(25)).await;
+    ///         time::sleep(Duration::from_millis(25)).await;
     ///
     ///         // Send the final value
     ///         tx2.send(5).await.unwrap();
@@ -277,7 +307,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let stream = stream::iter(1..=8);
     /// let mut evens = stream.filter(|x| x % 2 == 0);
@@ -303,7 +333,7 @@ pub trait StreamExt: Stream {
     /// As values of this stream are made available, the provided function will
     /// be run on them. If the predicate `f` resolves to
     /// [`Some(item)`](Some) then the stream will yield the value `item`, but if
-    /// it resolves to [`None`] then the next value will be produced.
+    /// it resolves to [`None`], then the value will be skipped.
     ///
     /// Note that this function consumes the stream passed into it and returns a
     /// wrapped version of it, similar to [`Iterator::filter_map`] method in the
@@ -313,7 +343,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let stream = stream::iter(1..=8);
     /// let mut evens = stream.filter_map(|x| {
@@ -345,7 +375,7 @@ pub trait StreamExt: Stream {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{Stream, StreamExt};
+    /// use tokio_stream::{Stream, StreamExt};
     ///
     /// use std::pin::Pin;
     /// use std::task::{Context, Poll};
@@ -410,7 +440,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=10).take(3);
     ///
@@ -439,7 +469,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=10).take_while(|x| *x <= 3);
     ///
@@ -465,7 +495,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let mut stream = stream::iter(1..=10).skip(7);
     ///
@@ -496,7 +526,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     /// let mut stream = stream::iter(vec![1,2,3,4,1]).skip_while(|x| *x < 3);
     ///
     /// assert_eq!(Some(3), stream.next().await);
@@ -515,6 +545,12 @@ pub trait StreamExt: Stream {
 
     /// Tests if every element of the stream matches a predicate.
     ///
+    /// Equivalent to:
+    ///
+    /// ```ignore
+    /// async fn all<F>(&mut self, f: F) -> bool;
+    /// ```
+    ///
     /// `all()` takes a closure that returns `true` or `false`. It applies
     /// this closure to each element of the stream, and if they all return
     /// `true`, then so does `all`. If any of them return `false`, it
@@ -533,7 +569,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -548,7 +584,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -570,6 +606,12 @@ pub trait StreamExt: Stream {
 
     /// Tests if any element of the stream matches a predicate.
     ///
+    /// Equivalent to:
+    ///
+    /// ```ignore
+    /// async fn any<F>(&mut self, f: F) -> bool;
+    /// ```
+    ///
     /// `any()` takes a closure that returns `true` or `false`. It applies
     /// this closure to each element of the stream, and if any of them return
     /// `true`, then so does `any()`. If they all return `false`, it
@@ -586,7 +628,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -601,7 +643,7 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// let a = [1, 2, 3];
     ///
@@ -630,7 +672,7 @@ pub trait StreamExt: Stream {
     /// # Examples
     ///
     /// ```
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// #[tokio::main]
     /// async fn main() {
@@ -659,12 +701,18 @@ pub trait StreamExt: Stream {
     /// A combinator that applies a function to every element in a stream
     /// producing a single, final value.
     ///
+    /// Equivalent to:
+    ///
+    /// ```ignore
+    /// async fn fold<B, F>(self, init: B, f: F) -> B;
+    /// ```
+    ///
     /// # Examples
     /// Basic usage:
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, *};
+    /// use tokio_stream::{self as stream, *};
     ///
     /// let s = stream::iter(vec![1u8, 2, 3]);
     /// let sum = s.fold(0, |acc, x| acc + x).await;
@@ -682,10 +730,18 @@ pub trait StreamExt: Stream {
 
     /// Drain stream pushing all emitted values into a collection.
     ///
+    /// Equivalent to:
+    ///
+    /// ```ignore
+    /// async fn collect<T>(self) -> T;
+    /// ```
+    ///
     /// `collect` streams all values, awaiting as needed. Values are pushed into
     /// a collection. A number of different target collection types are
     /// supported, including [`Vec`](std::vec::Vec),
-    /// [`String`](std::string::String), and [`Bytes`](bytes::Bytes).
+    /// [`String`](std::string::String), and [`Bytes`].
+    ///
+    /// [`Bytes`]: https://docs.rs/bytes/0.6.0/bytes/struct.Bytes.html
     ///
     /// # `Result`
     ///
@@ -697,14 +753,14 @@ pub trait StreamExt: Stream {
     /// # Notes
     ///
     /// `FromStream` is currently a sealed trait. Stabilization is pending
-    /// enhancements to the Rust langague.
+    /// enhancements to the Rust language.
     ///
     /// # Examples
     ///
     /// Basic usage:
     ///
     /// ```
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// #[tokio::main]
     /// async fn main() {
@@ -721,7 +777,7 @@ pub trait StreamExt: Stream {
     /// Collecting a stream of `Result` values
     ///
     /// ```
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     ///
     /// #[tokio::main]
     /// async fn main() {
@@ -777,11 +833,12 @@ pub trait StreamExt: Stream {
     /// ```
     /// # #[tokio::main]
     /// # async fn main() {
-    /// use tokio::stream::{self, StreamExt};
+    /// use tokio_stream::{self as stream, StreamExt};
     /// use std::time::Duration;
     /// # let int_stream = stream::iter(1..=3);
     ///
-    /// let mut int_stream = int_stream.timeout(Duration::from_secs(1));
+    /// let int_stream = int_stream.timeout(Duration::from_secs(1));
+    /// tokio::pin!(int_stream);
     ///
     /// // When no items time out, we get the 3 elements in succession:
     /// assert_eq!(int_stream.try_next().await, Ok(Some(1)));
@@ -814,6 +871,47 @@ pub trait StreamExt: Stream {
     {
         Timeout::new(self, duration)
     }
+
+    /// Slows down a stream by enforcing a delay between items.
+    ///
+    /// # Example
+    ///
+    /// Create a throttled stream.
+    /// ```rust,no_run
+    /// use std::time::Duration;
+    /// use tokio_stream::StreamExt;
+    ///
+    /// # async fn dox() {
+    /// let item_stream = futures::stream::repeat("one").throttle(Duration::from_secs(2));
+    /// tokio::pin!(item_stream);
+    ///
+    /// loop {
+    ///     // The string will be produced at most every 2 seconds
+    ///     println!("{:?}", item_stream.next().await);
+    /// }
+    /// # }
+    /// ```
+    #[cfg(all(feature = "time"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
+    fn throttle(self, duration: Duration) -> Throttle<Self>
+    where
+        Self: Sized,
+    {
+        throttle(duration, self)
+    }
 }
 
 impl<St: ?Sized> StreamExt for St where St: Stream {}
+
+/// Merge the size hints from two streams.
+fn merge_size_hints(
+    (left_low, left_high): (usize, Option<usize>),
+    (right_low, right_hign): (usize, Option<usize>),
+) -> (usize, Option<usize>) {
+    let low = left_low.saturating_add(right_low);
+    let high = match (left_high, right_hign) {
+        (Some(h1), Some(h2)) => h1.checked_add(h2),
+        _ => None,
+    };
+    (low, high)
+}

tokio-stream/src/stream_ext/all.rs

@@ -0,0 +1,55 @@
+use crate::Stream;
+
+use core::future::Future;
+use core::marker::PhantomPinned;
+use core::pin::Pin;
+use core::task::{Context, Poll};
+use pin_project_lite::pin_project;
+
+pin_project! {
+    /// Future for the [`all`](super::StreamExt::all) method.
+    #[derive(Debug)]
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
+    pub struct AllFuture<'a, St: ?Sized, F> {
+        stream: &'a mut St,
+        f: F,
+        // Make this future `!Unpin` for compatibility with async trait methods.
+        #[pin]
+        _pin: PhantomPinned,
+    }
+}
+
+impl<'a, St: ?Sized, F> AllFuture<'a, St, F> {
+    pub(super) fn new(stream: &'a mut St, f: F) -> Self {
+        Self {
+            stream,
+            f,
+            _pin: PhantomPinned,
+        }
+    }
+}
+
+impl<St, F> Future for AllFuture<'_, St, F>
+where
+    St: ?Sized + Stream + Unpin,
+    F: FnMut(St::Item) -> bool,
+{
+    type Output = bool;
+
+    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));
+
+        match next {
+            Some(v) => {
+                if !(me.f)(v) {
+                    Poll::Ready(false)
+                } else {
+                    cx.waker().wake_by_ref();
+                    Poll::Pending
+                }
+            }
+            None => Poll::Ready(true),
+        }
+    }
+}

tokio-stream/src/stream_ext/any.rs

@@ -0,0 +1,55 @@
+use crate::Stream;
+
+use core::future::Future;
+use core::marker::PhantomPinned;
+use core::pin::Pin;
+use core::task::{Context, Poll};
+use pin_project_lite::pin_project;
+
+pin_project! {
+    /// Future for the [`any`](super::StreamExt::any) method.
+    #[derive(Debug)]
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
+    pub struct AnyFuture<'a, St: ?Sized, F> {
+        stream: &'a mut St,
+        f: F,
+        // Make this future `!Unpin` for compatibility with async trait methods.
+        #[pin]
+        _pin: PhantomPinned,
+    }
+}
+
+impl<'a, St: ?Sized, F> AnyFuture<'a, St, F> {
+    pub(super) fn new(stream: &'a mut St, f: F) -> Self {
+        Self {
+            stream,
+            f,
+            _pin: PhantomPinned,
+        }
+    }
+}
+
+impl<St, F> Future for AnyFuture<'_, St, F>
+where
+    St: ?Sized + Stream + Unpin,
+    F: FnMut(St::Item) -> bool,
+{
+    type Output = bool;
+
+    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));
+
+        match next {
+            Some(v) => {
+                if (me.f)(v) {
+                    Poll::Ready(true)
+                } else {
+                    cx.waker().wake_by_ref();
+                    Poll::Pending
+                }
+            }
+            None => Poll::Ready(false),
+        }
+    }
+}

tokio-stream/src/stream_ext/chain.rs

@@ -1,4 +1,5 @@
-use crate::stream::{Fuse, Stream};
+use crate::stream_ext::Fuse;
+use crate::Stream;
 
 use core::pin::Pin;
 use core::task::{Context, Poll};
@@ -44,14 +45,6 @@ where
     }
 
     fn size_hint(&self) -> (usize, Option<usize>) {
-        let (a_lower, a_upper) = self.a.size_hint();
-        let (b_lower, b_upper) = self.b.size_hint();
-
-        let upper = match (a_upper, b_upper) {
-            (Some(a_upper), Some(b_upper)) => Some(a_upper + b_upper),
-            _ => None,
-        };
-
-        (a_lower + b_lower, upper)
+        super::merge_size_hints(self.a.size_hint(), self.b.size_hint())
     }
 }

tokio-stream/src/stream_ext/collect.rs

@@ -0,0 +1,233 @@
+use crate::Stream;
+
+use core::future::Future;
+use core::marker::PhantomPinned;
+use core::mem;
+use core::pin::Pin;
+use core::task::{Context, Poll};
+use pin_project_lite::pin_project;
+
+// Do not export this struct until `FromStream` can be unsealed.
+pin_project! {
+    /// Future returned by the [`collect`](super::StreamExt::collect) method.
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
+    #[derive(Debug)]
+    pub struct Collect<T, U>
+    where
+        T: Stream,
+        U: FromStream<T::Item>,
+    {
+        #[pin]
+        stream: T,
+        collection: U::InternalCollection,
+        // Make this future `!Unpin` for compatibility with async trait methods.
+        #[pin]
+        _pin: PhantomPinned,
+    }
+}
+
+/// Convert from a [`Stream`](crate::Stream).
+///
+/// This trait is not intended to be used directly. Instead, call
+/// [`StreamExt::collect()`](super::StreamExt::collect).
+///
+/// # Implementing
+///
+/// Currently, this trait may not be implemented by third parties. The trait is
+/// sealed in order to make changes in the future. Stabilization is pending
+/// enhancements to the Rust language.
+pub trait FromStream<T>: sealed::FromStreamPriv<T> {}
+
+impl<T, U> Collect<T, U>
+where
+    T: Stream,
+    U: FromStream<T::Item>,
+{
+    pub(super) fn new(stream: T) -> Collect<T, U> {
+        let (lower, upper) = stream.size_hint();
+        let collection = U::initialize(sealed::Internal, lower, upper);
+
+        Collect {
+            stream,
+            collection,
+            _pin: PhantomPinned,
+        }
+    }
+}
+
+impl<T, U> Future for Collect<T, U>
+where
+    T: Stream,
+    U: FromStream<T::Item>,
+{
+    type Output = U;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<U> {
+        use Poll::Ready;
+
+        loop {
+            let mut me = self.as_mut().project();
+
+            let item = match ready!(me.stream.poll_next(cx)) {
+                Some(item) => item,
+                None => {
+                    return Ready(U::finalize(sealed::Internal, &mut me.collection));
+                }
+            };
+
+            if !U::extend(sealed::Internal, &mut me.collection, item) {
+                return Ready(U::finalize(sealed::Internal, &mut me.collection));
+            }
+        }
+    }
+}
+
+// ===== FromStream implementations
+
+impl FromStream<()> for () {}
+
+impl sealed::FromStreamPriv<()> for () {
+    type InternalCollection = ();
+
+    fn initialize(_: sealed::Internal, _lower: usize, _upper: Option<usize>) {}
+
+    fn extend(_: sealed::Internal, _collection: &mut (), _item: ()) -> bool {
+        true
+    }
+
+    fn finalize(_: sealed::Internal, _collection: &mut ()) {}
+}
+
+impl<T: AsRef<str>> FromStream<T> for String {}
+
+impl<T: AsRef<str>> sealed::FromStreamPriv<T> for String {
+    type InternalCollection = String;
+
+    fn initialize(_: sealed::Internal, _lower: usize, _upper: Option<usize>) -> String {
+        String::new()
+    }
+
+    fn extend(_: sealed::Internal, collection: &mut String, item: T) -> bool {
+        collection.push_str(item.as_ref());
+        true
+    }
+
+    fn finalize(_: sealed::Internal, collection: &mut String) -> String {
+        mem::replace(collection, String::new())
+    }
+}
+
+impl<T> FromStream<T> for Vec<T> {}
+
+impl<T> sealed::FromStreamPriv<T> for Vec<T> {
+    type InternalCollection = Vec<T>;
+
+    fn initialize(_: sealed::Internal, lower: usize, _upper: Option<usize>) -> Vec<T> {
+        Vec::with_capacity(lower)
+    }
+
+    fn extend(_: sealed::Internal, collection: &mut Vec<T>, item: T) -> bool {
+        collection.push(item);
+        true
+    }
+
+    fn finalize(_: sealed::Internal, collection: &mut Vec<T>) -> Vec<T> {
+        mem::replace(collection, vec![])
+    }
+}
+
+impl<T> FromStream<T> for Box<[T]> {}
+
+impl<T> sealed::FromStreamPriv<T> for Box<[T]> {
+    type InternalCollection = Vec<T>;
+
+    fn initialize(_: sealed::Internal, lower: usize, upper: Option<usize>) -> Vec<T> {
+        <Vec<T> as sealed::FromStreamPriv<T>>::initialize(sealed::Internal, lower, upper)
+    }
+
+    fn extend(_: sealed::Internal, collection: &mut Vec<T>, item: T) -> bool {
+        <Vec<T> as sealed::FromStreamPriv<T>>::extend(sealed::Internal, collection, item)
+    }
+
+    fn finalize(_: sealed::Internal, collection: &mut Vec<T>) -> Box<[T]> {
+        <Vec<T> as sealed::FromStreamPriv<T>>::finalize(sealed::Internal, collection)
+            .into_boxed_slice()
+    }
+}
+
+impl<T, U, E> FromStream<Result<T, E>> for Result<U, E> where U: FromStream<T> {}
+
+impl<T, U, E> sealed::FromStreamPriv<Result<T, E>> for Result<U, E>
+where
+    U: FromStream<T>,
+{
+    type InternalCollection = Result<U::InternalCollection, E>;
+
+    fn initialize(
+        _: sealed::Internal,
+        lower: usize,
+        upper: Option<usize>,
+    ) -> Result<U::InternalCollection, E> {
+        Ok(U::initialize(sealed::Internal, lower, upper))
+    }
+
+    fn extend(
+        _: sealed::Internal,
+        collection: &mut Self::InternalCollection,
+        item: Result<T, E>,
+    ) -> bool {
+        assert!(collection.is_ok());
+        match item {
+            Ok(item) => {
+                let collection = collection.as_mut().ok().expect("invalid state");
+                U::extend(sealed::Internal, collection, item)
+            }
+            Err(err) => {
+                *collection = Err(err);
+                false
+            }
+        }
+    }
+
+    fn finalize(_: sealed::Internal, collection: &mut Self::InternalCollection) -> Result<U, E> {
+        if let Ok(collection) = collection.as_mut() {
+            Ok(U::finalize(sealed::Internal, collection))
+        } else {
+            let res = mem::replace(collection, Ok(U::initialize(sealed::Internal, 0, Some(0))));
+
+            if let Err(err) = res {
+                Err(err)
+            } else {
+                unreachable!();
+            }
+        }
+    }
+}
+
+pub(crate) mod sealed {
+    #[doc(hidden)]
+    pub trait FromStreamPriv<T> {
+        /// Intermediate type used during collection process
+        ///
+        /// The name of this type is internal and cannot be relied upon.
+        type InternalCollection;
+
+        /// Initialize the collection
+        fn initialize(
+            internal: Internal,
+            lower: usize,
+            upper: Option<usize>,
+        ) -> Self::InternalCollection;
+
+        /// Extend the collection with the received item
+        ///
+        /// Return `true` to continue streaming, `false` complete collection.
+        fn extend(internal: Internal, collection: &mut Self::InternalCollection, item: T) -> bool;
+
+        /// Finalize collection into target type.
+        fn finalize(internal: Internal, collection: &mut Self::InternalCollection) -> Self;
+    }
+
+    #[allow(missing_debug_implementations)]
+    pub struct Internal;
+}

tokio-stream/src/stream_ext/filter.rs

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

tokio-stream/src/stream_ext/filter_map.rs

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

tokio-stream/src/stream_ext/fold.rs

@@ -1,6 +1,7 @@
-use crate::stream::Stream;
+use crate::Stream;
 
 use core::future::Future;
+use core::marker::PhantomPinned;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 use pin_project_lite::pin_project;
@@ -8,11 +9,15 @@ use pin_project_lite::pin_project;
 pin_project! {
     /// Future returned by the [`fold`](super::StreamExt::fold) method.
     #[derive(Debug)]
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub struct FoldFuture<St, B, F> {
         #[pin]
         stream: St,
         acc: Option<B>,
         f: F,
+        // Make this future `!Unpin` for compatibility with async trait methods.
+        #[pin]
+        _pin: PhantomPinned,
     }
 }
 
@@ -22,6 +27,7 @@ impl<St, B, F> FoldFuture<St, B, F> {
             stream,
             acc: Some(init),
             f,
+            _pin: PhantomPinned,
         }
     }
 }

tokio-stream/src/stream_ext/fuse.rs

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

tokio-stream/src/stream_ext/map.rs

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

tokio-stream/src/stream_ext/merge.rs

@@ -1,4 +1,5 @@
-use crate::stream::{Fuse, Stream};
+use crate::stream_ext::Fuse;
+use crate::Stream;
 
 use core::pin::Pin;
 use core::task::{Context, Poll};
@@ -52,15 +53,7 @@ where
     }
 
     fn size_hint(&self) -> (usize, Option<usize>) {
-        let (a_lower, a_upper) = self.a.size_hint();
-        let (b_lower, b_upper) = self.b.size_hint();
-
-        let upper = match (a_upper, b_upper) {
-            (Some(a_upper), Some(b_upper)) => Some(a_upper + b_upper),
-            _ => None,
-        };
-
-        (a_lower + b_lower, upper)
+        super::merge_size_hints(self.a.size_hint(), self.b.size_hint())
     }
 }
 

tokio-stream/src/stream_ext/next.rs

@@ -0,0 +1,37 @@
+use crate::Stream;
+
+use core::future::Future;
+use core::marker::PhantomPinned;
+use core::pin::Pin;
+use core::task::{Context, Poll};
+use pin_project_lite::pin_project;
+
+pin_project! {
+    /// Future for the [`next`](super::StreamExt::next) method.
+    #[derive(Debug)]
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
+    pub struct Next<'a, St: ?Sized> {
+        stream: &'a mut St,
+        // Make this future `!Unpin` for compatibility with async trait methods.
+        #[pin]
+        _pin: PhantomPinned,
+    }
+}
+
+impl<'a, St: ?Sized> Next<'a, St> {
+    pub(super) fn new(stream: &'a mut St) -> Self {
+        Next {
+            stream,
+            _pin: PhantomPinned,
+        }
+    }
+}
+
+impl<St: ?Sized + Stream + Unpin> Future for Next<'_, St> {
+    type Output = Option<St::Item>;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let me = self.project();
+        Pin::new(me.stream).poll_next(cx)
+    }
+}

tokio-stream/src/stream_ext/skip.rs

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

tokio-stream/src/stream_ext/skip_while.rs

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

tokio-stream/src/stream_ext/take.rs

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