kevy_uring/lib.rs
1//! kevy-uring — pure-Rust `io_uring` bindings against the Linux kernel ABI.
2//!
3//! A **completion**-based I/O engine. Where epoll/kqueue tell you *when* an
4//! fd is ready (then you do a `read`/`write` syscall each), io_uring lets
5//! you **submit** the reads/writes/accepts themselves into a shared
6//! submission queue (SQ) and later reap their results from a completion
7//! queue (CQ) — batching many operations into one `io_uring_enter` syscall,
8//! the lever toward the disk-I/O ceiling. **Linux-only**: on every other
9//! target this crate is an empty module that any caller can `cfg`-gate.
10//!
11//! Hand-written against the kernel ABI — `io_uring_setup`/`io_uring_enter`/
12//! `io_uring_register` are raw syscalls (no glibc wrappers, no `liburing`
13//! C dependency); the SQ/CQ/SQE regions are `mmap`'d and driven through
14//! the documented head/tail cursors. **No `libc` crate, no third-party
15//! dependency.**
16//!
17//! Carved out of [`kevy-sys`](https://crates.io/crates/kevy-sys) so the
18//! engine can be reused independently of kevy's network internals. Part of
19//! the [kevy](https://crates.io/crates/kevy) key–value server.
20//!
21//! # Safety
22//!
23//! The shared ring cursors are accessed as `AtomicU32` over the `mmap`'d
24//! memory (the kernel is the other party): the producer publishes the SQ
25//! tail with `Release` and reads the SQ head with `Acquire`; the consumer
26//! reads the CQ tail with `Acquire` and publishes the CQ head with
27//! `Release`. `IoUring` owns its ring fd and three mappings, freed on
28//! drop.
29
30#![cfg(target_os = "linux")]
31
32mod completion;
33mod ffi;
34mod layout;
35mod pbr;
36mod prep;
37mod register;
38mod ring;
39
40#[cfg(test)]
41mod ring_tests;
42
43pub use completion::Completion;
44pub use ffi::Iovec;
45pub use layout::KernelTimespec;
46pub use pbr::ProvidedBufRing;
47pub use ring::IoUring;