chore: prepare tokio v1.2.0 (#3506)

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

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

.cirrus.yml

@@ -1,17 +1,17 @@
 freebsd_instance:
-  image: freebsd-12-1-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,298 @@
+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
+        run: cargo build --features rt-net --bin test-mem
+        working-directory: tests-integration
+
+      # Run with valgrind
+      - name: Run valgrind
+        run: valgrind  --leak-check=full --show-leak-kinds=all ./target/debug/test-mem
+
+  test-unstable:
+    name: test tokio full --unstable
+    runs-on: ${{ matrix.os }}
+    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
 
@@ -132,8 +137,13 @@ RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
 ```
 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 +260,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 +331,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 +425,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

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,23 @@ edition = "2018"
 # If you copy one of the examples into a new project, you should be using
 # [dependencies] instead.
 [dev-dependencies]
-tokio = { version = "0.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" }
+
+async-stream = "0.3"
+tracing = "0.1"
+tracing-subscriber = { version = "0.2.7", default-features = false, features = ["fmt", "ansi", "env-filter", "chrono", "tracing-log"] }
+bytes = "1.0.0"
+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 +68,12 @@ path = "udp-codec.rs"
 [[example]]
 name = "tinyhttp"
 path = "tinyhttp.rs"
+
+[[example]]
+name = "custom-executor"
+path = "custom-executor.rs"
+
+
+[[example]]
+name = "custom-executor-tokio-context"
+path = "custom-executor-tokio-context.rs"

examples/README.md

@@ -19,5 +19,5 @@ 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,8 +27,8 @@
 #![warn(rust_2018_idioms)]
 
 use tokio::net::{TcpListener, TcpStream};
-use tokio::stream::{Stream, StreamExt};
 use tokio::sync::{mpsc, Mutex};
+use tokio_stream::{Stream, StreamExt};
 use tokio_util::codec::{Framed, LinesCodec, LinesCodecError};
 
 use futures::SinkExt;
@@ -43,6 +43,26 @@ 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 +77,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 +90,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);
             }
         });
     }
@@ -80,9 +101,6 @@ async fn main() -> Result<(), Box<dyn Error>> {
 /// Shorthand for the transmit half of the message channel.
 type Tx = mpsc::UnboundedSender<String>;
 
-/// Shorthand for the receive half of the message channel.
-type Rx = mpsc::UnboundedReceiver<String>;
-
 /// Data that is shared between all peers in the chat server.
 ///
 /// This is the set of `Tx` handles for all connected clients. Whenever a
@@ -106,7 +124,7 @@ struct Peer {
     ///
     /// This is used to receive messages from peers. When a message is received
     /// off of this `Rx`, it will be written to the socket.
-    rx: Rx,
+    rx: Pin<Box<dyn Stream<Item = String> + Send>>,
 }
 
 impl Shared {
@@ -138,11 +156,17 @@ impl Peer {
         let addr = lines.get_ref().peer_addr()?;
 
         // Create a channel for this peer
-        let (tx, rx) = mpsc::unbounded_channel();
+        let (tx, mut rx) = mpsc::unbounded_channel();
 
         // Add an entry for this `Peer` in the shared state map.
         state.lock().await.peers.insert(addr, tx);
 
+        let rx = Box::pin(async_stream::stream! {
+            while let Some(item) = rx.recv().await {
+                yield item;
+            }
+        });
+
         Ok(Peer { lines, rx })
     }
 }
@@ -200,7 +224,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,7 +236,7 @@ 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;
     }
 
@@ -233,9 +257,10 @@ async fn process(
                 peer.lines.send(&msg).await?;
             }
             Err(e) => {
-                println!(
+                tracing::error!(
                     "an error occurred while processing messages for {}; error = {:?}",
-                    username, e
+                    username,
+                    e
                 );
             }
         }
@@ -248,7 +273,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,32 @@ authors = ["Tokio Contributors <[email protected]>"]
 edition = "2018"
 publish = false
 
+[[bin]]
+name = "test-cat"
+
+[[bin]]
+name = "test-mem"
+required-features = ["rt-net"]
+
 [features]
+# For mem check
+rt-net = ["tokio/rt", "tokio/rt-multi-thread", "tokio/net"]
+
 full = [
     "macros",
-    "rt-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/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,3 +1,25 @@
+# 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
@@ -30,9 +52,11 @@
 
 - Initial release
 
-[#2225]: https://github.com/tokio-rs/tokio/pull/2225
-[#2177]: https://github.com/tokio-rs/tokio/pull/2177
-[#2152]: https://github.com/tokio-rs/tokio/pull/2152
-[#2038]: https://github.com/tokio-rs/tokio/pull/2038
-[#2022]: https://github.com/tokio-rs/tokio/pull/2022
 [#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

@@ -6,14 +6,14 @@ name = "tokio-macros"
 # - 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 +30,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,4 @@
-#![doc(html_root_url = "https://docs.rs/tokio-macros/0.2.5")]
+#![doc(html_root_url = "https://docs.rs/tokio-macros/1.1.0")]
 #![allow(clippy::needless_doctest_main)]
 #![warn(
     missing_debug_implementations,
@@ -6,7 +6,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 +24,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 +72,7 @@ use proc_macro::TokenStream;
 ///
 /// ## Usage
 ///
-/// ### Using default
+/// ### Using the multi-thread runtime
 ///
 /// ```rust
 /// #[tokio::main]
@@ -47,61 +81,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 +193,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 +240,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,33 @@
+# 0.1.3 (February 5, 2021)
+
+Added
+
+ - sync: add wrapper for broadcast and watch ([#3384], [#3504])
+
+[#3384]: https://github.com/tokio-rs/tokio/pull/3384
+[#3504]: https://github.com/tokio-rs/tokio/pull/3504
+
+# 0.1.2 (January 12, 2021)
+
+Fixed
+
+ - docs: fix some wrappers missing in documentation ([#3378])
+
+[#3378]: https://github.com/tokio-rs/tokio/pull/3378
+
+# 0.1.1 (January 4, 2021)
+
+Added
+
+ - add `Stream` wrappers ([#3343])
+
+Fixed
+
+ - move `async-stream` to `dev-dependencies` ([#3366])
+
+[#3366]: https://github.com/tokio-rs/tokio/pull/3366
+[#3343]: https://github.com/tokio-rs/tokio/pull/3343
+
+# 0.1.0 (December 23, 2020)
+
+ - Initial release

tokio-stream/Cargo.toml

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

tokio-stream/LICENSE

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

tokio-stream/src/macros.rs

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

tokio-stream/src/once.rs

@@ -1,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,34 @@ 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 {}

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};

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};

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;

tokio-stream/src/stream_ext/take_while.rs

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