fs: add io_uring open operation

[mox692]

Overview

This PR implement io_uring version open system call.

Since common file operations, like fs::read and fs::write, use open under the hood, I think suppporting open sysacall first is a good starting point.

Also, since this is the first operation we actually ship, I've added:

• Some uring fs tests
• Runtime flag for enabling uring (enable_uring)

Implementation

• When constructing OpenOptions, the implementation is chosen based on the presence of cfg flags.
• The only difference is that its open() method, which uses io_uring or thread_pool.
• Even when calling open() on UringOpenOptions, if the machine does not support io_uring, it will fall back to using the standard OpenOptions.

Much of the code in this PR is ported from the tokio-uring crate.

Why do we need our own UringOpenOptions?

The standard library’s OpenOptions does not expose accessors for its internal flags. However, when using io_uring to perform the open system call, it's necessary to access these internal flags. Since this is not possible with the standard implementation, we define our own UringOpenOptions type.

This limitation is tracked in the std (rust-lang/rust#76801), but it has not yet been resolved.

[mox692]

I ran a benchmark in commit d0dc6b2.

settings

$ uname -a
Linux mox692-ThinkPad-P51 6.8.0-59-generic 61-Ubuntu SMP PREEMPT_DYNAMIC Fri Apr 11 23:16:11 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

# On commit `d0dc6b2`,

# uring bench
$ RUSTFLAGS="--cfg tokio_unstable_uring" cargo bench open_many_files

# thread pool bench
$ cargo bench open_many_files

Single-threaded runtime

Benchmark Name	Thread Pool	Uring
open_many_files	[5.0981 µs 5.1226 µs 5.1520 µs]	[4.1279 µs 4.1374 µs 4.1479 µs]

Multi-threaded runtime

Benchmark Name	Thread Pool	Uring
open_many_files/2 threads	[3.5071 µs 3.5448 µs 3.5911 µs]	[4.0503 µs 4.1464 µs 4.2529 µs]
open_many_files/4 threads	[3.2188 µs 3.2382 µs 3.2582 µs]	[5.0549 µs 5.1624 µs 5.2627 µs]
open_many_files/8 threads	[3.2208 µs 3.2434 µs 3.2663 µs]	[6.6902 µs 6.7288 µs 6.7705 µs]
open_many_files/16 threads	[3.4278 µs 3.4474 µs 3.4675 µs]	[7.4527 µs 7.5142 µs 7.5674 µs]
open_many_files/32 threads	[3.9230 µs 3.9604 µs 3.9977 µs]	[6.8199 µs 6.8953 µs 6.9600 µs]

While performance improves in a current thread runtime, the results actually regress as the number of threads increases. Currently there is only one global ring in the runtime, so increasing threads may be causing lock contention.

I'll look into whether I can reduce the lock contention.

[Darksonn]

The main feedback I have here is that although it's ok to use #[cfg()] temporarily, eventually we will want --cfg tokio_uring to result in a binary that supports both io_uring and spawn_blocking. I.e. it should fall back to spawn_blocking if the Linux kernel it runs on does not support io_uring.

[mox692]

Update: Sync with master and now the base branch is 7357.

[mox692]

This is ready for review.

[Darksonn]

Overall looks reasonable to me. Have we verified whether CI runs a recent enough Linux to actually run the io_uring code?

[ADD-SP]

https://github.com/tokio-rs/tokio/actions/runs/15971607056/job/45043945544?pr=7321

SLOW [>21480.000s] tokio::fs_uring shutdown_runtime_while_performing_io_uring_ops

This job ran for six hours and was canceled due to timeout. Were we just unlucky? Or was something else slows down the test?

[mox692]

This doesn't seem like a random occurrence, I'll take a look into it.

[mox692]

To fix #7321 (review), I opened another PR #7436 since it's somewhat unrelated to open support itself.

[ADD-SP]

I'd like to go over the uring implementation (#7320) again before reviewing this PR, this is because I took too much time to understand the fix in #7436.

After that, I think I can review this PR with deeper understanding.

[Darksonn]

Overall looks reasonable to me.

[Darksonn]

Why the dead code annotation?

[mox692]

I removed some #[allow(dead_code)] annotations, but it seems that some of them still require the annotation. So I also added comments to explain that.

1405ee8

[Darksonn]

Could we use yield_now() here? Sleeping is best avoided in tests if possible.

[mox692]

Using yield_now should work, but now I'm seeing a test failure after this change (6dd50a3) ... Let me figure out what's going on

[mox692]

It turns out there was a flaw in the drop implementation of UringContext, so I pushed a commit (76d1537) to fix that.

Previous implementation used a wrong key when we remove the slab entry:

// commit: 1405ee87b11c6bbb558d2f411002fd587524cd88
fn drop(&mut self) {

    ...

    let mut cancel_ops = Slab::new();
    let mut keys_to_move = Vec::new();

    ... 

    for key in keys_to_move {
        let lifecycle = self.remove_op(key);
        // Here, cancel_ops generates a separate index from `self.ops`. 
        cancel_ops.insert(lifecycle);
    }

    while !cancel_ops.is_empty() {
        ...

        for cqe in self.ring_mut().completion() {
            let idx = cqe.user_data() as usize;
            
            // Bug: We should not use `idx` gained from `cqe.user_data()` here,
            // as it will not correspond to the index in `cancel_ops`
            cancel_ops.remove(idx);
        }
    }
}

[mox692]

I'll be back soon and address the comments.

[ADD-SP]

I'm reading this branch locally, would you mind fixing the clippy reports?

RUSTFLAGS="--cfg tokio_uring" cargo +1.88 clippy --all --tests --all-features

[Darksonn]

Does the clippy job need to be modified?

[ADD-SP]

Does the clippy job need to be modified?

I think we need to improve the clippy job to cover different combination of feature flags of cfgs, cargo-hack may help a lot.

Currently, it covers only one combination.

tokio/.github/workflows/ci.yml

Line 845 in 9f42305

run: cargo clippy --all --tests --all-features --no-deps

[Darksonn]

I probably would only consider two combinations for clippy:

• Full without any cfg flags.
• Full with all cfg flags.

It's not critical that every combination is clippy-free.

[mox692]

Clippy stuff is resolved, and I slightly fixed the test.

[mox692]

In the da0175b, I removed an assertion assert!(res.is_pending(), "Expected the open to be pending"); since it could be ready at first poll if it's using fallback logic. (For example, old kernel ci check could fail here)

[ADD-SP]

Looks good to me.