Skip to main content

Crate store_io

Crate store_io 

Source
Expand description

§store-io

Durable storage I/O for Rust databases.

store-io is the layer between a storage engine and the files and devices it writes to. It moves caller bytes to media and proves when they are durable. It does not frame, parse or validate the bytes it moves, and it never decides what a caller keeps after a crash.

The design rests on four rules:

  • Durability is decided per device, with evidence. Each store is probed at open and classed as power-safe, flush-required, unverified or unsafe from what the device and operating system report. Operating-system cache toggles and vendor tables never promote a device.
  • A durable write produces an unforgeable receipt. Positions, write tickets and receipts are distinct opaque types, so a sequence number can never be passed where a byte position is expected, and a barrier can never be a silent no-op.
  • Failure is fail-stop. The first failed write or flush poisons the device’s barrier domain. A flush is never retried and success is never reported after a failed one.
  • Nothing hides latency. There are no timers, no group-commit windows and no background threads that wake an idle process.

§Quick start

use store_io::{Store, StoreOptions};

// First run: create. Every later run: `Store::open`.
let store = Store::create("data/orders", StoreOptions::default())?;

// Regions are provisioned once; looking one up never creates it.
let wal = store.provision_append_region("wal", 256 << 20)?;

// Append any number of bytes; durable when this returns.
let (pos, receipt) = wal.append_durable(b"order 1001: 3 widgets")?;
println!("durable through {} ({})", receipt.durable_through(), receipt.class());

// Many records, one write and one flush.
let mut batch = wal.batch();
batch.append(b"order 1002")?;
batch.append(b"order 1003")?;
let (start, receipt) = batch.commit()?;

// Small objects: old or new after any crash.
let manifest = store.provision_slot("manifest")?;
let _receipt = manifest.commit(b"wal@0")?;

docs/GUIDE.md in the repository walks through every part: append and page regions, batches, many writers, small objects, recovery with AppendRegion::scan and resume_at, the device report, errors and space.

§Container format

Stores are created in container format 2. A store made before 0.5 (format 1) opens read-only (Store::open_readonly); a writable open refuses it with Unsupported(FormatVersion) before writing anything. copy_store (or store-io copy <old> <new>) copies it into a new format-2 store, all or nothing, the source untouched.

§Layers

  • Simple: Store, AppendRegion, PageRegion, Slot and Directory; every call blocks until its I/O is done and copies the caller’s bytes once into aligned buffers.
  • Batch: AppendBatch and PageBatch: many writes, one barrier, with in-place encoding and no copy.
  • Submitter: Submitter (submit): many reads and writes in flight from one thread without blocking, from pooled buffers with no copy; tickets come with the completions.
  • Engine: the generic engine crate under all of it, which also runs on the deterministic simulator.

§Platforms

Windows (unbuffered overlapped I/O on IOCP), Linux (direct I/O, io_uring or pwritev2) and macOS (pwrite and F_FULLFSYNC, uncached where the kernel can) have native backends (NativePlatform). On other targets the types compile but there is no native backend.

Re-exports§

pub use store_io_engine as engine;

Modules§

observe
The observer’s types: Store::observe() returns an observe::Snapshot. The observer: per-stage latency histograms and event counters (D-094).
submit
The Submitter’s types: its configuration, buffers, completions and refusals, and the waker that ends its wait from another thread.

Structs§

ByteRange
Byte range [start, end) within a region or file.
CertId
Opaque identity of a certificate (exact model, firmware, capacity and LBA format, backed by a power-cut rig log) or of an operator attestation.
ClassDecision
The outcome of decide.
CopyOptions
How copy_store builds its target.
CopyReport
What copy_store copied.
DirectoryLinux or macOS or Windows
A directory of small files, each replaced atomically and durably (see store_io_engine::Directory).
DomainStats
Counters a domain exposes for observability.
DurableReceipt
Unforgeable proof that bytes are durable.
ErrorContext
Where an error happened. The volume is the store the call was made on.
Evidence
Everything a backend could learn about one path.
FirstCause
What the domain was poisoned by.
Generation
A generation: how many times an object or region has been rewritten, recycled or re-owned. Starts at 1; 0 is never written.
IoPath
The kernel interface a platform’s queues use, and why (reported in StoreReport).
OsError
Raw operating-system error code, kept exactly as the OS reported it.
Outstanding
The oldest operation in flight on the store’s queues.
Probe
What probe found out about a directory’s device.
RegionId
Identity of a region within a volume. Never reused within a volume. 64-bit: container format 2 ids are page << 32 | seq; format 1’s fit in the low 32 bits.
RegionOptions
A region’s size, and the most it may ever grow to.
RegionPos
A byte position inside one generation of one region.
ScanSummary
How a scan ended.
SpaceReport
Where a store’s space goes.
StoreLinux or macOS or Windows
A store: one container file in a directory of its own, on one device.
StoreOptions
Explicit, reported choices for a store. Every durability-affecting field appears in Store::report.
StoreReport
What the store learned about its device, and what it decided.
TagSpace
Usage of one tag.
Trust
Caller-supplied trust inputs. Every field is an explicit, reported choice.
UnavailableRegion
A region the region table names that could not be opened (D-090).
VolumeId
128-bit identity of a volume (one container or raw namespace).
WriteTicket
Proof that a write was submitted and completed. Barrier it to make it durable. Not Clone: one ticket per write.

Enums§

Capability
A capability the platform, filesystem or device does not offer.
CorruptionKind
Corruption store-io detected in its own metadata or on media.
DurabilityClass
What a completed durable operation means on this device.
DurableOpen
Whether a durable open may proceed.
Error
Every error store-io returns.
IoInterface
A kernel interface for I/O (IoPath).
LinuxTier
Which kernel interface the Linux backend’s queues use (D-082). Other backends have one interface and ignore it.
Missing
Evidence the probe could not obtain.
Named
What a lookup did not find, or found already existing.
NotWrittenCause
Why an operation was rejected before reaching the device.
Op
The operation that failed.
OsErrorSource
Numbering space of an OsError code.
Reason
Why a device was classed below power-safe, or refused.
ReceiptLabel
Why the holder of a receipt may trust it.
RegionKind
What a region is for.
Repair
What one repair of a store did (v0.5 E6), as Store::repairs returns it: for the caller’s own log (the library prints nothing).
ReserveTag
What ran out: a space-accounting tag (tenant, class), store-io’s own table, or a region’s own limit.
ScanItem
One step of a scan, in region order.
Unavailable
Why a region the region table names could not be opened (D-090).

Constants§

CONTAINER
The container file name inside the store directory.
COPYING
The temporary name a copy’s target is built under (no live store ever has it: one left by a crashed copy is removed by the next).
COPY_LOCK
The file in a copy’s target directory whose lock a copy holds from before it looks for a store there until after its rename (created by the first copy and kept: removing a lock file races its next user).

Functions§

copy_storeLinux or macOS or Windows
Copies the store in from into a new store (container format 2) in to, whose directory must hold no store: the way a format-1 store moves to format 2, and the way to compact a format-2 one. The source is opened read-only and never written; the copy is built under a temporary name and renamed into place only when whole and durable, so after a crash to holds nothing or the whole copy (run the copy again).
io_uring_fallbacksLinux
Operations, process-wide, that the io_uring tier finished with a blocking system call because the kernel would have blocked or cut them short (never a failure; how often the asynchronous path was not taken). 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.
probeLinux or macOS or Windows
Probes the device under the existing directory dir: the evidence store-io reads and the durability class it would decide with default trust. Creates, probes and removes a small temporary file there.

Type Aliases§

AppendBatchLinux or macOS or Windows
Many appends, one barrier (see store_io_engine::AppendBatch).
AppendRegionLinux or macOS or Windows
A region store-io appends to (see store_io_engine::AppendRegion).
MissingSet
Set of Missing evidence items.
NativePlatformLinux or macOS
The operating system’s native backend.
PageBatchLinux or macOS or Windows
Many page writes, one barrier (see store_io_engine::PageBatch).
PageRegionLinux or macOS or Windows
A region of caller-addressed blocks (see store_io_engine::PageRegion).
ReasonSet
Set of Reasons.
ReservationLinux or macOS or Windows
Space set aside for provisioning (see store_io_engine::Reservation).
Result
Result with Error.
SlotLinux or macOS or Windows
A small object committed atomically (see store_io_engine::Slot).
SubmitterLinux or macOS or Windows
Many reads and writes in flight from one thread, without blocking (see store_io_engine::Submitter); from Store::submitter.