Skip to main content

JsonFileCheckpointer

Struct JsonFileCheckpointer 

Source
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

Source

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).

Source

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).

Source

pub fn delta_policy(&self) -> DeltaPolicy

The delta-chain policy this checkpointer writes under.

Source

pub fn dir(&self) -> &Path

The root directory checkpoints are stored under.

Trait Implementations§

Source§

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,

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,

Persist a checkpoint. Implementations must not overwrite an existing checkpoint with the same id (ids are unique by construction). Read more
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,

The most recent checkpoint for a thread, or 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 more
Source§

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,

All checkpoints for a thread, oldest first (time-travel listing). Read more
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,

Fetch one specific checkpoint of a thread by id (time-travel handle). Read more
Source§

impl Clone for JsonFileCheckpointer

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for JsonFileCheckpointer

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more