fs: emit compilation error without 'tokio_unstable' for 'io-uring'

Signed-off-by: ADD-SP <qiqi.zhang@konghq.com>

Author: ADD-SP

.cirrus.yml

@@ -6,6 +6,8 @@ env:
   RUST_STABLE: stable
   RUST_NIGHTLY: nightly-2025-01-25
   RUSTFLAGS: -D warnings
+  # This excludes unstable features like io_uring, which require '--cfg tokio_unstable'.
+  TOKIO_STABLE_FEATURES: full,test-util
 
 # 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
@@ -23,7 +25,13 @@ task:
       rustc --version
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --all --all-features
+    - cargo test --all --features $TOKIO_STABLE_FEATURES
+    # Free the disk space before the next build,
+    # otherwise cirrus-ci complains about "No space left on device".
+    - cargo clean
+    # Enable all unstable features, including io_uring, because it supports
+    # x86_64 FreeBSD.
+    - RUSTFLAGS="$RUSTFLAGS --cfg tokio_unstable" RUSTDOCFLAGS="$RUSTDOCFLAGS --cfg tokio_unstable" cargo test --all --all-features
 
 task:
   name: FreeBSD docs
@@ -55,4 +63,4 @@ task:
       rustc --version
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --all --all-features --target i686-unknown-freebsd
+    - cargo test --all --features $TOKIO_STABLE_FEATURES --target i686-unknown-freebsd

.github/workflows/ci.yml

@@ -29,6 +29,9 @@ env:
   # - tokio-test/Cargo.toml
   # - tokio-stream/Cargo.toml
   rust_min: '1.70'
+  # This excludes unstable features like io_uring,
+  # which require '--cfg tokio_unstable'.
+  TOKIO_STABLE_FEATURES: "full,test-util"
 
 defaults:
   run:
@@ -73,15 +76,13 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
 
-      # Run `tokio` with `full` features. This excludes testing utilities which
+      # Run `tokio` with stable features. This excludes testing utilities which
       # can alter the runtime behavior of Tokio.
       - name: test tokio full
         run: |
           set -euxo pipefail
-          # We use `--features "full,test-util"` instead of `--all-features` since
-          # `--all-features` includes `io_uring`, which is not available on all targets.
-          cargo nextest run --features full,test-util
-          cargo test --doc --features full,test-util
+          cargo nextest run --features full
+          cargo test --doc --features full
         working-directory: tokio
 
   test-workspace-all-features:
@@ -107,12 +108,11 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
 
-      # Test **all** crates in the workspace with all features.
-      - name: test all --all-features
+      - name: test --features ${{ env.TOKIO_STABLE_FEATURES }}
         run: |
           set -euxo pipefail
-          cargo nextest run --workspace --all-features
-          cargo test --doc --workspace --all-features
+          cargo nextest run --workspace --features $TOKIO_STABLE_FEATURES
+          cargo test --doc --workspace --features $TOKIO_STABLE_FEATURES
 
   test-workspace-all-features-panic-abort:
     needs: basics
@@ -137,10 +137,15 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
 
-      - name: test all --all-features panic=abort
+      - name: test --features ${{ env.TOKIO_STABLE_FEATURES }} panic=abort
         run: |
           set -euxo pipefail
-          RUSTFLAGS="$RUSTFLAGS -C panic=abort -Zpanic-abort-tests" cargo nextest run --workspace --exclude tokio-macros --exclude tests-build --all-features --tests
+          RUSTFLAGS="$RUSTFLAGS -C panic=abort -Zpanic-abort-tests" cargo nextest run \
+            --workspace \
+            --exclude tokio-macros \
+            --exclude tests-build \
+            --features $TOKIO_STABLE_FEATURES \
+            --tests
 
   test-integration-tests-per-feature:
     needs: basics
@@ -204,8 +209,9 @@ jobs:
         run: sed -i '/\[features\]/a plsend = ["parking_lot/send_guard"]' tokio/Cargo.toml
 
       - uses: Swatinem/rust-cache@v2
-      - name: Check tests with all features enabled
-        run: cargo check --workspace --all-features --tests
+
+      - name: Check tests --unstable --features ${{ env.TOKIO_STABLE_FEATURES }}
+        run: cargo check --workspace --tests --features $TOKIO_STABLE_FEATURES
 
   valgrind:
     name: valgrind
@@ -247,12 +253,11 @@ jobs:
     strategy:
       matrix:
         include:
-          # We use `--features "full,test-util"` instead of `--all-features` since
-          # `--all-features` includes `io_uring`, which is not available on all targets.
-          - { os: windows-latest, features: "full,test-util" }
-          - { os: ubuntu-latest, features: "full,test-util" }
-          - { os: ubuntu-latest, features: "full,test-util,io-uring" }
-          - { os: macos-latest, features: "full,test-util" }
+          - { os: windows-latest, extra_features: "" }
+          - { os: ubuntu-latest, extra_features: "" }
+          # only Linux supports io_uring
+          - { os: ubuntu-latest, extra_features: io-uring }
+          - { os: macos-latest, extra_features: "" }
     steps:
       - uses: actions/checkout@v5
       - name: Install Rust ${{ env.rust_stable }}
@@ -270,8 +275,8 @@ jobs:
       - name: test tokio full --cfg unstable
         run: |
           set -euxo pipefail
-          cargo nextest run --features ${{ matrix.features }}
-          cargo test --doc --features ${{ matrix.features }}
+          cargo nextest run --features $TOKIO_STABLE_FEATURES,${{ matrix.extra_features }}
+          cargo test --doc --features $TOKIO_STABLE_FEATURES,${{ matrix.extra_features }}
         working-directory: tokio
         env:
           RUSTFLAGS: --cfg tokio_unstable -Dwarnings
@@ -304,8 +309,11 @@ jobs:
       - name: test tokio full --cfg unstable --cfg taskdump
         run: |
           set -euxo pipefail
-          cargo nextest run --all-features
-          cargo test --doc --all-features
+          # taskdump is an unstable feature, but it can only be enabled
+          # by --cfg tokio_taskdump, not by a feature flag, so we can
+          # use $TOKIO_STABLE_FEATURES here.
+          cargo nextest run --features $TOKIO_STABLE_FEATURES
+          cargo test --doc --features $TOKIO_STABLE_FEATURES
         working-directory: tokio
         env:
           RUSTFLAGS: --cfg tokio_unstable --cfg tokio_taskdump -Dwarnings
@@ -336,8 +344,11 @@ jobs:
       - name: check tokio full --cfg unstable --cfg internal-mt-counters
         run: |
           set -euxo pipefail
-          cargo nextest run --all-features
-          cargo test --doc --all-features
+          # taskdump is an unstable feature, but it can only be enabled
+          # by --cfg tokio_taskdump, not by a feature flag, so we can
+          # use $TOKIO_STABLE_FEATURES here.
+          cargo nextest run --features $TOKIO_STABLE_FEATURES
+          cargo test --doc --features $TOKIO_STABLE_FEATURES
         working-directory: tokio
         env:
           RUSTFLAGS: --cfg tokio_unstable --cfg tokio_internal_mt_counters -Dwarnings
@@ -405,7 +416,7 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - name: miri-doc-test
         run: |
-          cargo miri test --doc --all-features --no-fail-fast
+          cargo miri test --doc --features $TOKIO_STABLE_FEATURES --no-fail-fast
         working-directory: tokio
         env:
           MIRIFLAGS: -Zmiri-disable-isolation -Zmiri-strict-provenance -Zmiri-retag-fields
@@ -426,7 +437,7 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
       - name: asan
-        run: cargo test --workspace --all-features --target x86_64-unknown-linux-gnu --tests -- --test-threads 1 --nocapture
+        run: cargo test --workspace --features $TOKIO_STABLE_FEATURES --target x86_64-unknown-linux-gnu --tests -- --test-threads 1 --nocapture
         env:
           RUSTFLAGS: -Z sanitizer=address --cfg tokio_no_tuning_tests
           # Ignore `trybuild` errors as they are irrelevant and flaky on nightly
@@ -444,6 +455,9 @@ jobs:
           rust-toolchain: ${{ env.rust_stable }}
           package: tokio
           release-type: minor
+          feature-group: only-explicit-features
+          # We don't care about the semver of unstable tokio features.
+          features: ${{ env.TOKIO_STABLE_FEATURES }}
       - name: Check semver for rest of the workspace
         if: ${{ !startsWith(github.event.pull_request.base.ref, 'tokio-1.') }}
         uses: obi1kenobi/cargo-semver-checks-action@v2
@@ -669,9 +683,9 @@ jobs:
     strategy:
       matrix:
         include:
-          - { name: "", rustflags: "" }
-          - { name: "--unstable", rustflags: "--cfg tokio_unstable -Dwarnings" }
-          - { name: "--unstable --taskdump", rustflags: "--cfg tokio_unstable -Dwarnings --cfg tokio_taskdump" }
+          - { name: "", rustflags: "", exclude_features: "io-uring" }
+          - { name: "--unstable", rustflags: "--cfg tokio_unstable -Dwarnings", exclude_features: "" }
+          - { name: "--unstable --taskdump", rustflags: "--cfg tokio_unstable -Dwarnings --cfg tokio_taskdump", exclude_features: "" }
     steps:
       - uses: actions/checkout@v5
       - name: Install Rust ${{ env.rust_nightly }}
@@ -684,7 +698,7 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
       - name: check --feature-powerset ${{ matrix.name }}
-        run: cargo hack check --all --feature-powerset --depth 2 --keep-going
+        run: cargo hack check --all --feature-powerset --exclude-features "${{ matrix.exclude_features }}" --depth 2 --keep-going
         env:
           RUSTFLAGS: ${{ matrix.rustflags }}
 
@@ -698,17 +712,19 @@ jobs:
         with:
           toolchain: ${{ env.rust_min }}
       - uses: Swatinem/rust-cache@v2
-      - name: "check --workspace --all-features"
+      - name: "cargo check"
         run: |
           if [[ "${{ github.event.pull_request.base.ref }}" =~ ^tokio-1\..* ]]; then
             # Only check `tokio` crate as the PR is backporting to an earlier tokio release.
-            cargo check -p tokio --all-features
+
+            cargo check -p tokio --features $TOKIO_STABLE_FEATURES
           else
             # Check all crates in the workspace
-            cargo check --workspace --all-features
+
+            cargo check -p tokio --features $TOKIO_STABLE_FEATURES
+            # Other crates doesn't have unstable features, so we can use --all-features.
+            cargo check -p tokio-macros -p tokio-stream -p tokio-util -p tokio-test --all-features
           fi
-        env:
-          RUSTFLAGS: "" # remove -Dwarnings
 
   minimal-versions:
     name: minimal-versions
@@ -724,14 +740,17 @@ jobs:
         uses: taiki-e/install-action@cargo-hack
 
       - uses: Swatinem/rust-cache@v2
-      - name: "check --all-features -Z minimal-versions"
+      - name: "check -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 hack check --all-features --ignore-private
+          # We use `--features "full,test-util"` instead of `--all-features` since
+          # `--all-features` includes `io_uring`, which requires '--cfg tokio_unstable'.
+          cargo hack check -p tokio --features full,test-util --ignore-private
+          cargo hack check -p tokio-macros -p tokio-stream -p tokio-util -p tokio-test --all-features --ignore-private
       - name: "check --all-features --unstable -Z minimal-versions"
         env:
           RUSTFLAGS: --cfg tokio_unstable --cfg tokio_taskdump -Dwarnings
@@ -766,11 +785,6 @@ jobs:
   clippy:
     name: clippy
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        rustflags:
-          - ""
-          - "--cfg tokio_unstable --cfg tokio_taskdump -Dwarnings"
     steps:
       - uses: actions/checkout@v5
       - name: Install Rust ${{ env.rust_clippy }}
@@ -780,10 +794,12 @@ jobs:
           components: clippy
       - uses: Swatinem/rust-cache@v2
       # Run clippy
-      - name: "clippy --all ${{ matrix.rustflags }}"
-        run: cargo clippy --all --tests --all-features --no-deps
+      - name: "clippy --all --features ${{ env.TOKIO_STABLE_FEATURES }}"
+        run: cargo clippy --all --tests --no-deps --features $TOKIO_STABLE_FEATURES
+      - name: "clippy --all --all-features --unstable"
+        run: cargo clippy --all --tests --no-deps --all-features
         env:
-          RUSTFLAGS: ${{ matrix.rustflags }}
+          RUSTFLAGS: --cfg tokio_unstable --cfg tokio_taskdump -Dwarnings
 
   docs:
     name: docs
@@ -970,7 +986,7 @@ jobs:
           toolchain: ${{ env.rust_nightly }}
           target: x86_64-unknown-redox
       - name: check tokio on redox
-        run: cargo check --target x86_64-unknown-redox --all-features
+        run: cargo check --target x86_64-unknown-redox --features $TOKIO_STABLE_FEATURES
         working-directory: tokio
 
   wasm32-unknown-unknown:
@@ -1087,7 +1103,7 @@ jobs:
         with:
           tool: cargo-check-external-types@0.1.13
       - name: check-external-types
-        run: cargo check-external-types --all-features
+        run: cargo check-external-types --features $TOKIO_STABLE_FEATURES
         working-directory: tokio
 
   check-fuzzing:

tokio-macros/src/lib.rs

@@ -282,7 +282,7 @@ use proc_macro::TokenStream;
 /// fn main() {
 ///     tokio::runtime::Builder::new_current_thread()
 ///         .enable_all()
-///         .unhandled_panic(UnhandledPanic::ShutdownRuntime)
+///         .unhandled_panic(tokio::runtime::UnhandledPanic::ShutdownRuntime)
 ///         .build()
 ///         .unwrap()
 ///         .block_on(async {
@@ -539,7 +539,7 @@ pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
 ///         panic!("This panic will shutdown the runtime.");
 ///     }).await;
 /// }
-/// # #[cfg(not(tokio_unstable))]
+///
 /// # fn main() { }
 /// ```
 ///
@@ -560,7 +560,7 @@ pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
 ///             }).await;
 ///         })
 /// }
-/// # #[cfg(not(tokio_unstable))]
+///
 /// # fn main() { }
 /// ```
 ///

tokio/src/lib.rs

@@ -474,6 +474,9 @@ compile_error! {
 ))]
 compile_error!("Only features sync,macros,io-util,rt,time are supported on wasm.");
 
+#[cfg(all(not(tokio_unstable), feature = "io-uring"))]
+compile_error!("The `io-uring` feature requires `--cfg tokio_unstable`.");
+
 #[cfg(all(not(tokio_unstable), tokio_taskdump))]
 compile_error!("The `tokio_taskdump` feature requires `--cfg tokio_unstable`.");