laminar_storage/per_core_wal/mod.rs
1//! # Per-Core WAL
2//!
3//! Per-core WAL segments for thread-per-core architecture. Each core writes to its own
4//! WAL file without contention, and segments are merged during checkpoint for global recovery.
5//!
6//! ## Architecture
7//!
8//! ```text
9//! ┌─────────────────────────────────────────────────────────────────┐
10//! │ Thread-Per-Core with Per-Core WAL │
11//! ├─────────────────────────────────────────────────────────────────┤
12//! │ │
13//! │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
14//! │ │ Core 0 │ │ Core 1 │ │ Core 2 │ │
15//! │ │ │ │ │ │ │ │
16//! │ │ Changelog │ │ Changelog │ │ Changelog │ │
17//! │ │ │ │ │ │ │ │ │ │ │
18//! │ │ ▼ │ │ ▼ │ │ ▼ │ │
19//! │ │ wal-0.log │ │ wal-1.log │ │ wal-2.log │ │
20//! │ └──────────────┘ └──────────────┘ └──────────────┘ │
21//! │ │ │ │ │
22//! │ └─────────────────┼─────────────────┘ │
23//! │ │ │
24//! │ ▼ │
25//! │ ┌─────────────────┐ │
26//! │ │ Checkpoint │ │
27//! │ │ Coordinator │ │
28//! │ │ │ │
29//! │ │ Merge segments │ │
30//! │ │ by epoch order │ │
31//! │ └─────────────────┘ │
32//! │ │
33//! └─────────────────────────────────────────────────────────────────┘
34//! ```
35//!
36//! ## Key Components
37//!
38//! - [`CoreWalWriter`]: Per-core WAL writer (lock-free, no cross-core sync)
39//! - [`PerCoreWalEntry`]: WAL entry with epoch for cross-core ordering
40//! - [`PerCoreWalReader`]: Reader for a single segment file
41//! - [`PerCoreWalManager`]: Coordinates all core writers
42//! - [`CheckpointCoordinator`]: Merges segments during checkpoint
43//! - [`PerCoreRecoveryManager`]: Recovery from multiple segments
44//!
45//! ## Core Invariant
46//!
47//! ```text
48//! Checkpoint(epoch) + WAL.replay(epoch..current) = Consistent State
49//! ```
50//!
51//! Entries are ordered by (epoch, timestamp_ns) for deterministic recovery.
52//!
53//! ## Example
54//!
55//! ```rust,no_run
56//! use laminar_storage::per_core_wal::{
57//! PerCoreWalConfig, PerCoreWalManager, WalOperation,
58//! };
59//! use std::path::Path;
60//!
61//! // Create manager for 4 cores
62//! let config = PerCoreWalConfig::new(Path::new("/data/wal"), 4);
63//! let mut manager = PerCoreWalManager::new(config).unwrap();
64//!
65//! // Each core writes to its own segment (lock-free)
66//! manager.writer(0).append_put(b"key1", b"value1").unwrap();
67//! manager.writer(1).append_put(b"key2", b"value2").unwrap();
68//! manager.writer(0).sync().unwrap();
69//! manager.writer(1).sync().unwrap();
70//!
71//! // During checkpoint, merge all segments
72//! let merged = manager.merge_segments().unwrap();
73//! // merged is sorted by (epoch, timestamp_ns)
74//! ```
75
76mod coordinator;
77mod entry;
78mod error;
79mod manager;
80mod reader;
81mod recovery;
82mod writer;
83
84pub use coordinator::CheckpointCoordinator;
85pub use entry::{PerCoreWalEntry, WalOperation};
86pub use error::PerCoreWalError;
87pub use manager::{PerCoreWalConfig, PerCoreWalManager};
88pub use reader::PerCoreWalReader;
89pub use recovery::{recover_per_core, PerCoreRecoveredState, PerCoreRecoveryManager, SegmentStats};
90pub use writer::CoreWalWriter;