pub struct JsonFileCheckpointer { /* private fields */ }Expand description
File-backed checkpointer: one pretty-printed JSON file per checkpoint
({dir}/{thread_id}/{checkpoint_id}.json) plus a latest pointer file
({dir}/{thread_id}/latest holding the most recent checkpoint id), using
only serde_json and tokio::fs — no database dependencies.
Writes are atomic: payload is written to a uniquely named temp file in the
same directory and then renamed over the target path, so a crash mid-write
can never leave a truncated checkpoint file behind. Puts are serialized
per thread (an in-process lock per thread_id), so concurrent same-thread
puts cannot interleave the checkpoint file and pointer writes and leave
latest pointing at the older checkpoint. The lock is per-process:
multiple writer PROCESSES over the same directory are not serialized —
treat one writer process per thread directory as a precondition.
Read paths are forgiving: a missing thread directory yields None / an
empty list, a missing or corrupt latest pointer falls back to scanning
the checkpoint files, and individual corrupt checkpoint files are skipped
during scans. Genuine IO failures surface as
RustyError::Checkpoint.
§Delta checkpoints (R0.7 wave 4)
This backend opts into delta encoding: put diffs the incoming full
snapshot against the thread’s materialized head and stores only the
channels that changed, bounded by a DeltaPolicy
(JsonFileCheckpointer::with_delta_policy reconfigures or disables
it). The head is cached in-process (heads), so the hot path diffs
against the previous put’s shared channel values — pointer-equal for
unchanged channels, no re-read — and a cold process rebuilds the cache
entry by reading the current chain once. Reads fold chains transparently
(fold_chain, materialize_all); checkpoint files with no base
field (everything written before W4) load exactly as before.
Implementations§
Source§impl JsonFileCheckpointer
impl JsonFileCheckpointer
Sourcepub fn new(dir: impl Into<PathBuf>) -> Self
pub fn new(dir: impl Into<PathBuf>) -> Self
A checkpointer rooted at dir (created lazily on first put), with
the default DeltaPolicy (delta encoding on, chain bounded at 32).
Sourcepub fn with_delta_policy(dir: impl Into<PathBuf>, policy: DeltaPolicy) -> Self
pub fn with_delta_policy(dir: impl Into<PathBuf>, policy: DeltaPolicy) -> Self
A checkpointer rooted at dir with an explicit delta policy —
DeltaPolicy::full_only restores the pre-W4 full-snapshot write
behavior (the benchmark baseline).
Sourcepub fn delta_policy(&self) -> DeltaPolicy
pub fn delta_policy(&self) -> DeltaPolicy
The delta-chain policy this checkpointer writes under.
Trait Implementations§
Source§impl Checkpointer for JsonFileCheckpointer
impl Checkpointer for JsonFileCheckpointer
Source§fn fork_thread<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
src_thread: &'life1 str,
dst_thread: &'life2 str,
at_checkpoint_id: Option<&'life3 str>,
) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
fn fork_thread<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
src_thread: &'life1 str,
dst_thread: &'life2 str,
at_checkpoint_id: Option<&'life3 str>,
) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Forked histories are written as full snapshots (eager compaction): a fork is a new timeline and the natural compaction point, so time-travel reads on the fork never fold a chain — and never another timeline’s. The source thread is untouched.
Source§fn put<'life0, 'async_trait>(
&'life0 self,
checkpoint: Checkpoint,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn put<'life0, 'async_trait>(
&'life0 self,
checkpoint: Checkpoint,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
Source§fn get_latest<'life0, 'life1, 'async_trait>(
&'life0 self,
thread_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
fn get_latest<'life0, 'life1, 'async_trait>(
&'life0 self,
thread_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
None if the thread has
never been checkpointed. Recency is defined by insertion (put)
order — the last successfully stored checkpoint wins — not by
super-step number: replay on the same thread legitimately appends
checkpoints whose step is at or below the existing head, and a
later resume must continue that newest timeline. Read moreSource§fn list<'life0, 'life1, 'async_trait>(
&'life0 self,
thread_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Vec<Checkpoint>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
fn list<'life0, 'life1, 'async_trait>(
&'life0 self,
thread_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Vec<Checkpoint>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Source§fn get_by_id<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
thread_id: &'life1 str,
checkpoint_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
fn get_by_id<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
thread_id: &'life1 str,
checkpoint_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Source§impl Clone for JsonFileCheckpointer
impl Clone for JsonFileCheckpointer
Source§fn clone(&self) -> JsonFileCheckpointer
fn clone(&self) -> JsonFileCheckpointer
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more