Per-node result cache. More...

#include <node_cache.h>

Public Member Functions
void	clear ()
	Drop all cached entries (per-node enable/disable state preserved).

std::size_t	eviction_count () const
	Lifetime capacity-eviction count. clear() and overwrite do not count.

std::size_t	hit_count () const
	Lifetime hit count (incremented on lookup that returns a value).

bool	is_enabled (const std::string &node_name) const
	True iff `set_enabled(node_name, true)` was the last call for it.

std::optional< NodeResult >	lookup (const std::string &node_name, const std::string &state_hash) const
	Lookup. nullopt if no cached result for this (node, state_hash).

std::optional< NodeResult >	lookup (const std::string &node_name, const std::string &state_hash, const std::string &scope_key) const
	Lookup with the execution or caller-declared reusable scope key.

std::size_t	max_entries () const
	Configured global entry bound. Zero means unbounded.

std::size_t	miss_count () const
	Lifetime miss count (incremented on lookup that returns nullopt for an enabled node).

CacheKeyPolicy	policy_for (const std::string &node_name) const
	Return a node's policy, or the safe execution-local default.

void	set_enabled (const std::string &node_name, bool enabled)
	Enable / disable caching for a specific node.

void	set_max_entries (std::size_t max_entries)
	Set the global entry bound.

void	set_policy (const std::string &node_name, CacheKeyPolicy policy)
	Set a node's cache identity policy. The default is execution-local.

std::size_t	size () const
	Number of entries currently held.

void	store (const std::string &node_name, const std::string &state_hash, const std::string &scope_key, NodeResult result)
	Store with the execution or caller-declared reusable scope key.

void	store (const std::string &node_name, const std::string &state_hash, NodeResult result)
	Store the NodeResult for this (node, state_hash).

Detailed Description

Per-node result cache.

Opt-in per node — callers must explicitly enable caching via set_enabled(name, true) so semantics never silently change for non-deterministic nodes.

Cache key = node name + state hash + an explicit scope key. The default scope key is a unique execution ID, so cache entries never cross tenant, Store, ToolGate, provider/model, resume, or other RunContext boundaries. Reusable caching is an explicit policy decision. Cache values are full NodeResults (writes + Command + Sends), so a cached hit replays the original outcome without re-running the node. Hit / miss / eviction counters are exposed for observability. max_entries == 0 preserves the historical unbounded behavior. A positive limit evicts the least-recently-used entry; ties are broken by the encoded cache key so serial operation is deterministic.

Only safe for pure nodes — deterministic, no external side effects, no time-dependent behavior. Streaming nodes are skipped because cached hits cannot replay token events.

Thread-safe: protected by an internal mutex. Callers should remember that fan-out branches see the same cache instance, so the first parallel branch to compute a (node, state) pair populates the entry the rest hit.

Definition at line 75 of file node_cache.h.

Member Function Documentation

◆ set_max_entries()

void neograph::graph::NodeCache::set_max_entries ( std::size_t max_entries )

Set the global entry bound.

Zero means unbounded. Lowering the limit evicts least-recently-used entries immediately.

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

include/neograph/graph/node_cache.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ set_max_entries()