Crate rudb_io 

Files, and the interception shim the crash tests drive.

Rank 1 in the layer rule. See xtask/layers.toml and spec/18-package-layout.md.

Everything that touches a file in this project goes through Filesystem and File. Not most things, everything. spec/16-testing.md section 16.5 is explicit about why the shim is scheduled at M0 and not at M6, where the crash tests that use it live: retrofitting an interception layer into a codebase that has been calling File::write directly for two years is a much larger job than building against it from the start. So the shim goes in before there is anything to intercept, and the rule that nothing bypasses it is cheap to keep now and expensive to establish later.

What is here

RealFilesystem, which is std::fs and positional reads and writes.

SimFilesystem, which is memory, and which records every operation, can be told to fail at a chosen point, and models the thing that actually happens on a crash: writes that were not separated by an fsync can land in any combination.

Request and Completion, which are how a caller states every read it wants in one call instead of one at a time. spec/engine/05-scan.md section 5.3 has the argument and submit has the details.

Pool, which is the threads that serve those requests. They are not the execution threads, which is the whole idea: a thread blocked on a read is not a core lost to execution, because the thread that blocked was never an execution thread.

What is not here yet

Direct I/O, io_uring and object storage. spec/05-storage.md sections on I/O say the layer ends up with two backends chosen by measurement at startup, and choosing needs a buffer manager to generate the depth and a workload to measure. What matters now is that the interface they will implement exists and that nothing is written against std::fs directly in the meantime.

Why the methods take &self

Positional I/O does not need exclusive access and the buffer manager is going to want many readers at once. read_at and write_at are the whole interface for a reason: a seek plus a read is two operations with shared state between them, and shared mutable state in the I/O layer is how a database gets a bug that only appears at sixteen threads.

Re-exports

pub use glob::expand;

pub use machine::default_memory_limit;

pub use machine::physical_memory;

pub use pool::Config;

pub use pool::Pool;

pub use pool::Pooled;

pub use pool::Stats;

pub use real::RealFilesystem;

pub use sim::Completions;

pub use sim::Crash;

pub use sim::Op;

pub use sim::SimFilesystem;

pub use submit::Completion;

pub use submit::Filler;

pub use submit::Request;

pub use submit::Response;

Modules

glob

Path patterns, and the filesystem walk that turns one into a list of files.

machine

How much memory the machine has, which is where the default budget comes from.

pool

The I/O threads, which are not the execution threads.

real

The filesystem that is an actual filesystem.

sim

The interception shim.

submit

Stating every read up front, and waiting for the answers.

Enums

OpenMode

How a file is opened.

Traits

File

An open file, addressed by offset rather than by a cursor.

Filesystem

A place files live.