neograph::graph::RunContext Struct Reference

Per-run dispatch metadata threaded through the engine and executor. More...

#include <engine.h>

Public Attributes
std::shared_ptr< CancelToken >	cancel_token
	Cooperative cancel handle.
std::optional< std::chrono::steady_clock::time_point >	deadline
	Optional absolute wall-clock deadline.
int	step = 0
	Current super-step index.
std::shared_ptr< Store >	store
	Cross-thread shared memory (issue #27).
StreamMode	stream_mode = StreamMode::ALL
	Mirrors RunConfig::stream_mode.
std::string	thread_id
	Mirrors RunConfig::thread_id so executor-side logic (e.g.
std::string	trace_id
	Per-run trace correlator.

Detailed Description

Per-run dispatch metadata threaded through the engine and executor.

Built from RunConfig at the top of execute_graph_async and carried by reference through every internal dispatch hop (NodeExecutor::run_one_async / run_parallel_async / run_sends_async / execute_node_with_retry_async). Replaces the v0.3.x-era smuggling channels — GraphState::run_cancel_token_ and the current_cancel_token() thread-local — with one explicit argument that survives every Send-fan-out / serialize-restore / thread-hop.

PR 1 (v0.4.0) is plumbing-only: the struct exists, the engine builds it, and NodeExecutor carries it through, but nothing yet consumes it. GraphNode::execute_full_async still receives only state. The smuggling channels remain authoritative until subsequent PRs flip the consumers (PR 2: new run(NodeInput) virtual; PR 3: hierarchical CancelToken; PR 4: deprecate the smuggling).

Cheap to copy (one shared_ptr + a couple of strings); workers that need an isolated copy take it by value, the common path takes it by const reference.

See also

RunConfig (the caller-supplied source) and ROADMAP_v1.md (Candidate 2: "Explicit RunContext for per-run metadata").

Definition at line 118 of file engine.h.

Member Data Documentation

cancel_token

std::shared_ptr<CancelToken> neograph::graph::RunContext::cancel_token

Cooperative cancel handle.

Mirrors RunConfig::cancel_token. Null when the caller did not opt in.

Definition at line 121 of file engine.h.

deadline

std::optional<std::chrono::steady_clock::time_point> neograph::graph::RunContext::deadline

Optional absolute wall-clock deadline.

Reserved for a future PR (RunConfig has no deadline field today); left std::nullopt by the engine for now so existing behaviour is unchanged.

Definition at line 126 of file engine.h.

step

int neograph::graph::RunContext::step = 0

Current super-step index.

Updated by the engine at the top of each super-step iteration so per-step consumers see a consistent value without the engine threading int step separately.

Definition at line 141 of file engine.h.

store

std::shared_ptr<Store> neograph::graph::RunContext::store

Cross-thread shared memory (issue #27).

Mirrors GraphEngine::get_store(). Populated by the engine at the top of every run so node bodies can read / write Store-backed state through in.ctx.store without a separate plumbing channel.

Default nullptr. The engine sets this to whatever the caller previously passed to GraphEngine::set_store(...); if no Store is configured, in.ctx.store stays nullptr and node bodies should guard accordingly.

Before this field existed, the only way for a node body to reach the Store was to capture a shared_ptr<Store> in the NodeFactory registration closure. That pattern still works and is left undisturbed during the deprecation window — use whichever shape fits your code best:

// New shape (post-#27):
asio::awaitable<NodeOutput> run(NodeInput in) override {
    if (in.ctx.store) {
        auto v = in.ctx.store->get(ns, "user.fact");
    }
    ...
}
 
// Legacy factory-closure shape — still supported:
NodeFactory::instance().register_type("my_node",
    [store](const std::string& name, const json&, const NodeContext&) {
        return std::make_unique<MyNode>(name, store);  // ← capture
    });

Definition at line 181 of file engine.h.

thread_id

std::string neograph::graph::RunContext::thread_id

Mirrors RunConfig::thread_id so executor-side logic (e.g.

future per-thread metric tags) does not have to hold a separate RunConfig reference.

Definition at line 136 of file engine.h.

trace_id

std::string neograph::graph::RunContext::trace_id

Per-run trace correlator.

Reserved for OTel integration; the engine does not populate this in PR 1 (callers can fill it via a future RunConfig::trace_id field).

Definition at line 131 of file engine.h.

---

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

• include/neograph/graph/engine.h