Abstract interface for checkpoint persistence backends. More...

#include <checkpoint.h>

Inheritance diagram for neograph::graph::CheckpointStore:

Public Member Functions
virtual void	clear_writes (const std::string &, const std::string &)
	Discard pending writes for a parent checkpoint once its successor super-step has been fully committed.

virtual void	delete_thread (const std::string &thread_id)
	Delete all checkpoints for a thread.

virtual std::vector< PendingWrite >	get_writes (const std::string &, const std::string &)
	Load all pending writes attached to a parent checkpoint.

virtual std::vector< Checkpoint >	list (const std::string &thread_id, int limit=100)
	List checkpoints for a thread, ordered by timestamp (newest first).

virtual std::optional< Checkpoint >	load_by_id (const std::string &id)
	Load a checkpoint by its unique ID.

virtual std::optional< Checkpoint >	load_latest (const std::string &thread_id)
	Load the most recent checkpoint for a thread.

virtual void	put_writes (const std::string &, const std::string &, const PendingWrite &)
	Record a successful node execution within an in-progress super-step.

virtual void	save (const Checkpoint &cp)
	Save a checkpoint.

Detailed Description

Abstract interface for checkpoint persistence backends.

Implement this to store checkpoints in databases, files, or other storage systems. The engine uses this interface for save/load operations.

Pending writes (fine-grained progress log)

The put_writes / get_writes / clear_writes family lets the engine record each successful node execution within a super-step, so partial fan-out failures can be resumed without re-running siblings. Custom stores MAY leave the default no-op implementations in place — the engine degrades gracefully to "full super-step replay" semantics, matching the behavior of NeoGraph before this feature existed.

Durability requirement: put_writes must be durable by the time it returns (flushed to whatever backend the store wraps), because the engine calls state.apply_writes only after put_writes succeeds.

Thread safety

Individual ops are atomic; cross-op sequencing is the caller's responsibility. Every backend in-tree (InMemoryCheckpointStore mutex-guards each call; PostgresCheckpointStore / SqliteCheckpointStore use per-call transactions) guarantees that a single save_checkpoint / load_latest / put_writes / delete_thread call observes a consistent snapshot — no torn reads, no half-applied writes. They do NOT serialize sequences of calls for the same thread_id. Concurrent runs against the same thread_id therefore exhibit last-writer-wins on save_checkpoint and last-saver visibility on subsequent load_latest — see GraphEngine's class-level Thread safety section for the engine- side contract. Backend authors implementing this interface MUST preserve the per-call-atomic invariant; callers needing cross-op atomicity (e.g. compare-and-set on the latest checkpoint) must wrap the relevant call sequence behind their own external mutex, or use the engine's cancel_token to drain in-flight runs before issuing an admin op.

See also: InMemoryCheckpointStore for a reference implementation.

Note

Backend authors: this is a "fat" interface (5 sync core + 5 async peers + 3 pending-writes + 1 async pending = 14 virtuals). Defaults bridge sync↔async in both directions (sync calls run_sync(async); async calls execute_in_pool(sync)) so a backend can override only one side per method — but overriding NEITHER yields infinite mutual recursion at call time. The contract is enforced at runtime, not at compile time. A future major version (v1.0) is expected to split this into:

CheckpointStoreCore — 5 sync mandatory virtuals
AsyncCheckpointStore — async peer mixin (optional)
PendingWritesCheckpointStore — pending-writes mixin The current monolithic shape is kept for back-compat. New backends should override at least one of (sync, async) per method to avoid infinite recursion.

Definition at line 207 of file checkpoint.h.

Member Function Documentation

◆ clear_writes()

virtual void neograph::graph::CheckpointStore::clear_writes	(	const std::string &	,
		const std::string &
	)

inlinevirtual

Discard pending writes for a parent checkpoint once its successor super-step has been fully committed.

Called by the engine after the new super-step checkpoint has been durably saved, so pending writes are never cleared while still being the only record of a node's output.

Parameters

thread_id	Thread identifier.
parent_checkpoint_id	Checkpoint whose pending writes to clear.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

Definition at line 318 of file checkpoint.h.

◆ delete_thread()

virtual void neograph::graph::CheckpointStore::delete_thread ( const std::string & thread_id )

virtual

Delete all checkpoints for a thread.

Parameters

thread_id Thread identifier to delete.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

◆ get_writes()

virtual std::vector< PendingWrite > neograph::graph::CheckpointStore::get_writes	(	const std::string &	,
		const std::string &
	)

inlinevirtual

Load all pending writes attached to a parent checkpoint.

Called by the engine on resume to skip already-completed tasks. Default implementation returns an empty vector.

Parameters

thread_id	Thread identifier.
parent_checkpoint_id	Checkpoint whose pending writes to load.

Returns: Vector of pending writes, in insertion order.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

Definition at line 303 of file checkpoint.h.

◆ list()

virtual std::vector< Checkpoint > neograph::graph::CheckpointStore::list	(	const std::string &	thread_id,
		int	limit = `100`
	)

virtual

List checkpoints for a thread, ordered by timestamp (newest first).

Parameters

thread_id	Thread identifier.
limit	Maximum number of checkpoints to return (default: 100).

Returns: Vector of checkpoints.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

◆ load_by_id()

virtual std::optional< Checkpoint > neograph::graph::CheckpointStore::load_by_id ( const std::string & id )

virtual

Load a checkpoint by its unique ID.

Parameters

id	Checkpoint UUID.

Returns: The checkpoint, or std::nullopt if not found.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

◆ load_latest()

virtual std::optional< Checkpoint > neograph::graph::CheckpointStore::load_latest ( const std::string & thread_id )

virtual

Load the most recent checkpoint for a thread.

Parameters

thread_id Thread identifier.

Returns: The latest checkpoint, or std::nullopt if none exists.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

◆ put_writes()

virtual void neograph::graph::CheckpointStore::put_writes	(	const std::string &	,
		const std::string &	,
		const PendingWrite &
	)

inlinevirtual

Record a successful node execution within an in-progress super-step.

Called by the engine immediately after a node returns successfully and before its writes are applied to the shared GraphState. The parent_checkpoint_id anchors the pending write to the super-step boundary it was produced under.

Default implementation is a no-op so custom stores keep working; such stores fall back to "full super-step replay" on resume.

Parameters

thread_id	Thread identifier.
parent_checkpoint_id	Checkpoint marking the start of the in-progress super-step.
write	The pending write record to persist.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

Definition at line 289 of file checkpoint.h.

◆ save()

virtual void neograph::graph::CheckpointStore::save ( const Checkpoint & cp )

virtual

Save a checkpoint.

Parameters

cp	The checkpoint to persist.

Reimplemented in neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

The documentation for this class was generated from the following file:

include/neograph/graph/checkpoint.h

Public Member Functions

Detailed Description

Pending writes (fine-grained progress log)

Thread safety

Member Function Documentation

◆ clear_writes()

◆ delete_thread()

◆ get_writes()

◆ list()

◆ load_by_id()

◆ load_latest()

◆ put_writes()

◆ save()