Expand description
§store-io-posix
The Linux backend of store-io. PosixPlatform implements
store_io_platform::Platform over O_DIRECT file descriptors, on one of
two tiers chosen at run time (LinuxTier, D-082): io_uring through
store-io’s own binding (uring: rings restricted to reads, writes, NOP
and cancel, every read and write RWF_NOWAIT, what the kernel would block
on finished by one ordinary system call; nothing ever runs on io-wq), or
the synchronous tier (T3), where PosixQueue performs every data
operation inside submit with one system call. A queue whose operations
the caller waits for one at a time runs inline on either tier: no thread
hop, no timer, no allocation.
What this backend does:
- opens data files
O_RDWR|O_DIRECT|O_CLOEXEC(read-only:O_RDONLY|O_DIRECT|O_CLOEXEC) relative to a directory descriptor, withopenat2(RESOLVE_BENEATH|RESOLVE_NO_SYMLINKS)on kernels 5.6 and later andopenat(O_NOFOLLOW)before; symlinks are refused and so is anything that is neither a regular file nor a block device; - creates files
O_CREAT|O_EXCL, mode 0600, and directories mode 0700 followed by anfsyncof the parent; - takes the ownership lock with
fcntl(F_OFD_SETLK)on the very open file description used for I/O (flockon kernels without OFD locks), never a POSIXF_SETLK, which anyclose()of the inode would drop; - allocates with
fallocatemode 0 only (neverKEEP_SIZE); the engine fills the unwritten extents with direct writes before a region is ready; - reports extents with
FS_IOC_FIEMAPand page-cache residency withcachestat(2); - writes with
pwritev2(RWF_DSYNC)when durability at completion is requested, except on raw block devices, where the synchronousRWF_DSYNCpath issues both a FUA write and a cache flush; there a plain write is followed by onefdatasync; - runs the operations of a parallel queue (
QueueConfig::parallel) on a bounded pool of worker threads, started on first use and parked untimed while idle (D-051, D-096); every other queue stays inline; - gathers
Evidencefrom statfs, statx,/proc/self/mountinfo, the ext4 effective options, inode flags, the sysfs block tree, NVMe Identify (when the device node can be opened) and the DMI tables. Every sysfs, procfs and device byte is parsed as hostile input. The probe never decides a class and never writes a file.
Errors are raw errno values; the engine classifies them. EINTR is
retried, and the retry counted, only on opens, which provably precede any
I/O. Data system calls on O_DIRECT files are not interrupted before I/O
in practice, so their EINTR is returned as the raw outcome.
Every module is gated on target_os = "linux"; on other operating systems
the crate compiles to an empty shell so a workspace build succeeds
everywhere. Every unsafe block lives in sys.rs, posix.rs and the io_uring
binding (uring/sys.rs: its system calls and shared memory; ring.rs
and queue.rs: pushing entries and the wake read’s target), each preceded
by a SAFETY comment citing the contract it relies on; tests aside.
Structs§
- Posix
Dir - An open directory (closed on drop).
- Posix
File - An open data file.
- Posix
Lock - A held ownership lock, released on drop.
- Posix
Platform - The Linux synchronous platform.
- Posix
Queue - A per-thread synchronous queue.
- Posix
Waker - Ends a
PosixQueue’s wait from another thread (D-083). An inline queue never blocks inwait, so its waker has nothing to do. - Registration
- What an io_uring queue registered (D-078), from
PosixQueue::registered.
Enums§
- Linux
Tier - Which kernel interface the Linux backend’s queues use (D-082). Other backends have one interface and ignore it.
Functions§
- io_
uring_ fallbacks - Operations, in this process so far, that the io_uring tier finished with one blocking system call because the kernel would have blocked (or could not honour NOWAIT for the file) or transferred short. A measure of how often the asynchronous path was not taken; never a failure.