oxifaster/
checkpoint.rs

1//! Checkpoint and recovery for FASTER
2//!
3//! This module provides checkpointing and recovery functionality
4//! for FasterKV stores.
5//!
6//! # Overview
7//!
8//! FASTER uses the CPR (Concurrent Prefix Recovery) protocol for checkpointing,
9//! which allows checkpoints to be taken without stopping normal operations.
10//!
11//! # Checkpoint Types
12//!
13//! - **Full Checkpoint**: Saves both index and hybrid log state
14//! - **Index-Only Checkpoint**: Saves only the hash index
15//! - **HybridLog-Only Checkpoint**: Saves only the log state
16//! - **Incremental Checkpoint**: Saves only changes since last snapshot
17//!
18//! # CPR Protocol Phases
19//!
20//! 1. **PrepIndexChkpt**: Prepare index checkpoint, synchronize threads
21//! 2. **IndexChkpt**: Write index to disk
22//! 3. **Prepare**: Prepare HybridLog checkpoint
23//! 4. **InProgress**: Increment version, mark checkpoint in progress
24//! 5. **WaitPending**: Wait for pending operations
25//! 6. **WaitFlush**: Wait for log flush
26//! 7. **PersistenceCallback**: Invoke persistence callback
27//! 8. **Rest**: Return to rest state
28//!
29//! # File Structure
30//!
31//! Each checkpoint creates a directory with the following files:
32//!
33//! - `index.meta`: Index checkpoint metadata (JSON)
34//! - `index.dat`: Hash index data (binary)
35//! - `log.meta`: Log checkpoint metadata (JSON)
36//! - `log.snapshot`: Log snapshot data (binary)
37//!
38//! # Usage
39//!
40//! ```rust,ignore
41//! use std::path::Path;
42//!
43//! // Create checkpoint
44//! let token = store.checkpoint(Path::new("/checkpoints"))?;
45//!
46//! // Recover from checkpoint
47//! let recovered = FasterKv::recover(
48//!     Path::new("/checkpoints"),
49//!     token,
50//!     config,
51//!     device
52//! )?;
53//! ```
54
55/// C-style binary format serialization for FASTER C++ compatibility
56pub mod binary_format;
57mod locks;
58mod recovery;
59pub mod serialization;
60mod state;
61
62pub use locks::{
63    AtomicCheckpointLock, CheckpointLock, CheckpointLockGuard, CheckpointLocks, LockType,
64};
65pub(crate) use recovery::{build_incremental_chain, validate_incremental_checkpoint};
66pub use recovery::{
67    find_latest_checkpoint, list_checkpoints, validate_checkpoint, CheckpointInfo,
68    PageRecoveryStatus, RecoveryState, RecoveryStatus,
69};
70pub use serialization::{
71    create_checkpoint_directory, delta_log_path, delta_metadata_path, incremental_info_path,
72    index_data_path, index_metadata_path, log_metadata_path, log_snapshot_path, DeltaLogMetadata,
73    IncrementalCheckpointChain, SerializableCheckpointInfo, SerializableIndexMetadata,
74    SerializableLogMetadata,
75};
76pub use state::{CheckpointState, CheckpointType, IndexMetadata, LogMetadata, SessionState};
77
78use uuid::Uuid;
79
80/// Token identifying a checkpoint
81pub type CheckpointToken = Uuid;
82
83/// Callback for index persistence completion
84pub type IndexPersistenceCallback = Box<dyn FnOnce(crate::Status) + Send + 'static>;
85
86/// Callback for hybrid log persistence completion
87pub type HybridLogPersistenceCallback = Box<dyn FnOnce(crate::Status, u64) + Send + 'static>;
oxifaster/checkpoint.rs

oxifaster/
checkpoint.rs
