Struct CheckpointedStageState 

pub struct CheckpointedStageState<T> { /* private fields */ }

A stage state wrapper with durable checkpoint/restore support.

Serializes the state to a BlockLease on checkpoint and deserializes on restore, using a format compatible with the grafos-collections Durable pattern.

Fail-closed

If a checkpoint write fails, the error is propagated immediately. Callers should halt the stage rather than continue with an uncheckpointed state.

Preemption protection (Phase 218.2 / slice 96)

When constructed with CheckpointedStageState::with_observer, the wrapper notifies a CheckpointFlushObserver at flush start and complete so the scheduler-service can mark the lease as NonPreemptibleReason::CheckpointInProgress. The marker is cleared on BOTH the success path and every failure path via an RAII guard. Wrappers constructed via CheckpointedStageState::new continue to flush without the sideband notification (back-compat).

Implementations

impl<T: Serialize + DeserializeOwned> CheckpointedStageState<T>

pub fn new(state: T, block_lease: BlockLease) -> Self

Create a new checkpointed state wrapper.

Does not write an initial checkpoint. Call checkpoint to persist.

Constructed without a CheckpointFlushObserver — checkpoint flushes do NOT emit preemption-protection sideband notifications. Use Self::with_observer to attach the marker producer for NonPreemptibleReason::CheckpointInProgress (Phase 218.2 / slice 96).

pub fn with_observer( state: T, block_lease: BlockLease, lease_id: u128, observer: Box<dyn CheckpointFlushObserver + Send + Sync>, ) -> Self

Phase 218.2 / slice 96 — attach a CheckpointFlushObserver and the lease_id of the lease whose preemption window the flush occupies. Calls to Self::checkpoint then notify the observer at flush start AND on flush complete (both success AND failure paths, via an RAII guard).

The producer is responsible for naming the correct lease_id — the lease backing the stage’s durable checkpoint storage (BlockLease). The observer is typically the scheduler-service PreemptionManager’s checkpoint adapter (see grafos_scheduler_service::preemption::PreemptionCheckpointObserver).

pub fn checkpoint(&mut self) -> Result<(), EdgeError>

Serialize the current state to block storage.

Uses a header block + data block layout:

• Block 0: magic (4) + version (4) + data_len (8)
• Blocks 1..N: postcard-serialized state bytes

Preemption protection (Phase 218.2 / slice 96)

When this CheckpointedStageState was constructed via Self::with_observer, the observer’s on_flush_start is called at the top of this method and on_flush_complete is called when the flush returns — on BOTH the success path and every failure path. The notification is implemented via an RAII guard so partway-through errors don’t leave the lease stuck in CheckpointInProgress.

Errors

Returns EdgeError::CheckpointFailed on serialization or I/O failure.

pub fn restore(block_lease: BlockLease) -> Result<Self, EdgeError>

Restore a checkpointed state from block storage.

Reads the header block to determine data length, then reads and deserializes the state from the data blocks.

Errors

Returns EdgeError::CheckpointFailed on corrupt data, version mismatch, or deserialization failure.

pub fn state(&self) -> &T

Borrow the current state.

pub fn state_mut(&mut self) -> &mut T

Mutably borrow the current state.

pub fn into_block_lease(self) -> BlockLease

Consume the wrapper and return the underlying block lease.

This allows transferring the lease to a subsequent restore call so that both sides access the same underlying block storage.