Skip to main content

lellm_graph/node/
parallel_node.rs

1//! ParallelNode — 并行执行多个分支,通过 MergeStrategy 合并 State。
2//!
3//! 执行模型:
4//! ```text
5//! State
6//!  ↓
7//! fork (ParallelNode)
8//!  ↓
9//! Branch A     Branch B     Branch C
10//!  ↓            ↓            ↓
11//! State<S>     State<S>     State<S>
12//!  ↓            ↓            ↓
13//! MergeStrategy<S>::merge(branches)
14//!  ↓
15//! Merged State → replace parent state
16//! ```
17//!
18//! 每个分支接收相同的 State 快照,独立产生变更(通过 Effects)。
19//! 所有分支完成后,变更通过 MergeStrategy 合并到 State。
20
21use std::sync::Arc;
22use std::time::Instant;
23
24#[allow(deprecated)]
25use super::FlowNode;
26use crate::error::GraphError;
27use crate::exec::execution_engine::{ExecutionEngine, ExecutorState, OwnedExecutionEngine};
28use crate::state::workflow_state::{MergeStrategy, WorkflowState};
29use crate::state::{State, StateMerge};
30
31/// 并行节点 — 同时执行多个分支,通过 MergeStrategy 合并 State。
32///
33/// 每个分支接收相同的 State 快照,独立产生变更。
34/// 所有分支完成后,变更通过 MergeStrategy 合并。
35///
36/// # 泛型参数
37///
38/// - `S` — 类型化状态
39/// - `M` — 合并策略(默认为 [`StateMerge`])
40///
41/// # 示例
42///
43/// ```rust,ignore
44/// let parallel = ParallelNode::builder()
45///     .branch("search", Arc::new(SearchNode::new()))
46///     .branch("analyze", Arc::new(AnalyzeNode::new()))
47///     .build();
48///
49/// graph.node("research", NodeKind::Parallel(parallel));
50/// ```
51#[allow(deprecated)]
52pub struct ParallelNode<S: WorkflowState = State, M: MergeStrategy<S> = StateMerge> {
53    label: Option<String>,
54    branches: Vec<(String, Arc<dyn FlowNode<S>>)>,
55    error_strategy: ParallelErrorStrategy,
56    /// Phantom — M 通过 `M::merge()` 静态调用,不需要实例。
57    _merge_strategy: std::marker::PhantomData<M>,
58}
59
60impl<S: WorkflowState, M: MergeStrategy<S>> Clone for ParallelNode<S, M> {
61    fn clone(&self) -> Self {
62        Self {
63            label: self.label.clone(),
64            branches: self.branches.clone(),
65            error_strategy: self.error_strategy,
66            _merge_strategy: std::marker::PhantomData,
67        }
68    }
69}
70
71/// 并行执行错误处理策略。
72#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
73pub enum ParallelErrorStrategy {
74    /// 任一分支失败 → 立即返回错误(其余分支继续执行但结果被忽略)
75    #[default]
76    FailFast,
77    /// 等待所有分支完成,至少一个失败 → 返回错误但包含成功分支的变更
78    CollectAll,
79}
80
81impl ParallelNode {
82    /// 创建默认构建器(`State` + `StateMerge`)。
83    pub fn builder() -> ParallelNodeBuilder {
84        ParallelNodeBuilder::new()
85    }
86}
87
88impl<S: WorkflowState, M: MergeStrategy<S>> ParallelNode<S, M> {
89    pub fn with_label(mut self, label: impl Into<String>) -> Self {
90        self.label = Some(label.into());
91        self
92    }
93
94    pub fn branch_count(&self) -> usize {
95        self.branches.len()
96    }
97
98    pub fn branch_names(&self) -> Vec<&str> {
99        self.branches
100            .iter()
101            .map(|(name, _)| name.as_str())
102            .collect()
103    }
104
105    #[allow(deprecated)]
106    pub fn branches_iter(&self) -> impl Iterator<Item = (&str, &Arc<dyn FlowNode<S>>)> {
107        self.branches
108            .iter()
109            .map(|(name, node)| (name.as_str(), node))
110    }
111
112    pub fn error_strategy(&self) -> ParallelErrorStrategy {
113        self.error_strategy
114    }
115
116    pub fn label(&self) -> Option<&str> {
117        self.label.as_deref()
118    }
119
120    fn display_name(&self) -> String {
121        self.label.clone().unwrap_or_else(|| "parallel".to_string())
122    }
123}
124
125/// ParallelNode 构建器。
126#[allow(deprecated)]
127pub struct ParallelNodeBuilder<S: WorkflowState = State, M: MergeStrategy<S> = StateMerge> {
128    label: Option<String>,
129    branches: Vec<(String, Arc<dyn FlowNode<S>>)>,
130    error_strategy: ParallelErrorStrategy,
131    _phantom: std::marker::PhantomData<M>,
132}
133
134impl<S: WorkflowState, M: MergeStrategy<S>> ParallelNodeBuilder<S, M> {
135    fn new() -> Self {
136        Self {
137            label: None,
138            branches: Vec::new(),
139            error_strategy: ParallelErrorStrategy::default(),
140            _phantom: std::marker::PhantomData,
141        }
142    }
143
144    pub fn label(mut self, label: impl Into<String>) -> Self {
145        self.label = Some(label.into());
146        self
147    }
148
149    #[allow(deprecated)]
150    pub fn branch(mut self, name: impl Into<String>, node: Arc<dyn FlowNode<S>>) -> Self {
151        self.branches.push((name.into(), node));
152        self
153    }
154
155    pub fn error_strategy(mut self, strategy: ParallelErrorStrategy) -> Self {
156        self.error_strategy = strategy;
157        self
158    }
159
160    pub fn build(self) -> ParallelNode<S, M> {
161        if self.branches.is_empty() {
162            panic!("ParallelNode must have at least one branch");
163        }
164        ParallelNode {
165            label: self.label,
166            branches: self.branches,
167            error_strategy: self.error_strategy,
168            _merge_strategy: std::marker::PhantomData,
169        }
170    }
171
172    /// 替换合并策略,返回新类型的构建器。
173    pub fn merge_strategy<NM>(self) -> ParallelNodeBuilder<S, NM>
174    where
175        NM: MergeStrategy<S>,
176    {
177        ParallelNodeBuilder {
178            label: self.label,
179            branches: self.branches,
180            error_strategy: self.error_strategy,
181            _phantom: std::marker::PhantomData,
182        }
183    }
184}
185
186impl<S: WorkflowState, M: MergeStrategy<S>> std::fmt::Debug for ParallelNode<S, M> {
187    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
188        f.debug_struct("ParallelNode")
189            .field("label", &self.label)
190            .field(
191                "branches",
192                &self
193                    .branches
194                    .iter()
195                    .map(|(n, _)| n.as_str())
196                    .collect::<Vec<_>>(),
197            )
198            .field("error_strategy", &self.error_strategy)
199            .finish()
200    }
201}
202
203impl<S: WorkflowState + Clone + Send + Sync, M: MergeStrategy<S>> ParallelNode<S, M> {
204    /// 执行并行分支 — 创建独立的 OwnedExecutionEngine 给每个分支。
205    #[allow(deprecated)]
206    pub async fn execute(&self, engine: &mut ExecutionEngine<'_, S>) -> Result<(), GraphError> {
207        let start_time = Instant::now();
208        let branch_count = self.branches.len();
209        let display_name = self.display_name();
210
211        tracing::debug!(
212            parallel = %display_name,
213            branches = branch_count,
214            "parallel node started"
215        );
216
217        // Clone typed state for each branch — each branch works on its own copy
218        let base_state = engine.clone_state();
219
220        // Inherit parent's cancel token and stream (fan-out via Arc clone)
221        let parent_cancel = engine.cancel_token().clone();
222        let parent_stream = engine.stream_sink();
223
224        // Clone branch data so async blocks own everything they need
225        let branches: Vec<(String, Arc<dyn super::FlowNode<S>>)> = self
226            .branches
227            .iter()
228            .map(|(n, nd)| (n.clone(), nd.clone()))
229            .collect();
230
231        // Create a future for each branch — no spawn, no 'static required
232        let branch_futures: Vec<_> = branches
233            .into_iter()
234            .map(|(branch_name, node)| {
235                let state = base_state.clone();
236                let child_cancel = parent_cancel.child_token();
237                let child_stream = parent_stream.clone();
238                async move {
239                    let branch_start = Instant::now();
240
241                    // Each branch gets its own OwnedExecutionEngine (child engine)
242                    let mut child_engine =
243                        OwnedExecutionEngine::new(state, child_stream, child_cancel);
244
245                    let mut branch_ctx = child_engine.build_node_context();
246                    let exec_result = node.execute(&mut branch_ctx).await;
247                    // branch_ctx goes out of scope here; explicit drop removed
248                    // (NodeContext only holds references, drop() is a no-op)
249
250                    if let Err(ref e) = exec_result {
251                        return (branch_name, Err(format!("branch execution failed: {e}")));
252                    }
253
254                    // Commit mutations to child engine
255                    child_engine.commit();
256
257                    let duration = branch_start.elapsed();
258
259                    (branch_name, Ok((child_engine.into_state(), duration)))
260                }
261            })
262            .collect();
263
264        // Execute all branches concurrently (no spawn, just concurrent polling)
265        type BranchResult<S> = (String, Result<(S, std::time::Duration), String>);
266        let raw_results: Vec<BranchResult<S>> = futures::future::join_all(branch_futures).await;
267
268        // Process results in branch order
269        let mut branch_states: Vec<S> = Vec::with_capacity(branch_count);
270        let mut errors: Vec<(String, String)> = Vec::new();
271
272        for (branch_name, result) in raw_results {
273            match result {
274                Ok((state, branch_duration)) => {
275                    tracing::debug!(
276                        parallel = %display_name,
277                        branch = %branch_name,
278                        duration_ms = branch_duration.as_millis(),
279                        "branch completed"
280                    );
281                    branch_states.push(state);
282                }
283                Err(reason) => {
284                    errors.push((branch_name, reason));
285                }
286            }
287        }
288
289        // Error handling based on strategy
290        if !errors.is_empty() {
291            match self.error_strategy {
292                ParallelErrorStrategy::FailFast => {
293                    let (name, reason) = &errors[0];
294                    return Err(GraphError::Terminal(
295                        crate::error::TerminalError::NodeExecutionFailed {
296                            node: format!("{}/{}", display_name, name),
297                            source: reason.clone().into(),
298                        },
299                    ));
300                }
301                ParallelErrorStrategy::CollectAll => {
302                    if !branch_states.is_empty() {
303                        for (name, reason) in &errors {
304                            tracing::warn!(
305                                parallel = %display_name,
306                                branch = %name,
307                                error = %reason,
308                                "branch failed (CollectAll strategy)"
309                            );
310                        }
311                    }
312                    let (name, reason) = &errors[0];
313                    return Err(GraphError::Terminal(
314                        crate::error::TerminalError::NodeExecutionFailed {
315                            node: format!("{}/{}", display_name, name),
316                            source: reason.clone().into(),
317                        },
318                    ));
319                }
320            }
321        }
322
323        // Merge all branch states using MergeStrategy — Graph 层并行语义
324        // 传入 base(分支执行前的父状态),策略据此计算各分支 delta,只合并实际变更的 key
325        let merged = M::merge(&base_state, branch_states).map_err(|e| {
326            GraphError::Terminal(crate::error::TerminalError::StateError(format!(
327                "parallel merge conflict: {e}",
328            )))
329        })?;
330
331        // Replace parent state with merged result
332        engine.replace_state(merged);
333
334        tracing::debug!(
335            parallel = %display_name,
336            duration_ms = start_time.elapsed().as_millis(),
337            "parallel node completed"
338        );
339
340        Ok(())
341    }
342}