Struct CheckpointManager 

pub struct CheckpointManager {
    config: CheckpointConfig,
    storage: Box<dyn CheckpointStorage>,
    actors: HashMap<u32, (String, String)>,
    last_snapshot: HashMap<u32, Instant>,
    pending: HashMap<u64, PendingSnapshot>,
    next_request_id: u64,
    checkpoint_history: HashMap<u32, Vec<String>>,
    total_completed: u64,
    total_failed: u64,
}

Manages periodic checkpointing for persistent GPU actors.

The CheckpointManager orchestrates the checkpoint lifecycle:

1. Periodically determines when a snapshot is due
2. Issues SnapshotRequests (caller sends as H2K commands)
3. Processes SnapshotResponses (caller feeds from K2H responses)
4. Persists completed checkpoints to storage
5. Enforces retention policy (deletes old checkpoints)

Usage

use ringkernel_core::checkpoint::{CheckpointConfig, CheckpointManager};
use std::time::Duration;

let config = CheckpointConfig::new(Duration::from_secs(10))
    .with_max_snapshots(3)
    .with_storage_path("/tmp/checkpoints");

let mut manager = CheckpointManager::new(config);
manager.register_actor(0, "wave_sim_0", "fdtd_3d");

// In your poll loop:
for request in manager.poll_due_snapshots() {
    // Send as H2K SnapshotActor command
    h2k_queue.send(H2KMessage::snapshot_actor(
        request.request_id,
        request.actor_slot,
        request.buffer_offset,
    ));
}

// When K2H SnapshotComplete arrives:
manager.complete_snapshot(SnapshotResponse { ... })?;

Fields

config: CheckpointConfig

storage: Box<dyn CheckpointStorage>

actors: HashMap<u32, (String, String)>

last_snapshot: HashMap<u32, Instant>

pending: HashMap<u64, PendingSnapshot>

next_request_id: u64

checkpoint_history: HashMap<u32, Vec<String>>

total_completed: u64

total_failed: u64

Implementations

impl CheckpointManager

pub fn new(config: CheckpointConfig) -> CheckpointManager

Create a new checkpoint manager with file storage at the configured path.

pub fn with_storage( config: CheckpointConfig, storage: Box<dyn CheckpointStorage>, ) -> CheckpointManager

Create a checkpoint manager with a custom storage backend.

pub fn register_actor( &mut self, actor_slot: u32, kernel_id: impl Into<String>, kernel_type: impl Into<String>, )

Register an actor for periodic checkpointing.

pub fn unregister_actor(&mut self, actor_slot: u32)

Unregister an actor from checkpointing.

pub fn is_enabled(&self) -> bool

Check if checkpointing is enabled.

pub fn config(&self) -> &CheckpointConfig

Get the checkpoint configuration.

pub fn pending_count(&self) -> usize

Get the number of pending snapshot requests.

pub fn total_completed(&self) -> u64

Get total completed snapshots.

pub fn total_failed(&self) -> u64

Get total failed snapshots.

pub fn poll_due_snapshots(&mut self) -> Vec<SnapshotRequest>

Poll for actors that are due for a snapshot.

Returns a list of SnapshotRequests that should be sent to the device as H2K SnapshotActor commands.

Each actor is only requested once per interval, and only if no prior request for that actor is still pending.

pub fn complete_snapshot( &mut self, response: SnapshotResponse, ) -> Result<Option<String>, RingKernelError>

Process a completed snapshot response from the device.

If the snapshot succeeded, the data is persisted to storage and the retention policy is enforced.

Returns the checkpoint name on success.

pub fn request_snapshot(&mut self, actor_slot: u32) -> Option<SnapshotRequest>

Manually request a snapshot for a specific actor, bypassing the interval timer.

This is useful for on-demand snapshots (e.g., before a risky operation) or in tests. Returns None if the actor is not registered.

pub fn cancel_pending(&mut self, request_id: u64) -> bool

Cancel a pending snapshot request.

Returns true if the request was found and cancelled.

pub fn cancel_all_pending(&mut self)

Cancel all pending snapshot requests.

pub fn load_latest( &self, actor_slot: u32, ) -> Result<Option<Checkpoint>, RingKernelError>

Load the most recent checkpoint for an actor.

pub fn list_checkpoints( &self, actor_slot: u32, ) -> Result<Vec<String>, RingKernelError>

List all checkpoint names for an actor.

pub fn storage(&self) -> &dyn CheckpointStorage

Get a reference to the storage backend.