1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
//! # 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")?;
//! # let _ = (pos, start, receipt);
//! # Ok::<(), store_io::Error>(())
//! ```
//!
//! `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.
// Without a native backend the simple-API types do not exist, so the links
// above have no target there.
/// The generic engine under the simple API (stores over any platform,
/// including the simulator).
pub use store_io_engine as engine;
pub use ;
pub use ;
pub use ;
pub use Evidence;
pub use ;
/// The observer's types: `Store::observe()` returns an [`observe::Snapshot`].
pub use observe;
pub use ;
/// A read stream's items and options ([`ReadStream`]).
pub use ;
/// Export through a caller's sink (`Store::export`, `Store::export_with`):
/// its options, the header and each region's info a sink is told, the
/// sink's trait and errors, and the report.
pub use ;
pub use ;
/// The [`Submitter`]'s types: its configuration, buffers, completions and
/// refusals, and the waker that ends its `wait` from another thread.
/// The operating system's native backend.
pub type NativePlatform = WinPlatform;
/// The operating system's native backend.
pub type NativePlatform = PosixPlatform;
/// 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).
pub use io_uring_fallbacks;
pub use ;
/// What [`probe`] found out about a directory's device.