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
//! # 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.
//!
//! ## 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.
//! - **Engine:** the generic [`engine`] crate under all of it, which also runs
//! on the deterministic simulator.
//!
//! ## Platforms
//!
//! Windows (unbuffered overlapped I/O on IOCP) and Linux (direct I/O,
//! `pwritev2`) have native backends ([`NativePlatform`]). On other targets the
//! types compile but there is no native backend yet; macOS arrives in 0.5.
// 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 ;
pub use ;
/// The operating system's native backend.
pub type NativePlatform = WinPlatform;
/// The operating system's native backend.
pub type NativePlatform = PosixPlatform;
pub use ;
/// What [`probe`] found out about a directory's device.