Struct WorkflowGuardState 

pub struct WorkflowGuardState { /* private fields */ }

Mutable runtime state tracked by the guard during a workflow execution.

Shared between parent and child workflows via Arc<Mutex<_>> so that limits are enforced globally across the entire run tree.

Examples

use ironflow_engine::guard::{WorkflowGuardConfig, WorkflowGuardState};

let mut state = WorkflowGuardState::new();
let config = WorkflowGuardConfig::new().with_max_depth(2);

state.record_invocation("workflow-a");
state.record_invocation("workflow-b");
assert!(state.check(&config, "workflow-c").is_err());

Implementations

impl WorkflowGuardState

pub fn new() -> Self

Create a fresh guard state for a new workflow execution.

Examples

use ironflow_engine::guard::WorkflowGuardState;

let state = WorkflowGuardState::new();
assert_eq!(state.depth(), 0);
assert_eq!(state.total_invocations(), 0);

pub fn with_tokens_used(self, tokens: u64) -> Self

Seed the tokens already used by earlier executions of the run tree.

Call it before the state is shared.

Examples

use ironflow_engine::guard::WorkflowGuardState;

let state = WorkflowGuardState::new().with_tokens_used(700);
assert_eq!(state.total_tokens_used(), 700);

pub fn with_elapsed(self, elapsed: Duration) -> Self

Seed the active time spent by earlier executions of the run.

Examples

use std::time::Duration;

use ironflow_engine::guard::WorkflowGuardState;

let state = WorkflowGuardState::new().with_elapsed(Duration::from_secs(30));
assert!(state.elapsed_secs() >= 30);

pub fn with_deadline_at(self, deadline_at: DateTime<Utc>) -> Self

Set the absolute deadline of the run.

Examples

use chrono::Utc;
use ironflow_engine::guard::WorkflowGuardState;

let at = Utc::now();
let state = WorkflowGuardState::new().with_deadline_at(at);
assert_eq!(state.deadline_at(), Some(at));

pub fn deadline_at(&self) -> Option<DateTime<Utc>>

The absolute deadline of the run, if any.

Examples

use ironflow_engine::guard::WorkflowGuardState;

assert_eq!(WorkflowGuardState::new().deadline_at(), None);

pub fn depth(&self) -> u32

Current sub-workflow nesting depth.

pub fn total_invocations(&self) -> u32

Total workflow invocations so far.

pub fn total_tokens_used(&self) -> u64

Total tokens consumed so far.

pub fn call_chain(&self) -> &[String]

The current call chain (workflow name stack).

pub fn elapsed_secs(&self) -> u64

Seconds of active execution time across every execution of the run, sleeping excluded.

pub fn check( &self, config: &WorkflowGuardConfig, target_workflow: &str, ) -> Result<(), WorkflowRejection>

Read-only check: would invoking target_workflow violate any limit?

Does not mutate state. Call this before record_invocation.

Errors

Returns the specific WorkflowRejection variant that would be violated.

Examples

use ironflow_engine::guard::{WorkflowGuardConfig, WorkflowGuardState, WorkflowRejection};

let state = WorkflowGuardState::new();
let config = WorkflowGuardConfig::new().with_max_depth(0);

let err = state.check(&config, "child").unwrap_err();
assert!(matches!(err, WorkflowRejection::MaxDepthExceeded { .. }));

pub fn record_invocation(&mut self, target_workflow: &str)

Record that a sub-workflow invocation is starting.

Increments depth and fan-out counter, and pushes the workflow name onto the call chain for cycle detection.

Examples

use ironflow_engine::guard::WorkflowGuardState;

let mut state = WorkflowGuardState::new();
state.record_invocation("child-workflow");
assert_eq!(state.depth(), 1);
assert_eq!(state.total_invocations(), 1);
assert_eq!(state.call_chain(), &["child-workflow"]);

pub fn record_return(&mut self)

Record that a sub-workflow invocation has returned.

Decrements depth and pops the last entry from the call chain. Safe to call even on failure paths (the guard must never leak depth).

Examples

use ironflow_engine::guard::WorkflowGuardState;

let mut state = WorkflowGuardState::new();
state.record_invocation("child");
assert_eq!(state.depth(), 1);

state.record_return();
assert_eq!(state.depth(), 0);
assert!(state.call_chain().is_empty());

pub fn record_tokens( &mut self, config: &WorkflowGuardConfig, tokens_used: u64, ) -> Result<u64, WorkflowRejection>

Record tokens consumed by an agent step.

Returns the remaining token budget, or an error if the budget is now exhausted.

Errors

Returns WorkflowRejection::TokenBudgetExhausted when the cumulative usage exceeds the configured maximum.

Examples

use ironflow_engine::guard::{WorkflowGuardConfig, WorkflowGuardState, WorkflowRejection};

let mut state = WorkflowGuardState::new();
let config = WorkflowGuardConfig::new().with_max_workflow_tokens(100);

assert!(state.record_tokens(&config, 50).is_ok());
assert!(state.record_tokens(&config, 60).is_err());

Trait Implementations

impl Debug for WorkflowGuardState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WorkflowGuardState

fn default() -> Self

Returns the “default value” for a type.