neograph::graph::GraphState Class Reference

Thread-safe container for all graph state channels. More...

#include <state.h>

Public Member Functions
void	apply_writes (const std::vector< ChannelWrite > &writes)
	Apply a batch of channel writes atomically (exclusive lock).
std::optional< std::vector< sp::Message > >	captured_provider_messages (const std::string &channel="messages") const
	Captured C++ history only; never interprets an arbitrary JSON channel.
std::vector< std::string >	channel_names () const
	List all channel names in this state.
uint64_t	channel_version (const std::string &channel) const
	Get the version of a specific channel.
json	ephemeral_checkpoint_guard () const
	Record which non-checkpointed channels existed at this checkpoint.
template<typename T >
T	get (const ChannelKey< T > &channel) const
	Read and convert a channel using a reusable typed key.
json	get (const std::string &channel) const
	Read a channel's current value (thread-safe, shared lock).
std::vector< ChatMessage >	get_messages () const
	Convenience method to read the "messages" channel as a vector of ChatMessage.
std::vector< sp::Message >	get_provider_messages (const std::string &channel="messages") const
	Full ordered provider history; JSON is only its portable projection.
uint64_t	global_version () const
	Get the state's write counter.
bool	has_channel (const std::string &channel) const
	Whether the graph declared this channel.
void	init_channel (const std::string &name, ReducerType type, ReducerFn reducer, const json &initial_value=json(), ChannelLifecyclePolicy lifecycle={})
	Initialize a new channel with reducer and lifecycle policy.
void	restore (const json &data)
	Restore durable channels from a JSON snapshot.
void	restore_checkpoint (const json &data, const json &guard, std::shared_ptr< const NativeGraphCheckpoint > native={})
	Reject missing/incompatible guards and lost ephemeral values before restoring a durable checkpoint.
json	serialize () const
	Serialize checkpointed channel values and versions to JSON.
json	serialize_cache () const
	Cacheable channel/native inputs, excluding operational budget authority.
json	serialize_runtime () const
	Isolated in-process Send workers need every live channel, including ephemeral values.
template<typename T >
std::optional< T >	try_get (const ChannelKey< T > &channel) const
	Read a typed channel when it is declared.
void	write (const std::string &channel, const json &value)
	Write a value to a single channel through its reducer (exclusive lock).

Detailed Description

Thread-safe container for all graph state channels.

Provides concurrent read access (shared lock) and exclusive write access (unique lock) to state channels. Supports serialization for checkpointing and version tracking for change detection.

Definition at line 55 of file state.h.

Member Function Documentation

apply_writes()

void neograph::graph::GraphState::apply_writes

(

const std::vector< ChannelWrite > &

writes

)

Apply a batch of channel writes atomically (exclusive lock).

All writes in the batch are applied under a single lock acquisition, ensuring consistency when multiple channels must be updated together.

Parameters

writes

Vector of ChannelWrite objects to apply.

channel_names()

std::vector< std::string > neograph::graph::GraphState::channel_names

(

)

const

List all channel names in this state.

Returns

Vector of channel name strings.

channel_version()

uint64_t neograph::graph::GraphState::channel_version

(

const std::string &

channel

)

const

Get the version of a specific channel.

The version is the value of the state's write counter (global_version()) at the channel's last write. All channels share that counter, so it orders writes but does not count the writes of this channel.

Parameters

channel

Channel name.

Returns

The channel's version; 0 if it was never written or does not exist.

ephemeral_checkpoint_guard()

json neograph::graph::GraphState::ephemeral_checkpoint_guard

(

)

const

Record which non-checkpointed channels existed at this checkpoint.

A written ephemeral value cannot be reconstructed on resume.

get() [1/2]

template<typename T >

T neograph::graph::GraphState::get ( const ChannelKey< T > &  channel ) const

inline

Read and convert a channel using a reusable typed key.

Exceptions

json::type_error

If the current value cannot be converted to T.

Definition at line 83 of file state.h.

get() [2/2]

json neograph::graph::GraphState::get

(

const std::string &

channel

)

const

Read a channel's current value (thread-safe, shared lock).

Parameters

channel

Channel name.

Returns

The current value, or null if the channel does not exist.

get_messages()

std::vector< ChatMessage > neograph::graph::GraphState::get_messages

(

)

const

Convenience method to read the "messages" channel as a vector of ChatMessage.

Returns

Vector of ChatMessage objects from the "messages" channel.

global_version()

uint64_t neograph::graph::GraphState::global_version

(

)

const

Get the state's write counter.

Every write to any channel adds 1 to it and stamps the written channel with the new value. It starts at 0, is restored from a checkpoint, and counts the writes of the run input as well as those of the nodes.

Returns

The counter's current value, the version of the latest write.

has_channel()

bool neograph::graph::GraphState::has_channel

(

const std::string &

channel

)

const

Whether the graph declared this channel.

write() throws on an undeclared channel, so code that writes into a channel it does not own (the engine seeding a resume value into "messages", say) must ask first rather than assume the graph is shaped like a chat.

init_channel()

void neograph::graph::GraphState::init_channel	(	const std::string &	name,
		ReducerType	type,
		ReducerFn	reducer,
		const json &	initial_value = json(),
		ChannelLifecyclePolicy	lifecycle = {}
	)

Initialize a new channel with reducer and lifecycle policy.

Writes are combined by the reducer, normalized by retention, and then projected to checkpoints according to persistence. Existing callers that pass only an initial value retain the historical unbounded, checkpointed behavior.

restore()

void neograph::graph::GraphState::restore

(

const json &

data

)

Restore durable channels from a JSON snapshot.

Parameters

data	JSON object previously produced by serialize().

serialize()

json neograph::graph::GraphState::serialize

(

)

const

Serialize checkpointed channel values and versions to JSON.

Returns

JSON snapshot without ephemeral channel values.

serialize_runtime()

json neograph::graph::GraphState::serialize_runtime

(

)

const

Isolated in-process Send workers need every live channel, including ephemeral values.

Never pass this representation to a checkpoint store.

try_get()

template<typename T >

std::optional< T > neograph::graph::GraphState::try_get ( const ChannelKey< T > &  channel ) const

inline

Read a typed channel when it is declared.

Missing channels return std::nullopt. Conversion failures remain errors so a schema/type mismatch is not mistaken for absence.

Definition at line 94 of file state.h.

write()

void neograph::graph::GraphState::write	(	const std::string &	channel,
		const json &	value
	)

Write a value to a single channel through its reducer (exclusive lock).

Parameters

channel	Channel name.
value	Value to merge via the channel's reducer.

---

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

• include/neograph/graph/state.h