neograph::graph::CheckpointStore Class Reference

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, most recently saved first, one entry per ID; the first entry is load_latest().
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 recently saved 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 bool	requires_managed_budget (const std::string &thread_id)
	Whether this trusted checkpoint namespace/thread has ever held an active standalone managed bank.
virtual bool	retains_native_checkpoint () const noexcept
	Describes real local C++ custody, not a financial admission/grant.
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

This legacy interface is retained through the pre-v1 ABI window. New sync backends implement CheckpointStoreCore and call adapt_checkpoint_store(); native async backends implement AsyncCheckpointStore and call adapt_async_checkpoint_store(). Legacy sync defaults fail explicitly, while async defaults offload sync operations. No sync default calls its async peer.

Definition at line 400 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, neograph::graph::SqliteCheckpointStore, and neograph::tenant::ScopedCheckpointStore.

Definition at line 512 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, neograph::graph::SqliteCheckpointStore, and neograph::tenant::ScopedCheckpointStore.

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, neograph::graph::SqliteCheckpointStore, and neograph::tenant::ScopedCheckpointStore.

Definition at line 497 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, most recently saved first, one entry per ID; the first entry is load_latest().

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, neograph::graph::SqliteCheckpointStore, and neograph::tenant::ScopedCheckpointStore.

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, neograph::graph::SqliteCheckpointStore, and neograph::tenant::ScopedCheckpointStore.

load_latest()

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

virtual

Load the most recently saved checkpoint for a thread.

"Latest" is save order, not timestamp or step: a later run on a thread restarts at step 0, and saves can share a millisecond.

Parameters

thread_id

Thread identifier.

Returns

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

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

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::tenant::ScopedCheckpointStore, neograph::graph::InMemoryCheckpointStore, neograph::graph::PostgresCheckpointStore, and neograph::graph::SqliteCheckpointStore.

Definition at line 483 of file checkpoint.h.

requires_managed_budget()

virtual bool neograph::graph::CheckpointStore::requires_managed_budget ( const std::string &  thread_id )

virtual

Whether this trusted checkpoint namespace/thread has ever held an active standalone managed bank.

Saving stripped state or deleting checkpoints must not clear the obligation. This flag grants no currency; the original complete bank must still authenticate before restoration. Unsupported backends throw rather than authorize an absent bank.

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

save()

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

virtual

Save a checkpoint.

Saving an ID the thread already holds replaces that checkpoint and makes it the thread's latest, as if it were saved for the first time.

Parameters

cp	The checkpoint to persist.

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

---

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

• include/neograph/graph/checkpoint.h