Module graph 

Graph execution and management.

Graph - Pure Stream Implementation

This module defines the Graph struct for managing graph structures and executing async node graphs. Graphs contain nodes and edges, and provide methods for both structure management (sync) and execution (async).

Stream-Based Execution

The graph execution engine works purely with streams:

1. Collects input streams for each node from connected upstream nodes
2. Calls node.execute(inputs) which returns output streams
3. Connects output streams to downstream nodes’ input streams
4. Drives all streams to completion

Channels are used internally for backpressure, but are never exposed to nodes. Nodes only see and work with streams.

Graph as Node (Nested Graphs)

Graph implements the Node trait, allowing graphs to be used as nodes within other graphs. This enables hierarchical composition and reusable subgraphs.

Port Mapping

When a graph is used as a node, you must explicitly map internal node ports to external ports using expose_input_port() and expose_output_port():

• Input ports: "configuration" and "input" (fixed external names)
• Output ports: "output" and "error" (fixed external names)

Pull-Based Execution

Graphs use a pull-based execution model:

1. When a graph’s output port is consumed, it signals readiness backward
2. This propagates through internal nodes to the graph’s input ports
3. Data flows only when downstream nodes are ready to consume

Lifecycle Control

Graphs support full lifecycle control:

• start() - Begin execution (sets state to running)
• pause() - Pause execution (maintains state, stops processing new data)
• resume() - Resume execution after pause
• stop() - Stop execution and clear all state (discards in-flight data)

Example: Nested Graphs

use streamweave;
use streamweave::node::Node;
use streamweave::edge::Edge;

// Create a subgraph
let mut subgraph = Graph::new("subgraph".to_string());
// ... add nodes and edges to subgraph ...

// Expose internal ports as external ports
subgraph.expose_input_port("internal_source", "in", "input")?;
subgraph.expose_output_port("internal_sink", "out", "output")?;

// Use subgraph as a node in parent graph
let mut parent = Graph::new("parent".to_string());
let subgraph_node: Box<dyn Node> = Box::new(subgraph);
parent.add_node("subgraph".to_string(), subgraph_node)?;

// Connect to subgraph's external ports
parent.add_edge(Edge {
    source_node: "source".to_string(),
    source_port: "out".to_string(),
    target_node: "subgraph".to_string(),
    target_port: "input".to_string(),
})?;

Structs

Graph

A graph containing nodes and edges.

Functions

topological_sort

Helper function to perform topological sort of nodes in a graph.

Type Aliases

GraphExecutionError

Error type for graph execution operations.