Skip to main content

Module executor

Module executor 

Source
Expand description

The executor: a Pregel/BSP-inspired super-step run loop.

Execution proceeds in discrete super-steps (Google Pregel / Bulk-Synchronous-Parallel), each super-step being:

  1. Plan — determine the active node set (entry point on step 0; afterwards the routing result of the previous step, including crate::node::Command::goto overrides and crate::graph::Send fan-outs).
  2. Compute — run all active nodes concurrently in a tokio::task::JoinSet, each receiving an immutable snapshot of the state as of the start of the step. No node can observe another’s in-progress writes.
  3. Barrier — wait for all active nodes. The step is transactional: if any node fails, the step’s writes are discarded. An RustyError::Interrupt suspends the whole run instead.
  4. Merge — apply all node updates to the state via crate::state::StateSpec::apply_super_step (per-channel reducers + LastValue single-write validation).
  5. Route — evaluate outgoing edges / commands against the post-barrier state to determine the next active set; Route::End (or an empty next set) terminates the run.
  6. Checkpoint — persist a crate::checkpoint::Checkpoint recording step, state, and next nodes, and emit GraphEvents for streaming.

A graph cycle (e.g. the ReAct loop agent → tools → agent) is not call-stack recursion — it is nodes being re-scheduled across super-steps, which is why the guard is max_steps, not a stack limit.

§Observability

The executor emits tracing telemetry throughout a run (no subscriber is installed by the library — the application chooses one):

  • rusty.run (INFO span) — one per Executor::run call, carrying thread_id and max_steps; parent of everything below.
  • rusty.super_step (DEBUG span) — one per super-step, carrying step and active_nodes; covers plan → barrier → merge → route.
  • rusty.node (INFO span) — one per spawned node task, carrying node and step; attached to the JoinSet task via .instrument().
  • DEBUG event on each barrier merge (channels written), INFO events on interrupt and run completion (steps, duration_ms), WARN events on node failure (with a retryable classification).

Structs§

Executor
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).
RunConfig
Per-run configuration (the LangGraph RunnableConfig analog).

Enums§

ExecutionOutcome
How a run ended.
GraphEvent
Streaming events emitted by the executor during a run. All of LangGraph’s stream modes are views over this single typed event stream.

Constants§

DEFAULT_MAX_STEPS
Default super-step limit. Deliberately far above LangGraph’s default recursion_limit of 25: ReAct-style loops burn one super-step per agent/tool hop, so long tool chains legitimately exceed 25.