Struct DurableCheckpointStore 

pub struct DurableCheckpointStore { /* private fields */ }

Filesystem-backed durable checkpoint store.

Every store constructed for the same normalized path in one process shares writer generations, so a cancelled older async save cannot replace a newer request even when the callers did not clone the same store value. Deployments must still enforce one writer process per checkpoint path; filesystem rename atomicity does not establish ordering between independent processes. Atomic saves currently require Unix; unsupported platforms return a typed error rather than falling back to a remove-then-rename durability gap.

Implementations

impl DurableCheckpointStore

pub fn new(path: impl Into<PathBuf>) -> Self

Use path as the single atomic checkpoint file.

pub fn with_max_checkpoint_bytes(self, max_checkpoint_bytes: u64) -> Self

Override the maximum encoded checkpoint size accepted for reads and writes. The default is DEFAULT_MAX_DURABLE_CHECKPOINT_BYTES.

This bounds file reads and the encoded write allocation; it is not a retention target. Snapshot capture still owns a clone of the cache state before measuring its serialized size, so services must budget capture memory separately. Lower the bound for tightly constrained services or raise it deliberately for unusually large caches.

pub fn max_checkpoint_bytes(&self) -> u64

Maximum encoded checkpoint size accepted by this store.

pub fn path(&self) -> &Path

Path of the checkpoint file.

pub fn save( &self, cache: &EvmCache, metadata: DurableCheckpointMetadata, ) -> Result<(), DurableCheckpointError>

Persist a complete cache snapshot and its commit metadata atomically.

The new file is written and synced in the same directory, renamed over the previous checkpoint, and then the parent directory is synced. A failure before the rename leaves the previous committed file intact. The final rename replaces the destination directory entry itself; if the destination is a symlink, the symlink is replaced rather than followed.

This low-level API can verify the cache’s chain id, but cannot prove that its event-maintained state includes every effect through metadata.block. It trusts that caller assertion and normalizes the persisted exact pin/context to it. Production reactive consumers should normally use ReactiveEngine::*_checkpointed, which derives metadata from the batch committed with the runtime state.

Errors

Returns DurableCheckpointError when cache and metadata chain/context identity disagree, the generation counter is exhausted, encoding exceeds the configured size bound, or atomic write/sync/replace fails.

pub async fn save_async( &self, cache: &EvmCache, metadata: DurableCheckpointMetadata, ) -> Result<(), DurableCheckpointError>

Persist a complete cache snapshot without serializing or syncing the checkpoint file on the async runtime worker.

Capturing the owned cache snapshot is synchronous, but the potentially long bincode encode, file write, fsync, rename, and directory fsync run on Tokio’s blocking pool. This keeps checkpoint durability out of event transport and heartbeat scheduling paths. The same low-level metadata trust contract as save applies.

Errors

Returns DurableCheckpointError for the same identity, generation, size, encoding, and filesystem failures as save, or when Tokio’s blocking task cannot be joined.

pub fn load( &self, ) -> Result<Option<LoadedDurableCheckpoint>, DurableCheckpointError>

Load a checkpoint without mutating a cache.

This split lets callers inspect and RPC-validate the canonical hash in LoadedDurableCheckpoint::metadata before choosing to restore it. The configured size ceiling and integrity checksum are verified before any checkpoint payload is decoded.

Errors

Returns DurableCheckpointError for read/metadata failures, oversized files, invalid magic/version/encoding, checksum mismatch, or malformed checkpoint content. A missing file returns Ok(None).

Trait Implementations

impl Clone for DurableCheckpointStore

fn clone(&self) -> DurableCheckpointStore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DurableCheckpointStore

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

Formats the value using the given formatter.

impl Eq for DurableCheckpointStore

impl PartialEq for DurableCheckpointStore

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.