pub struct Executor { /* private fields */ }Expand description
The graph executor. Holds an optional checkpointer and an optional
middleware chain; stateless with respect to individual runs, so one
Executor can drive many concurrent runs (each with its own
thread_id).
Implementations§
Source§impl Executor
impl Executor
Sourcepub fn new() -> Self
pub fn new() -> Self
An executor without persistence (runs cannot be interrupted/resumed durably; interrupts will still surface but resume requires a checkpointer).
Sourcepub fn with_checkpointer(checkpointer: Arc<dyn Checkpointer>) -> Self
pub fn with_checkpointer(checkpointer: Arc<dyn Checkpointer>) -> Self
An executor persisting checkpoints through checkpointer.
Sourcepub fn layer<M: Middleware + 'static>(self, middleware: M) -> Self
pub fn layer<M: Middleware + 'static>(self, middleware: M) -> Self
Builder-style: attach a middleware layer (Middleware/Interceptor
SDK). Layers compose in registration order — before-hooks run in
.layer() order on the way into a node/model/tool call, after-hooks
in reverse order on the way out. See crate::middleware.
Builder-style: attach a pre-shared middleware layer.
Sourcepub fn middleware(&self) -> &MiddlewareChain
pub fn middleware(&self) -> &MiddlewareChain
The attached middleware chain (empty when no layers were added).
Sourcepub fn with_effect_admission(self, compensations: CompensationRegistry) -> Self
pub fn with_effect_admission(self, compensations: CompensationRegistry) -> Self
Builder-style: make guarded tool effect admission available to nodes.
The supplied registry may be empty. Pure and read-only calls remain
automatic; idempotent calls require a key, compensatable calls require
a handler in this registry, and non-idempotent calls require a matching
token in RunConfig::effect_approvals. The prebuilt ReAct tools node
enforces this automatically. Custom nodes must pass
NodeContext::effect_admission to the crate::tool::ToolExecutor
they construct; direct crate::tool::Tool::call invocations are not
intercepted by the executor.
Sourcepub fn effect_admission_enabled(&self) -> bool
pub fn effect_admission_enabled(&self) -> bool
Whether this executor enforces the effect admission boundary.
Sourcepub fn with_token_tx(self, token_tx: Sender<GraphEvent>) -> Self
pub fn with_token_tx(self, token_tx: Sender<GraphEvent>) -> Self
Builder-style: hold a token broadcast sender that nodes can clone to
publish GraphEvent::Token deltas (LangGraph’s messages stream
mode).
The executor never emits Token events itself — tokens originate in
nodes calling crate::llm::ChatModel::chat_stream. This is a
convenience handle so node factories built around an Executor can
fetch the sink via Executor::token_tx and capture a clone in each
node closure. When the same channel should also receive the
executor’s own events, attach it to the run via
RunConfig::with_event_tx instead (or as well).
Sourcepub fn token_tx(&self) -> Option<&Sender<GraphEvent>>
pub fn token_tx(&self) -> Option<&Sender<GraphEvent>>
The token broadcast sender, if one was attached via
Executor::with_token_tx. Clone it into node closures to stream
GraphEvent::Tokens from within nodes.
Sourcepub fn with_memory_source(self, source: MemorySource) -> Self
pub fn with_memory_source(self, source: MemorySource) -> Self
Builder-style: install the governed-memory source this executor’s
runs answer memory reads from (R0.8 wave 1; see
crate::memory::MemorySource).
The executor never reads or writes memory itself this wave — the
full run-loop integration is a later wave. This is the seam’s
installation point, mirroring Executor::with_token_tx: node
factories built around an Executor fetch the journaled handle via
Executor::memory once the run has started and capture a clone in
each node closure. Nodes may equally bind a source to an attached
journal directly (crate::journal::Journal::memory); both paths
journal into the same run evidence.
Sourcepub fn memory_source(&self) -> Option<&MemorySource>
pub fn memory_source(&self) -> Option<&MemorySource>
The configured memory source, if one was installed via
Executor::with_memory_source.
Sourcepub fn memory(&self) -> Option<JournaledMemory>
pub fn memory(&self) -> Option<JournaledMemory>
The journaled memory handle for the most recent run: the run’s
journal (set at run start) bound to the configured source. None
before the first run or when no source is installed. The same
most-recent-run caveat as Executor::journal applies: driving
several runs concurrently through one Executor leaves this handle
pointing at whichever run started last — bind per-run handles via
crate::journal::Journal::memory when runs overlap.
Sourcepub fn checkpointer(&self) -> Option<&Arc<dyn Checkpointer>>
pub fn checkpointer(&self) -> Option<&Arc<dyn Checkpointer>>
The configured checkpointer, if any. Shared (not consumed) so one
Executor can drive many concurrent runs over the same store.
Sourcepub fn journal(&self) -> Option<Journal>
pub fn journal(&self) -> Option<Journal>
The Flight Recorder journal of the most recent run started through
this executor — the one attached via RunConfig::with_journal, or
the fresh journal the executor created for the run. None before the
first run.
The journal is set at run start, so the evidence of a failed or
suspended run is retrievable exactly like a completed run’s. Note the
executor is deliberately stateless across runs: driving several runs
concurrently through one Executor leaves this handle pointing at
whichever run started last — attach per-run journals via the config
when runs overlap.
Sourcepub async fn run(
&self,
graph: &Graph,
spec: &StateSpec,
initial_state: State,
config: RunConfig,
) -> Result<ExecutionOutcome>
pub async fn run( &self, graph: &Graph, spec: &StateSpec, initial_state: State, config: RunConfig, ) -> Result<ExecutionOutcome>
Run a compiled graph to completion (or interruption).
graph: the compiled, frozen graph topology.spec: the state schema (channels + reducers) used to merge node updates at each barrier.initial_state: the starting state. Whenconfig.resumeis set and a checkpoint exists forconfig.thread_id, the checkpointed state and next-node set take precedence over this argument. Whenconfig.checkpoint_idis set, that specific checkpoint (rather than the latest) is restored — replay/time travel; forking into a fresh thread first viacrate::checkpoint::Checkpointer::fork_threadis the safe pattern, since replaying on the same thread appends new history.config: run configuration (thread id, step limit, resume value, streaming sink).
§Super-step semantics
Each loop iteration runs one super-step as a transaction: the active
nodes execute in parallel over an immutable start-of-step snapshot;
the barrier discards the whole step’s writes on any node failure and
suspends the run on an interrupt; only then are writes merged via the
channel reducers, routing computed against the post-barrier state,
and a boundary checkpoint persisted. The module-level docs enumerate
the six phases; execute_super_step is the implementation.
The loop returns ExecutionOutcome::Done when routing yields an
empty next set, ExecutionOutcome::Interrupted when a node
interrupts, an RustyError::Graph error once config.max_steps
super-steps have run without termination, and
RustyError::Cancelled when RunConfig::cancellation is
observed cancelled at a super-step boundary (the boundary checkpoint
is intact; the run resumes from it).