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
//! Versioned state snapshots for long-running engines.
//!
//! Any `Clone` state (an `Indicator`, an `engine::*` tracker, a composition graph) can be captured
//! into a [`Checkpoint`] and restored later, in-process, to deterministically save/rewind
//! execution. When `S` also implements `serde::Serialize`/`Deserialize` (behind the `serde`
//! feature), the checkpoint itself becomes serializable for cross-process persistence — no
//! separate persistence API is required.
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};
/// A versioned, timestamped snapshot of some `Clone`-able engine state `S`.
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct Checkpoint<S: Clone> {
/// Monotonically increasing checkpoint version, incremented by the caller on each capture.
/// Lets consumers detect stale/out-of-order restores.
pub version: u32,
/// The bar timestamp the state reflects (i.e. state after processing this bar).
pub timestamp: i64,
pub state: S,
}
impl<S: Clone> Checkpoint<S> {
/// Captures a snapshot of `state` at `timestamp` tagged with `version`.
pub fn capture(state: &S, timestamp: i64, version: u32) -> Self {
Self {
version,
timestamp,
state: state.clone(),
}
}
/// Overwrites `target` with this checkpoint's state.
pub fn restore_into(&self, target: &mut S) {
*target = self.state.clone();
}
}
/// Keeps the single most recent [`Checkpoint`] for `S`, auto-incrementing the version on every
/// [`CheckpointStore::save`]. Suited for a "last confirmed state" rewind point on a long-running
/// engine.
#[derive(Debug, Clone, Default)]
pub struct CheckpointStore<S: Clone> {
latest: Option<Checkpoint<S>>,
next_version: u32,
}
impl<S: Clone> CheckpointStore<S> {
pub fn new() -> Self {
Self {
latest: None,
next_version: 0,
}
}
/// Captures `state` as the new latest checkpoint, replacing any prior one.
pub fn save(&mut self, state: &S, timestamp: i64) -> u32 {
let version = self.next_version;
self.next_version += 1;
self.latest = Some(Checkpoint::capture(state, timestamp, version));
version
}
pub fn latest(&self) -> Option<&Checkpoint<S>> {
self.latest.as_ref()
}
/// Restores `target` from the latest checkpoint, if one exists.
pub fn restore_into(&self, target: &mut S) -> bool {
match &self.latest {
Some(checkpoint) => {
checkpoint.restore_into(target);
true
}
None => false,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_checkpoint_capture_and_restore() {
let state = vec![1, 2, 3];
let checkpoint = Checkpoint::capture(&state, 1_000, 0);
assert_eq!(checkpoint.version, 0);
assert_eq!(checkpoint.timestamp, 1_000);
let mut target = vec![9, 9];
checkpoint.restore_into(&mut target);
assert_eq!(target, state);
}
#[test]
fn test_checkpoint_store_versions_increment() {
let mut store: CheckpointStore<i32> = CheckpointStore::new();
assert!(store.latest().is_none());
let v0 = store.save(&10, 1_000);
let v1 = store.save(&20, 1_060);
assert_eq!(v0, 0);
assert_eq!(v1, 1);
assert_eq!(store.latest().unwrap().state, 20);
let mut target = 0;
assert!(store.restore_into(&mut target));
assert_eq!(target, 20);
}
}