Skip to content

fs: skip io_uring path gracefully when IO driver is disabled - #8377

Closed
philphauler wants to merge 3 commits into
tokio-rs:masterfrom
philphauler:fix-8164-uring-io-disabled
Closed

philphauler wants to merge 3 commits into
tokio-rs:masterfrom
philphauler:fix-8164-uring-io-disabled

Conversation

@philphauler

@philphauler philphauler commented Aug 21, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

When a Tokio runtime is built without enable_io() and the crate is compiled
with tokio_unstable + io-uring, filesystem operations like tokio::fs::read
panic before reaching the existing spawn_blocking fallback:

A Tokio 1.x context was found, but IO is disabled.
Call `enable_io` on the runtime builder to enable IO.

The seven tokio::fs callsites that probe the io_uring driver all call
driver().io(), which panics via .expect() on a disabled IO handle.

Fixes #8164

Related: #8165 fixes the same panic for read, write, OpenOptions::open
and File reads and was approved in May, but has been conflicted since July.
This PR also covers rename and try_exists.

Solution

Add driver::Handle::has_io() -> bool next to the panicking io() accessor
and guard each io_uring probe with it, so a runtime without an IO driver falls
through to the existing blocking path.

Changes

  • runtime/driver.rs: add has_io() (gated by cfg_io_uring!)
  • fs/read.rs, fs/write.rs, fs/rename.rs, fs/try_exists.rs,
    fs/open_options.rs, fs/file.rs (poll_read_inner and lazy_init_read):
    probe io_uring only when has_io()
  • tests/fs_io_driver.rs: io_disabled, io_enabled, io_uring_enabled
    run write / read / OpenOptions::open / File::from_std read / rename /
    try_exists on both schedulers. Not gated on the io-uring feature, so CI
    runs it with and without io_uring compiled in. io_uring_enabled also
    checks the uring path is still taken (no blocking thread spawned).

All source changes are inside the existing
#[cfg(all(tokio_unstable, feature = "io-uring", ...))] blocks; the
spawn_blocking fallback is unchanged.

Testing

  • with fix, Linux (WSL2 6.6, io_uring), --cfg tokio_unstable --features full,test-util,io-uring, all fs_* tests: pass (3/3 in fs_io_driver)
  • with fix, without the io-uring feature; without tokio_unstable; on Windows both ways; under miri (--features full): 2/2 each
  • with fix, kernel.io_uring_disabled=2 (EPERM): 3/3 pass (io_uring_available returns false, assertion skipped)
  • tests only on the merge-base ea91b33 (no fix), io-uring + tokio_unstable: io_disabled fails with the panic above at tokio/src/fs/write.rs:39:51; io_enabled / io_uring_enabled pass
  • tests only on the merge-base without io-uring: pass
  • cargo fmt --check clean; cargo clippy --all-features -Dwarnings clean

When a Tokio runtime is built without `enable_io()`, the io_uring
filesystem probe in `tokio::fs` operations panics because
`driver().io()` calls `.expect()` on a `None` IO handle.

Add `Handle::try_io()` which returns `Option<&Handle>` instead of
panicking, and update all seven fs callsites to use it. When the IO
driver is absent, the io_uring path is skipped and the existing
`spawn_blocking` fallback runs as expected.

Affected: `fs::read`, `fs::write`, `fs::rename`, `fs::try_exists`,
`fs::OpenOptions::open`, `File::poll_read_inner`, and
`File::lazy_init_read`.

Fixes tokio-rs#8164
try_io() is only called from io_uring fs paths, so it should be
gated behind cfg_io_uring! rather than cfg_io_driver! to avoid
a dead_code error when clippy runs without tokio_unstable + io-uring.

@Daksh14 Daksh14 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching this! Also some tests would be great, these are some great candidates.

  1. Test with io disabled + io_uring and tokio_unstable
  2. Test with io enabled + io_uring and tokio_unstable
  3. Test with io enabled + io_uring enabled/disabled and tokio_unstable

Comment thread tokio/src/fs/open_options.rs Outdated
Kind::Uring(opts) => {
let handle = crate::runtime::Handle::current();
let driver_handle = handle.inner.driver().io();
let use_uring = match handle.inner.driver().try_io() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rename this to has_io as try is for Result resulting functions

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in f0fa514 — renamed to has_io, returns bool.

@philphauler

Copy link
Copy Markdown
Contributor Author

@Daksh14 Onnit g 🫡

@philphauler

Copy link
Copy Markdown
Contributor Author

Hi Daksh14

The has_io rename is in f0fa514 — try_io already names a public API in this crate (AsyncFd::try_io, TcpStream::try_io, …), so has_io() -> bool guards the panicking io() accessor.

As noted in the PR body, #8165 by @fallintoplace addresses the same panic. This PR covers the same sites plus rename and try_exists, adds the accessor, and has cross-platform tests. Happy to rebase onto theirs or add Co-authored-by if they come back — whichever you prefer.

Tests are in tokio/tests/fs_io_driver.rs — all seven call sites on both schedulers across three configurations (io disabled / io enabled / io_uring enabled). The io_uring case also asserts no blocking thread was spawned, confirming the uring path is still taken. The file isn't gated on the io-uring feature so CI runs it both ways. Matrix and run counts are in the PR body.

@Daksh14 Daksh14 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the driver.io() should take care of checking if the driver has io enabled. Otherwise I think the condition becomes a bit ugly to read

@philphauler

Copy link
Copy Markdown
Contributor Author

Damn! U right there g, imma tweak 🫡⚡️

@Darksonn Darksonn added A-tokio Area: The main tokio crate M-io Module: tokio/io T-io-uring Topic: Linux io_uring labels Sep 7, 2026
Comment thread tokio/src/fs/read.rs
Comment on lines +79 to +84
let driver = handle.inner.driver();
if driver.has_io()
&& driver
.io()
.check_and_init(io_uring::opcode::Read::CODE)
.await?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are repeating logic like this in several places. Could we have a method on driver() called check_io_uring that takes an opcode, and internally performs the has_io() check followed by the check_and_init() check? That way we can just call that combined method in the places where we need to check whether there is io-uring and it has a certain opcode.

@Darksonn

Darksonn commented Sep 7, 2026

Copy link
Copy Markdown
Member

Please make your PR description less verbose.

@Daksh14

Daksh14 commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

I'd like to close this PR in favor of @fallintoplace 's PR #8165 hopefully its okay with you? They are the same change very well needed with new io_uring semantics.

Thanks a lot for your contribution anyways!

@philphauler

Copy link
Copy Markdown
Contributor Author

Absolutely, that makes sense — #8165 covers the same ground. Happy to close this in favour of @fallintoplace's PR. The io_uring path was a real gap and glad it's getting fixed either way.

If any of the test coverage from this PR (the io_disabled / io_enabled / io_uring_enabled triplet in tests/fs_io_driver.rs) would be useful in #8165, feel free to pull it across.

Thanks for the review, @Daksh14!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-tokio Area: The main tokio crate M-io Module: tokio/io T-io-uring Topic: Linux io_uring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants