Module io 

All operating-system contact lives here. Everything above this module is arithmetic over byte arrays and is platform-neutral by construction.

SACRIFICE (Law 4): unbuffered I/O requires offset, length and buffer address to be page-aligned, and forgoes kernel readahead. Bought: the kernel does not keep a second copy of every page, so the cgroup charges only memory we chose.

Structs

AlignedRegion

A page-aligned heap region. The buffer pool owns exactly one of these, which satisfies the alignment requirement of unbuffered I/O and the “allocate once, never free” requirement that keeps allocator retention out of the picture.

IoStats

One file’s I/O, counted. Per FILE: a global cursor interleaves the data file and the WAL, counting every alternation as a seek and summing both files’ bytes as one – both measured wrong before this existed.

Locked

A file whose OS lock is RELEASED BY AN EXPLICIT UNLOCK when this is dropped, not by closing the descriptor.

Enums

Barrier

Which durability barrier a caller wants. Named rather than boolean, because true does not say what was promised.

IoMode

Traits

FileIo

Functions

lock_exclusive

Blocking exclusive lock: waits only for admissions in flight.

lock_shared

Blocking shared lock: waits only for an exclusive holder’s critical section (the page-WAL writer’s tail truncation or checkpoint).

open_file

Open path, asking for want. Returns the mode ACTUALLY obtained.

open_file_readonly

2f: open for a SNAPSHOT READER – read-only at the OS level, so the reader cannot write even by bug, and always Buffered (a reader shares the file with a live writer; O_DIRECT’s alignment contract buys nothing on a cache the writer is also warming).

open_file_writer

Open the database data file for its sole writer and retain an advisory whole-file lock for exactly as long as the returned FileIo owns the fd. Readers deliberately use open_file_readonly and never contend here.

open_recovery_source

Recovery reads through an OS read-only descriptor while excluding writers. No create semantics: a missing source must stay missing.

sync_directory

Make a newly created directory’s entry durable using the same portability contract as FileIo::sync_dir (Windows relies on the metadata journal).

try_lock_exclusive

Advisory whole-file lock, non-blocking (2n reader table). Ok(true) = acquired; Ok(false) = held by a live process. The lock dies with the fd – crash-safe by construction. Platform code lives HERE (the 2d rule).

try_lock_shared

Shared counterpart of try_lock_exclusive: Ok(false) when an exclusive holder is alive. Read-only handles suffice on every supported platform. Used by the page-WAL reader admission (ownership probe, admission gate).