Skip to main content

Crate store_io_posix

Crate store_io_posix 

Source
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, with openat2(RESOLVE_BENEATH|RESOLVE_NO_SYMLINKS) on kernels 5.6 and later and openat(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 an fsync of the parent;
  • takes the ownership lock with fcntl(F_OFD_SETLK) on the very open file description used for I/O (flock on kernels without OFD locks), never a POSIX F_SETLK, which any close() of the inode would drop;
  • allocates with fallocate mode 0 only (never KEEP_SIZE); the engine fills the unwritten extents with direct writes before a region is ready;
  • reports extents with FS_IOC_FIEMAP and page-cache residency with cachestat(2);
  • writes with pwritev2(RWF_DSYNC) when durability at completion is requested, except on raw block devices, where the synchronous RWF_DSYNC path issues both a FUA write and a cache flush; there a plain write is followed by one fdatasync;
  • 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 Evidence from 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§

PosixDir
An open directory (closed on drop).
PosixFile
An open data file.
PosixLock
A held ownership lock, released on drop.
PosixPlatform
The Linux synchronous platform.
PosixQueue
A per-thread synchronous queue.
PosixWaker
Ends a PosixQueue’s wait from another thread (D-083). An inline queue never blocks in wait, so its waker has nothing to do.
Registration
What an io_uring queue registered (D-078), from PosixQueue::registered.

Enums§

LinuxTier
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.