Crate turmoil_io_uring

Expand description

Simulated io_uring for turmoil.

This crate mirrors the io-uring 0.7 crate’s Rust API closely enough that consumers can flip a feature flag and swap their use io_uring::* imports for use turmoil_io_uring::*, then run the same code on macOS or Windows under a turmoil simulation.

It is not a real io_uring — there is no kernel ring, no SQ/CQ mmap, no io_uring_enter syscall. Instead, SQEs are queued in per-host Rust state, and CQEs become observable as simulated time advances past per-op completion timestamps drawn from the existing [turmoil_fs::FsConfig] latency distribution. Out-of-order completion falls out naturally because every op samples its own timestamp.

§Features

fs — enable the runtime: IoUring, Submitter, SubmissionQueue, CompletionQueue, AsyncFd. Without fs, only the data-shape types (Entry, Flags, opcode::*, types::*) compile — useful for downstream parity tests against the real io-uring crate.

All filesystem effects (read returning data, write becoming visible, fsync flushing pending ops, fault injection, page cache, torn writes on crash) flow through the same code paths as [turmoil_fs::shim::std::fs] and [turmoil_fs::shim::tokio::fs] — there is one source of truth for fs behavior under simulation.

§What is supported

[IoUring::new], [IoUring::builder], submission/completion queues (shared and exclusive variants).
Opcodes: opcode::Read, opcode::Write, opcode::Fsync, opcode::AsyncCancel.
[Submitter::submit], [Submitter::submit_and_wait], [Submitter::submit_with_args].
[AsyncFd] mirroring tokio::io::unix::AsyncFd for the ring’s readiness fd, driven by simulated time.

§What is rejected

IORING_SETUP_SQPOLL, IORING_SETUP_IOPOLL.
Linked SQEs (IOSQE_IO_LINK, IOSQE_IO_HARDLINK).
Fixed files / registered buffers / BufRing.
Multi-shot ops.
Any opcode other than the four listed above.

Submitting any of these surfaces as EINVAL — either at submit time or as a CQE result — exactly as the real kernel would.

§Stability

Normally consumed via turmoil’s unstable-io_uring feature. The API may change between patch releases.

Modules§

cqueue: Completion queue types mirroring io_uring::cqueue.
opcode: Opcode builders mirroring a small subset of io_uring::opcode.
squeue: Submission queue types mirroring io_uring::squeue.
types: Type fragments mirroring io_uring::types.