Skip to main content

store_io/
lib.rs

1//! # store-io
2//!
3//! Durable storage I/O for Rust databases.
4//!
5//! store-io is the layer between a storage engine and the files and devices it
6//! writes to. It moves caller bytes to media and proves when they are durable.
7//! It does not frame, parse or validate the bytes it moves, and it never decides
8//! what a caller keeps after a crash.
9//!
10//! The design rests on four rules:
11//!
12//! - **Durability is decided per device, with evidence.** Each store is probed
13//!   at open and classed as power-safe, flush-required, unverified or unsafe
14//!   from what the device and operating system report. Operating-system cache
15//!   toggles and vendor tables never promote a device.
16//! - **A durable write produces an unforgeable receipt.** Positions, write
17//!   tickets and receipts are distinct opaque types, so a sequence number can
18//!   never be passed where a byte position is expected, and a barrier can never
19//!   be a silent no-op.
20//! - **Failure is fail-stop.** The first failed write or flush poisons the
21//!   device's barrier domain. A flush is never retried and success is never
22//!   reported after a failed one.
23//! - **Nothing hides latency.** There are no timers, no group-commit windows and
24//!   no background threads that wake an idle process.
25//!
26//! ## Quick start
27//!
28#![cfg_attr(
29    any(windows, target_os = "linux", target_os = "macos"),
30    doc = "```no_run"
31)]
32#![cfg_attr(
33    not(any(windows, target_os = "linux", target_os = "macos")),
34    doc = "```ignore"
35)]
36//! use store_io::{Store, StoreOptions};
37//!
38//! // First run: create. Every later run: `Store::open`.
39//! let store = Store::create("data/orders", StoreOptions::default())?;
40//!
41//! // Regions are provisioned once; looking one up never creates it.
42//! let wal = store.provision_append_region("wal", 256 << 20)?;
43//!
44//! // Append any number of bytes; durable when this returns.
45//! let (pos, receipt) = wal.append_durable(b"order 1001: 3 widgets")?;
46//! println!("durable through {} ({})", receipt.durable_through(), receipt.class());
47//!
48//! // Many records, one write and one flush.
49//! let mut batch = wal.batch();
50//! batch.append(b"order 1002")?;
51//! batch.append(b"order 1003")?;
52//! let (start, receipt) = batch.commit()?;
53//!
54//! // Small objects: old or new after any crash.
55//! let manifest = store.provision_slot("manifest")?;
56//! let _receipt = manifest.commit(b"wal@0")?;
57//! # let _ = (pos, start, receipt);
58//! # Ok::<(), store_io::Error>(())
59//! ```
60//!
61//! `docs/GUIDE.md` in the repository walks through every part: append and
62//! page regions, batches, many writers, small objects, recovery with
63//! [`AppendRegion::scan`] and `resume_at`, the device report, errors and
64//! space.
65//!
66//! ## Container format
67//!
68//! Stores are created in container format 2. A store made before 0.5
69//! (format 1) opens read-only ([`Store::open_readonly`]); a writable open
70//! refuses it with `Unsupported(FormatVersion)` before writing anything.
71//! [`copy_store`] (or `store-io copy <old> <new>`) copies it into a new
72//! format-2 store, all or nothing, the source untouched.
73//!
74//! ## Layers
75//!
76//! - **Simple:** [`Store`], [`AppendRegion`], [`PageRegion`], [`Slot`] and
77//!   [`Directory`]; every call blocks until its I/O is done and copies the
78//!   caller's bytes once into aligned buffers.
79//! - **Batch:** [`AppendBatch`] and [`PageBatch`]: many writes, one barrier,
80//!   with in-place encoding and no copy.
81//! - **Submitter:** [`Submitter`] ([`submit`]): many reads and writes in
82//!   flight from one thread without blocking, from pooled buffers with no
83//!   copy; tickets come with the completions.
84//! - **Engine:** the generic [`engine`] crate under all of it, which also runs
85//!   on the deterministic simulator.
86//!
87//! ## Platforms
88//!
89//! Windows (unbuffered overlapped I/O on IOCP), Linux (direct I/O, io_uring
90//! or `pwritev2`) and macOS (`pwrite` and `F_FULLFSYNC`, uncached where the
91//! kernel can) have native backends ([`NativePlatform`]). On other targets the
92//! types compile but there is no native backend.
93
94#![deny(warnings)]
95#![forbid(unsafe_code)]
96// Without a native backend the simple-API types do not exist, so the links
97// above have no target there.
98#![cfg_attr(
99    not(any(windows, target_os = "linux", target_os = "macos")),
100    allow(rustdoc::broken_intra_doc_links)
101)]
102#![cfg_attr(docsrs, feature(doc_cfg))]
103
104/// The generic engine under the simple API (stores over any platform,
105/// including the simulator).
106pub use store_io_engine as engine;
107
108pub use store_io_core::class::{
109    CertId, DurabilityClass, Missing, MissingSet, Reason, ReasonSet, ReceiptLabel,
110};
111pub use store_io_core::decide::{ClassDecision, DurableOpen, Trust};
112pub use store_io_core::error::{
113    ByteRange, Capability, CorruptionKind, Error, ErrorContext, FirstCause, Named, NotWrittenCause,
114    Op, OsError, OsErrorSource, ReserveTag, Result,
115};
116pub use store_io_core::evidence::Evidence;
117pub use store_io_core::id::{Generation, RegionId, VolumeId};
118/// The observer's types: `Store::observe()` returns an [`observe::Snapshot`].
119pub use store_io_core::observe;
120pub use store_io_engine::{
121    CONTAINER, COPY_LOCK, COPYING, CopyOptions, CopyReport, DomainStats, DurableReceipt,
122    Outstanding, RegionKind, RegionOptions, RegionPos, Repair, ScanItem, ScanSummary, SpaceReport,
123    StoreOptions, StoreReport, TagSpace, Unavailable, UnavailableRegion, WriteTicket,
124};
125pub use store_io_platform::{IoInterface, IoPath, LinuxTier};
126
127/// The [`Submitter`]'s types: its configuration, buffers, completions and
128/// refusals, and the waker that ends its `wait` from another thread.
129pub mod submit {
130    pub use store_io_engine::completion::{Completion, Completions, Done, Rejected, Written};
131    pub use store_io_engine::{MAX_DEPTH, SubmitterConfig, WriteMode};
132    pub use store_io_platform::{IoBuf, Wake};
133
134    /// The waker of a [`Submitter`](crate::Submitter) on the native backend
135    /// (`Submitter::waker`).
136    #[cfg(any(windows, target_os = "linux", target_os = "macos"))]
137    pub type Waker = store_io_engine::SubmitterWaker<
138        <<crate::NativePlatform as store_io_platform::Platform>::Queue as store_io_platform::Queue>::Waker,
139    >;
140}
141
142/// The operating system's native backend.
143#[cfg(windows)]
144pub type NativePlatform = store_io_win::WinPlatform;
145
146/// The operating system's native backend.
147#[cfg(any(target_os = "linux", target_os = "macos"))]
148pub type NativePlatform = store_io_posix::PosixPlatform;
149
150/// Operations, process-wide, that the io_uring tier finished with a
151/// blocking system call because the kernel would have blocked or cut them
152/// short (never a failure; how often the asynchronous path was not taken).
153#[cfg(target_os = "linux")]
154pub use store_io_posix::io_uring_fallbacks;
155
156#[cfg(any(windows, target_os = "linux", target_os = "macos"))]
157mod native;
158
159#[cfg(any(windows, target_os = "linux", target_os = "macos"))]
160pub use native::{
161    AppendBatch, AppendRegion, Directory, PageBatch, PageRegion, Reservation, Slot, Store,
162    Submitter, copy_store, probe,
163};
164
165/// What [`probe`] found out about a directory's device.
166#[derive(Debug, Clone)]
167pub struct Probe {
168    /// The raw evidence.
169    pub evidence: Evidence,
170    /// The durability class decided from it with default trust.
171    pub decision: ClassDecision,
172}