a3s_flow/
execution.rs

1//! Execution handle and state types.
2//!
3//! [`ExecutionState`] is the public snapshot of a workflow execution.
4//! [`ExecutionHandle`] is an internal struct held by [`FlowEngine`] to control
5//! a running execution via a signal channel and a cancellation token.
6
7use std::sync::Arc;
8
9use tokio::sync::{watch, RwLock};
10use tokio_util::sync::CancellationToken;
11
12use crate::result::FlowResult;
13use crate::runner::FlowSignal;
14
15/// Snapshot of a workflow execution's current lifecycle state.
16#[derive(Debug, Clone)]
17pub enum ExecutionState {
18    /// Actively executing nodes.
19    Running,
20    /// Paused at a wave boundary; waiting for a resume signal.
21    Paused,
22    /// Finished successfully. Contains the per-node outputs.
23    Completed(FlowResult),
24    /// Aborted due to a node error. Contains the error message.
25    Failed(String),
26    /// Stopped by an external [`FlowEngine::terminate`](crate::engine::FlowEngine::terminate) call.
27    Terminated,
28}
29
30impl ExecutionState {
31    /// Short label used in error messages.
32    pub fn as_str(&self) -> &'static str {
33        match self {
34            Self::Running => "running",
35            Self::Paused => "paused",
36            Self::Completed(_) => "completed",
37            Self::Failed(_) => "failed",
38            Self::Terminated => "terminated",
39        }
40    }
41
42    /// Returns `true` if the execution has reached a terminal state and will
43    /// not change again.
44    pub fn is_terminal(&self) -> bool {
45        matches!(
46            self,
47            Self::Completed(_) | Self::Failed(_) | Self::Terminated
48        )
49    }
50}
51
52/// Internal control handle for a single execution managed by [`FlowEngine`].
53pub(crate) struct ExecutionHandle {
54    /// Shared, mutable execution state. Updated by the runner task (terminal
55    /// states) and by the engine (pause / resume).
56    pub(crate) state: Arc<RwLock<ExecutionState>>,
57    /// Sends pause / run signals to the runner task.
58    pub(crate) signal_tx: watch::Sender<FlowSignal>,
59    /// Cancellation token — call `.cancel()` to terminate the execution.
60    pub(crate) cancel: CancellationToken,
61}
a3s_flow/execution.rs

a3s_flow/
execution.rs
