Struct StateMachineBuilder 

pub struct StateMachineBuilder<S, E, C>
where
    S: State,
    E: Event,
    C: Context,
{
    pub(crate) id: Option<String>,
    pub(crate) transitions: Vec<Transition<S, E, C>>,
    pub(crate) fail_callback: Option<FailCallback<S, E, C>>,
    pub(crate) state_actions: HashMap<S, StateActions<S, E, C>>,
    pub(crate) state_timeouts: HashMap<S, Duration>,
    pub(crate) timeout_transitions: HashMap<S, (S, E)>,
    pub(crate) async_actions: HashMap<(S, E), Box<dyn AsyncAction<S, E, C>>>,
}

Builder for creating state machines with fluent API

Fields

id: Option<String>

transitions: Vec<Transition<S, E, C>>

fail_callback: Option<FailCallback<S, E, C>>

state_actions: HashMap<S, StateActions<S, E, C>>

state_timeouts: HashMap<S, Duration>

timeout_transitions: HashMap<S, (S, E)>

async_actions: HashMap<(S, E), Box<dyn AsyncAction<S, E, C>>>

Implementations

impl<S, E, C> StateMachineBuilder<S, E, C>

where S: State, E: Event, C: Context,

pub fn new() -> Self

Create a new state machine builder

pub fn id(self, id: impl Into<String>) -> Self

Set the ID of the state machine

Examples found in repository

examples/traffic_light_example.rs (line 68)

pub fn build_traffic_light_system(
) -> StateMachine<TrafficLightState, TrafficLightEvent, TrafficContext> {
    let mut builder =
        StateMachineBuilderFactory::create::<TrafficLightState, TrafficLightEvent, TrafficContext>(
        );

    // Configure the state machine based on available features
    configure_basic_transitions(&mut builder);

    #[cfg(feature = "extended")]
    configure_entry_exit_actions(&mut builder);

    #[cfg(feature = "guards")]
    configure_priority_transitions(&mut builder);

    #[cfg(feature = "timeout")]
    configure_timeouts(&mut builder);

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        eprintln!(
            "WARNING: Invalid transition from {:?} with {:?} at intersection {}",
            state, event, ctx.intersection_id
        );
    }));
    builder.id("TrafficLightController").build()
}

examples/order_example.rs (line 66)

fn basic_example() {
    println!("=== Basic State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Order {} payment initiated", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed for order {}", ctx.order_id);
        });

    let state_machine = builder.id("BasicOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-001".to_string(),
        amount: 99.99,
        customer_id: "CUST-123".to_string(),
    };

    let result = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());
    println!("Transition result: {:?}", result);
}

/// Example 2: With history tracking (requires 'history' feature)
#[cfg(feature = "history")]
fn history_example() {
    println!("\n=== History Tracking Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("HistoryOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-002".to_string(),
        amount: 149.99,
        customer_id: "CUST-456".to_string(),
    };

    // Execute multiple transitions
    let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());
    let _ = state_machine.fire_event(
        OrderState::PaymentPending,
        OrderEvent::ConfirmPayment,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);

    // Check history
    let history = state_machine.get_history();
    println!("Transition history:");
    for (i, record) in history.iter().enumerate() {
        println!(
            "  {}. {:?} -> {:?} via {:?} (success: {})",
            i + 1,
            record.from,
            record.to,
            record.event,
            record.success
        );
    }
}

/// Example 3: With entry/exit actions (requires 'extended' feature)
#[cfg(feature = "extended")]
fn extended_example() {
    println!("\n=== Extended State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .with_entry_action(OrderState::Processing, |state, ctx| {
            println!(
                "ENTRY: Starting to process order {} in state {:?}",
                ctx.order_id, state
            );
        })
        .with_exit_action(OrderState::Processing, |state, ctx| {
            println!(
                "EXIT: Finished processing order {} from state {:?}",
                ctx.order_id, state
            );
        })
        .with_entry_action(OrderState::Shipped, |_state, ctx| {
            println!("ENTRY: Order {} has been shipped!", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("ExtendedOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-003".to_string(),
        amount: 299.99,
        customer_id: "CUST-789".to_string(),
    };

    let _ = state_machine.fire_event(
        OrderState::PaymentReceived,
        OrderEvent::Process,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::Processing, OrderEvent::Ship, context);
}

/// Example 4: With metrics (requires 'metrics' feature)
#[cfg(feature = "metrics")]
fn metrics_example() {
    println!("\n=== Metrics Collection Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Add multiple transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("MetricsOrderMachine").build();

    // Simulate multiple orders
    for i in 0..10 {
        let context = OrderContext {
            order_id: format!("ORD-{:03}", i),
            amount: (i as f64) * 10.0,
            customer_id: format!("CUST-{:03}", i),
        };

        let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());

        if i % 3 == 0 {
            // Some orders get cancelled
            let _ =
                state_machine.fire_event(OrderState::PaymentPending, OrderEvent::Cancel, context);
        } else {
            // Others proceed normally
            let _ = state_machine.fire_event(
                OrderState::PaymentPending,
                OrderEvent::ConfirmPayment,
                context,
            );
        }
    }

    // Get and display metrics
    let metrics = state_machine.get_metrics();
    println!("State Machine Metrics:");
    println!("  Total transitions: {}", metrics.total_transitions);
    println!("  Successful: {}", metrics.successful_transitions);
    println!("  Failed: {}", metrics.failed_transitions);
    println!("  Success rate: {:.2}%", metrics.success_rate() * 100.0);

    if let Some(avg_time) = metrics.average_transition_time() {
        println!("  Average transition time: {:?}", avg_time);
    }

    println!("  State visit counts:");
    for (state, count) in &metrics.state_visit_counts {
        println!("    {}: {}", state, count);
    }
}

/// Example 5: With guard priorities (requires 'guards' feature)
#[cfg(feature = "guards")]
fn guards_example() {
    println!("\n=== Guard Priorities Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Multiple transitions with different priorities
    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount < 100.0)
        .with_priority(10)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing small order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 100.0 && ctx.amount < 1000.0)
        .with_priority(20)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing medium order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 1000.0)
        .with_priority(30)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing large order {} (amount: {}) - Priority handling!",
                ctx.order_id, ctx.amount
            );
        });

    let state_machine = builder.id("GuardsOrderMachine").build();

    // Test with different order amounts
    let contexts = vec![
        OrderContext {
            order_id: "ORD-SMALL".to_string(),
            amount: 50.0,
            customer_id: "C1".to_string(),
        },
        OrderContext {
            order_id: "ORD-MEDIUM".to_string(),
            amount: 500.0,
            customer_id: "C2".to_string(),
        },
        OrderContext {
            order_id: "ORD-LARGE".to_string(),
            amount: 5000.0,
            customer_id: "C3".to_string(),
        },
    ];

    for context in contexts {
        let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);
    }
}

/// Example 6: With visualization (requires 'visualization' feature)
#[cfg(feature = "visualization")]
fn visualization_example() {
    println!("\n=== Visualization Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Build a complete order flow
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Shipped)
        .to(OrderState::Delivered)
        .on(OrderEvent::Deliver)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Cancelled)
        .to(OrderState::Refunded)
        .on(OrderEvent::Refund)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("VisualOrderMachine").build();

    println!("DOT Format:");
    println!("{}", state_machine.to_dot());

    println!("\nPlantUML Format:");
    println!("{}", state_machine.to_plantuml());
}

/// Example 7: With parallel regions (requires 'parallel' feature)
#[cfg(feature = "parallel")]
fn parallel_example() {
    println!("\n=== Parallel Regions Example ===");

    // Order processing region
    let mut order_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    order_builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, ctx| {
            println!("Order region: Processing order {}", ctx.order_id);
        });

    // Payment processing region (using same states/events for simplicity)
    let mut payment_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    payment_builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!(
                "Payment region: Payment confirmed for order {}",
                ctx.order_id
            );
        });

    let mut parallel_machine = ParallelStateMachine::new();
    parallel_machine.add_region(order_builder.id("OrderRegion").build());
    parallel_machine.add_region(payment_builder.id("PaymentRegion").build());

    let context = OrderContext {
        order_id: "ORD-PARALLEL".to_string(),
        amount: 199.99,
        customer_id: "CUST-P1".to_string(),
    };

    // Fire events in parallel regions
    println!("Firing Process event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::New, OrderState::PaymentPending],
        OrderEvent::Process,
        context.clone(),
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }

    println!("Firing ConfirmPayment event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::Processing, OrderState::PaymentPending],
        OrderEvent::ConfirmPayment,
        context,
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }
}

/// Example 8: Complete example with multiple features
#[cfg(all(feature = "history", feature = "metrics", feature = "extended"))]
fn complete_example() {
    println!("\n=== Complete Example with Multiple Features ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Configure entry/exit actions
    builder
        .with_entry_action(OrderState::Processing, |_s, ctx| {
            println!("[ENTRY] Starting to process order {}", ctx.order_id);
        })
        .with_exit_action(OrderState::Processing, |_s, ctx| {
            println!("[EXIT] Finished processing order {}", ctx.order_id);
        });

    // Build transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Payment initiated for ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed: ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, ctx| {
            println!("Order {} shipped", ctx.order_id);
        });

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        println!(
            "FAILED: Cannot handle {:?} in state {:?} for order {}",
            event, state, ctx.order_id
        );
    }));

    let state_machine = builder.id("CompleteOrderMachine").build();

    // Process an order through the complete flow
    let context = OrderContext {
        order_id: "ORD-COMPLETE".to_string(),
        amount: 999.99,
        customer_id: "CUST-VIP".to_string(),
    };

    println!("\nProcessing order through complete flow:");
    let states = [
        (OrderState::New, OrderEvent::Pay),
        (OrderState::PaymentPending, OrderEvent::ConfirmPayment),
        (OrderState::PaymentReceived, OrderEvent::Process),
        (OrderState::Processing, OrderEvent::Ship),
    ];

    for (state, event) in &states {
        let result = state_machine.fire_event(state.clone(), event.clone(), context.clone());
        println!("  {:?} + {:?} = {:?}", state, event, result);
    }

    // Try an invalid transition
    println!("\nTrying invalid transition:");
    let _ = state_machine.fire_event(OrderState::Shipped, OrderEvent::Pay, context);

    // Display collected data
    println!("\nHistory:");
    for record in state_machine.get_history() {
        println!(
            "  {:?} -> {:?} (success: {})",
            record.from, record.to, record.success
        );
    }

    println!("\nMetrics:");
    let metrics = state_machine.get_metrics();
    println!(
        "  Total: {}, Success: {}, Failed: {}",
        metrics.total_transitions, metrics.successful_transitions, metrics.failed_transitions
    );
}

pub fn external_transition(&mut self) -> ExternalTransitionBuilder<'_, S, E, C>

Start building an external transition

Examples found in repository

examples/order_example.rs (line 49)

fn basic_example() {
    println!("=== Basic State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Order {} payment initiated", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed for order {}", ctx.order_id);
        });

    let state_machine = builder.id("BasicOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-001".to_string(),
        amount: 99.99,
        customer_id: "CUST-123".to_string(),
    };

    let result = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());
    println!("Transition result: {:?}", result);
}

/// Example 2: With history tracking (requires 'history' feature)
#[cfg(feature = "history")]
fn history_example() {
    println!("\n=== History Tracking Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("HistoryOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-002".to_string(),
        amount: 149.99,
        customer_id: "CUST-456".to_string(),
    };

    // Execute multiple transitions
    let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());
    let _ = state_machine.fire_event(
        OrderState::PaymentPending,
        OrderEvent::ConfirmPayment,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);

    // Check history
    let history = state_machine.get_history();
    println!("Transition history:");
    for (i, record) in history.iter().enumerate() {
        println!(
            "  {}. {:?} -> {:?} via {:?} (success: {})",
            i + 1,
            record.from,
            record.to,
            record.event,
            record.success
        );
    }
}

/// Example 3: With entry/exit actions (requires 'extended' feature)
#[cfg(feature = "extended")]
fn extended_example() {
    println!("\n=== Extended State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .with_entry_action(OrderState::Processing, |state, ctx| {
            println!(
                "ENTRY: Starting to process order {} in state {:?}",
                ctx.order_id, state
            );
        })
        .with_exit_action(OrderState::Processing, |state, ctx| {
            println!(
                "EXIT: Finished processing order {} from state {:?}",
                ctx.order_id, state
            );
        })
        .with_entry_action(OrderState::Shipped, |_state, ctx| {
            println!("ENTRY: Order {} has been shipped!", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("ExtendedOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-003".to_string(),
        amount: 299.99,
        customer_id: "CUST-789".to_string(),
    };

    let _ = state_machine.fire_event(
        OrderState::PaymentReceived,
        OrderEvent::Process,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::Processing, OrderEvent::Ship, context);
}

/// Example 4: With metrics (requires 'metrics' feature)
#[cfg(feature = "metrics")]
fn metrics_example() {
    println!("\n=== Metrics Collection Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Add multiple transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("MetricsOrderMachine").build();

    // Simulate multiple orders
    for i in 0..10 {
        let context = OrderContext {
            order_id: format!("ORD-{:03}", i),
            amount: (i as f64) * 10.0,
            customer_id: format!("CUST-{:03}", i),
        };

        let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());

        if i % 3 == 0 {
            // Some orders get cancelled
            let _ =
                state_machine.fire_event(OrderState::PaymentPending, OrderEvent::Cancel, context);
        } else {
            // Others proceed normally
            let _ = state_machine.fire_event(
                OrderState::PaymentPending,
                OrderEvent::ConfirmPayment,
                context,
            );
        }
    }

    // Get and display metrics
    let metrics = state_machine.get_metrics();
    println!("State Machine Metrics:");
    println!("  Total transitions: {}", metrics.total_transitions);
    println!("  Successful: {}", metrics.successful_transitions);
    println!("  Failed: {}", metrics.failed_transitions);
    println!("  Success rate: {:.2}%", metrics.success_rate() * 100.0);

    if let Some(avg_time) = metrics.average_transition_time() {
        println!("  Average transition time: {:?}", avg_time);
    }

    println!("  State visit counts:");
    for (state, count) in &metrics.state_visit_counts {
        println!("    {}: {}", state, count);
    }
}

/// Example 5: With guard priorities (requires 'guards' feature)
#[cfg(feature = "guards")]
fn guards_example() {
    println!("\n=== Guard Priorities Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Multiple transitions with different priorities
    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount < 100.0)
        .with_priority(10)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing small order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 100.0 && ctx.amount < 1000.0)
        .with_priority(20)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing medium order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 1000.0)
        .with_priority(30)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing large order {} (amount: {}) - Priority handling!",
                ctx.order_id, ctx.amount
            );
        });

    let state_machine = builder.id("GuardsOrderMachine").build();

    // Test with different order amounts
    let contexts = vec![
        OrderContext {
            order_id: "ORD-SMALL".to_string(),
            amount: 50.0,
            customer_id: "C1".to_string(),
        },
        OrderContext {
            order_id: "ORD-MEDIUM".to_string(),
            amount: 500.0,
            customer_id: "C2".to_string(),
        },
        OrderContext {
            order_id: "ORD-LARGE".to_string(),
            amount: 5000.0,
            customer_id: "C3".to_string(),
        },
    ];

    for context in contexts {
        let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);
    }
}

/// Example 6: With visualization (requires 'visualization' feature)
#[cfg(feature = "visualization")]
fn visualization_example() {
    println!("\n=== Visualization Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Build a complete order flow
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Shipped)
        .to(OrderState::Delivered)
        .on(OrderEvent::Deliver)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Cancelled)
        .to(OrderState::Refunded)
        .on(OrderEvent::Refund)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("VisualOrderMachine").build();

    println!("DOT Format:");
    println!("{}", state_machine.to_dot());

    println!("\nPlantUML Format:");
    println!("{}", state_machine.to_plantuml());
}

/// Example 7: With parallel regions (requires 'parallel' feature)
#[cfg(feature = "parallel")]
fn parallel_example() {
    println!("\n=== Parallel Regions Example ===");

    // Order processing region
    let mut order_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    order_builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, ctx| {
            println!("Order region: Processing order {}", ctx.order_id);
        });

    // Payment processing region (using same states/events for simplicity)
    let mut payment_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    payment_builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!(
                "Payment region: Payment confirmed for order {}",
                ctx.order_id
            );
        });

    let mut parallel_machine = ParallelStateMachine::new();
    parallel_machine.add_region(order_builder.id("OrderRegion").build());
    parallel_machine.add_region(payment_builder.id("PaymentRegion").build());

    let context = OrderContext {
        order_id: "ORD-PARALLEL".to_string(),
        amount: 199.99,
        customer_id: "CUST-P1".to_string(),
    };

    // Fire events in parallel regions
    println!("Firing Process event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::New, OrderState::PaymentPending],
        OrderEvent::Process,
        context.clone(),
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }

    println!("Firing ConfirmPayment event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::Processing, OrderState::PaymentPending],
        OrderEvent::ConfirmPayment,
        context,
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }
}

/// Example 8: Complete example with multiple features
#[cfg(all(feature = "history", feature = "metrics", feature = "extended"))]
fn complete_example() {
    println!("\n=== Complete Example with Multiple Features ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Configure entry/exit actions
    builder
        .with_entry_action(OrderState::Processing, |_s, ctx| {
            println!("[ENTRY] Starting to process order {}", ctx.order_id);
        })
        .with_exit_action(OrderState::Processing, |_s, ctx| {
            println!("[EXIT] Finished processing order {}", ctx.order_id);
        });

    // Build transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Payment initiated for ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed: ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, ctx| {
            println!("Order {} shipped", ctx.order_id);
        });

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        println!(
            "FAILED: Cannot handle {:?} in state {:?} for order {}",
            event, state, ctx.order_id
        );
    }));

    let state_machine = builder.id("CompleteOrderMachine").build();

    // Process an order through the complete flow
    let context = OrderContext {
        order_id: "ORD-COMPLETE".to_string(),
        amount: 999.99,
        customer_id: "CUST-VIP".to_string(),
    };

    println!("\nProcessing order through complete flow:");
    let states = [
        (OrderState::New, OrderEvent::Pay),
        (OrderState::PaymentPending, OrderEvent::ConfirmPayment),
        (OrderState::PaymentReceived, OrderEvent::Process),
        (OrderState::Processing, OrderEvent::Ship),
    ];

    for (state, event) in &states {
        let result = state_machine.fire_event(state.clone(), event.clone(), context.clone());
        println!("  {:?} + {:?} = {:?}", state, event, result);
    }

    // Try an invalid transition
    println!("\nTrying invalid transition:");
    let _ = state_machine.fire_event(OrderState::Shipped, OrderEvent::Pay, context);

    // Display collected data
    println!("\nHistory:");
    for record in state_machine.get_history() {
        println!(
            "  {:?} -> {:?} (success: {})",
            record.from, record.to, record.success
        );
    }

    println!("\nMetrics:");
    let metrics = state_machine.get_metrics();
    println!(
        "  Total: {}, Success: {}, Failed: {}",
        metrics.total_transitions, metrics.successful_transitions, metrics.failed_transitions
    );
}

examples/traffic_light_example.rs (line 77)

fn configure_basic_transitions<'a>(
    builder: &'a mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) -> &'a mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext> {
    // Normal traffic light cycle
    builder
        .external_transition()
        .from(TrafficLightState::Green)
        .to(TrafficLightState::Yellow)
        .on(TrafficLightEvent::Timer)
        .perform(|_s, _e, ctx| {
            println!("[{}] Changing to YELLOW", ctx.intersection_id);
        });

    builder
        .external_transition()
        .from(TrafficLightState::Yellow)
        .to(TrafficLightState::Red)
        .on(TrafficLightEvent::Timer)
        .perform(|_s, _e, ctx| {
            println!("[{}] Changing to RED", ctx.intersection_id);
        });

    builder
        .external_transition()
        .from(TrafficLightState::Red)
        .to(TrafficLightState::Green)
        .on(TrafficLightEvent::Timer)
        .when(|_s, _e, ctx| !ctx.emergency_active)
        .perform(|_s, _e, ctx| {
            println!("[{}] Changing to GREEN", ctx.intersection_id);
        });

    // Emergency vehicle handling
    builder
        .external_transitions()
        .from_among(vec![
            TrafficLightState::Green,
            TrafficLightState::Yellow,
            TrafficLightState::Red,
        ])
        .to(TrafficLightState::Emergency)
        .on(TrafficLightEvent::EmergencyVehicleDetected)
        .perform(|from, _e, ctx| {
            println!(
                "[{}] EMERGENCY MODE! Was in {:?}",
                ctx.intersection_id, from
            );
        });

    builder
        .external_transition()
        .from(TrafficLightState::Emergency)
        .to(TrafficLightState::Red)
        .on(TrafficLightEvent::EmergencyCleared)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] Emergency cleared, returning to RED",
                ctx.intersection_id
            );
        });

    // Maintenance mode
    builder
        .external_transitions()
        .from_among(vec![
            TrafficLightState::Green,
            TrafficLightState::Yellow,
            TrafficLightState::Red,
        ])
        .to(TrafficLightState::FlashingYellow)
        .on(TrafficLightEvent::MaintenanceMode)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] Entering maintenance mode - FLASHING YELLOW",
                ctx.intersection_id
            );
        });

    builder
        .external_transition()
        .from(TrafficLightState::FlashingYellow)
        .to(TrafficLightState::Red)
        .on(TrafficLightEvent::NormalMode)
        .perform(|_s, _e, ctx| {
            println!("[{}] Exiting maintenance mode", ctx.intersection_id);
        });

    builder
}

/// Configure entry and exit actions for states
#[cfg(feature = "extended")]
fn configure_entry_exit_actions(
    builder: &mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) {
    // Entry actions
    builder.with_entry_action(TrafficLightState::Green, |_state, ctx| {
        println!(
            "[{}] GREEN light ON - Vehicles may proceed",
            ctx.intersection_id
        );
        // In a real system, this would control the actual light hardware
    });

    builder.with_entry_action(TrafficLightState::Yellow, |_state, ctx| {
        println!(
            "[{}] YELLOW light ON - Prepare to stop",
            ctx.intersection_id
        );
    });

    builder.with_entry_action(TrafficLightState::Red, |_state, ctx| {
        println!(
            "[{}] RED light ON - Vehicles must stop",
            ctx.intersection_id
        );
        if ctx.pedestrian_waiting {
            println!(
                "[{}] Pedestrian crossing signal activated",
                ctx.intersection_id
            );
        }
    });

    builder.with_entry_action(TrafficLightState::Emergency, |_state, ctx| {
        println!(
            "[{}] EMERGENCY MODE - All lights RED except emergency route",
            ctx.intersection_id
        );
        // Would trigger emergency protocols in real system
    });

    // Exit actions
    builder.with_exit_action(TrafficLightState::Green, |_state, ctx| {
        println!("[{}] GREEN light OFF", ctx.intersection_id);
    });

    builder.with_exit_action(TrafficLightState::Emergency, |_state, ctx| {
        println!("[{}] Exiting emergency mode", ctx.intersection_id);
    });
}

/// Configure priority-based transitions for complex scenarios
#[cfg(feature = "guards")]
fn configure_priority_transitions(
    builder: &mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) {
    // High-priority pedestrian crossing during low traffic
    builder
        .external_transition()
        .from(TrafficLightState::Green)
        .to(TrafficLightState::Yellow)
        .on(TrafficLightEvent::PedestrianRequest)
        .when(|_s, _e, ctx| ctx.traffic_density < 0.3 && ctx.pedestrian_waiting)
        .with_priority(100)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] Pedestrian priority - changing to yellow",
                ctx.intersection_id
            );
        });

    // Normal pedestrian request
    builder
        .external_transition()
        .from(TrafficLightState::Green)
        .to(TrafficLightState::Yellow)
        .on(TrafficLightEvent::PedestrianRequest)
        .when(|_s, _e, ctx| {
            ctx.pedestrian_waiting && ctx.time_in_state > std::time::Duration::from_secs(10)
        })
        .with_priority(50)
        .perform(|_s, _e, ctx| {
            println!("[{}] Pedestrian request accepted", ctx.intersection_id);
        });

    // Rush hour handling - extend green time
    builder
        .internal_transition()
        .within(TrafficLightState::Green)
        .on(TrafficLightEvent::Timer)
        .when(|_s, _e, ctx| {
            ctx.traffic_density > 0.8 && ctx.time_in_state < std::time::Duration::from_secs(90)
        })
        .with_priority(200)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] High traffic - extending green phase",
                ctx.intersection_id
            );
        });
}

pub fn internal_transition(&mut self) -> InternalTransitionBuilder<'_, S, E, C>

Start building an internal transition

Examples found in repository

examples/traffic_light_example.rs (line 250)

fn configure_priority_transitions(
    builder: &mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) {
    // High-priority pedestrian crossing during low traffic
    builder
        .external_transition()
        .from(TrafficLightState::Green)
        .to(TrafficLightState::Yellow)
        .on(TrafficLightEvent::PedestrianRequest)
        .when(|_s, _e, ctx| ctx.traffic_density < 0.3 && ctx.pedestrian_waiting)
        .with_priority(100)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] Pedestrian priority - changing to yellow",
                ctx.intersection_id
            );
        });

    // Normal pedestrian request
    builder
        .external_transition()
        .from(TrafficLightState::Green)
        .to(TrafficLightState::Yellow)
        .on(TrafficLightEvent::PedestrianRequest)
        .when(|_s, _e, ctx| {
            ctx.pedestrian_waiting && ctx.time_in_state > std::time::Duration::from_secs(10)
        })
        .with_priority(50)
        .perform(|_s, _e, ctx| {
            println!("[{}] Pedestrian request accepted", ctx.intersection_id);
        });

    // Rush hour handling - extend green time
    builder
        .internal_transition()
        .within(TrafficLightState::Green)
        .on(TrafficLightEvent::Timer)
        .when(|_s, _e, ctx| {
            ctx.traffic_density > 0.8 && ctx.time_in_state < std::time::Duration::from_secs(90)
        })
        .with_priority(200)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] High traffic - extending green phase",
                ctx.intersection_id
            );
        });
}

pub fn external_transitions( &mut self, ) -> ExternalTransitionsBuilder<'_, S, E, C>

Start building external transitions from multiple states

Examples found in repository

examples/order_example.rs (line 216)

fn metrics_example() {
    println!("\n=== Metrics Collection Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Add multiple transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("MetricsOrderMachine").build();

    // Simulate multiple orders
    for i in 0..10 {
        let context = OrderContext {
            order_id: format!("ORD-{:03}", i),
            amount: (i as f64) * 10.0,
            customer_id: format!("CUST-{:03}", i),
        };

        let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());

        if i % 3 == 0 {
            // Some orders get cancelled
            let _ =
                state_machine.fire_event(OrderState::PaymentPending, OrderEvent::Cancel, context);
        } else {
            // Others proceed normally
            let _ = state_machine.fire_event(
                OrderState::PaymentPending,
                OrderEvent::ConfirmPayment,
                context,
            );
        }
    }

    // Get and display metrics
    let metrics = state_machine.get_metrics();
    println!("State Machine Metrics:");
    println!("  Total transitions: {}", metrics.total_transitions);
    println!("  Successful: {}", metrics.successful_transitions);
    println!("  Failed: {}", metrics.failed_transitions);
    println!("  Success rate: {:.2}%", metrics.success_rate() * 100.0);

    if let Some(avg_time) = metrics.average_transition_time() {
        println!("  Average transition time: {:?}", avg_time);
    }

    println!("  State visit counts:");
    for (state, count) in &metrics.state_visit_counts {
        println!("    {}: {}", state, count);
    }
}

/// Example 5: With guard priorities (requires 'guards' feature)
#[cfg(feature = "guards")]
fn guards_example() {
    println!("\n=== Guard Priorities Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Multiple transitions with different priorities
    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount < 100.0)
        .with_priority(10)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing small order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 100.0 && ctx.amount < 1000.0)
        .with_priority(20)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing medium order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 1000.0)
        .with_priority(30)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing large order {} (amount: {}) - Priority handling!",
                ctx.order_id, ctx.amount
            );
        });

    let state_machine = builder.id("GuardsOrderMachine").build();

    // Test with different order amounts
    let contexts = vec![
        OrderContext {
            order_id: "ORD-SMALL".to_string(),
            amount: 50.0,
            customer_id: "C1".to_string(),
        },
        OrderContext {
            order_id: "ORD-MEDIUM".to_string(),
            amount: 500.0,
            customer_id: "C2".to_string(),
        },
        OrderContext {
            order_id: "ORD-LARGE".to_string(),
            amount: 5000.0,
            customer_id: "C3".to_string(),
        },
    ];

    for context in contexts {
        let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);
    }
}

/// Example 6: With visualization (requires 'visualization' feature)
#[cfg(feature = "visualization")]
fn visualization_example() {
    println!("\n=== Visualization Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Build a complete order flow
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Shipped)
        .to(OrderState::Delivered)
        .on(OrderEvent::Deliver)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Cancelled)
        .to(OrderState::Refunded)
        .on(OrderEvent::Refund)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("VisualOrderMachine").build();

    println!("DOT Format:");
    println!("{}", state_machine.to_dot());

    println!("\nPlantUML Format:");
    println!("{}", state_machine.to_plantuml());
}

examples/traffic_light_example.rs (line 106)

fn configure_basic_transitions<'a>(
    builder: &'a mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) -> &'a mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext> {
    // Normal traffic light cycle
    builder
        .external_transition()
        .from(TrafficLightState::Green)
        .to(TrafficLightState::Yellow)
        .on(TrafficLightEvent::Timer)
        .perform(|_s, _e, ctx| {
            println!("[{}] Changing to YELLOW", ctx.intersection_id);
        });

    builder
        .external_transition()
        .from(TrafficLightState::Yellow)
        .to(TrafficLightState::Red)
        .on(TrafficLightEvent::Timer)
        .perform(|_s, _e, ctx| {
            println!("[{}] Changing to RED", ctx.intersection_id);
        });

    builder
        .external_transition()
        .from(TrafficLightState::Red)
        .to(TrafficLightState::Green)
        .on(TrafficLightEvent::Timer)
        .when(|_s, _e, ctx| !ctx.emergency_active)
        .perform(|_s, _e, ctx| {
            println!("[{}] Changing to GREEN", ctx.intersection_id);
        });

    // Emergency vehicle handling
    builder
        .external_transitions()
        .from_among(vec![
            TrafficLightState::Green,
            TrafficLightState::Yellow,
            TrafficLightState::Red,
        ])
        .to(TrafficLightState::Emergency)
        .on(TrafficLightEvent::EmergencyVehicleDetected)
        .perform(|from, _e, ctx| {
            println!(
                "[{}] EMERGENCY MODE! Was in {:?}",
                ctx.intersection_id, from
            );
        });

    builder
        .external_transition()
        .from(TrafficLightState::Emergency)
        .to(TrafficLightState::Red)
        .on(TrafficLightEvent::EmergencyCleared)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] Emergency cleared, returning to RED",
                ctx.intersection_id
            );
        });

    // Maintenance mode
    builder
        .external_transitions()
        .from_among(vec![
            TrafficLightState::Green,
            TrafficLightState::Yellow,
            TrafficLightState::Red,
        ])
        .to(TrafficLightState::FlashingYellow)
        .on(TrafficLightEvent::MaintenanceMode)
        .perform(|_s, _e, ctx| {
            println!(
                "[{}] Entering maintenance mode - FLASHING YELLOW",
                ctx.intersection_id
            );
        });

    builder
        .external_transition()
        .from(TrafficLightState::FlashingYellow)
        .to(TrafficLightState::Red)
        .on(TrafficLightEvent::NormalMode)
        .perform(|_s, _e, ctx| {
            println!("[{}] Exiting maintenance mode", ctx.intersection_id);
        });

    builder
}

pub fn set_fail_callback( &mut self, callback: FailCallback<S, E, C>, ) -> &mut Self

Set fail callback

Examples found in repository

examples/traffic_light_example.rs (lines 62-67)

pub fn build_traffic_light_system(
) -> StateMachine<TrafficLightState, TrafficLightEvent, TrafficContext> {
    let mut builder =
        StateMachineBuilderFactory::create::<TrafficLightState, TrafficLightEvent, TrafficContext>(
        );

    // Configure the state machine based on available features
    configure_basic_transitions(&mut builder);

    #[cfg(feature = "extended")]
    configure_entry_exit_actions(&mut builder);

    #[cfg(feature = "guards")]
    configure_priority_transitions(&mut builder);

    #[cfg(feature = "timeout")]
    configure_timeouts(&mut builder);

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        eprintln!(
            "WARNING: Invalid transition from {:?} with {:?} at intersection {}",
            state, event, ctx.intersection_id
        );
    }));
    builder.id("TrafficLightController").build()
}

examples/order_example.rs (lines 534-539)

fn complete_example() {
    println!("\n=== Complete Example with Multiple Features ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Configure entry/exit actions
    builder
        .with_entry_action(OrderState::Processing, |_s, ctx| {
            println!("[ENTRY] Starting to process order {}", ctx.order_id);
        })
        .with_exit_action(OrderState::Processing, |_s, ctx| {
            println!("[EXIT] Finished processing order {}", ctx.order_id);
        });

    // Build transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Payment initiated for ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed: ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, ctx| {
            println!("Order {} shipped", ctx.order_id);
        });

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        println!(
            "FAILED: Cannot handle {:?} in state {:?} for order {}",
            event, state, ctx.order_id
        );
    }));

    let state_machine = builder.id("CompleteOrderMachine").build();

    // Process an order through the complete flow
    let context = OrderContext {
        order_id: "ORD-COMPLETE".to_string(),
        amount: 999.99,
        customer_id: "CUST-VIP".to_string(),
    };

    println!("\nProcessing order through complete flow:");
    let states = [
        (OrderState::New, OrderEvent::Pay),
        (OrderState::PaymentPending, OrderEvent::ConfirmPayment),
        (OrderState::PaymentReceived, OrderEvent::Process),
        (OrderState::Processing, OrderEvent::Ship),
    ];

    for (state, event) in &states {
        let result = state_machine.fire_event(state.clone(), event.clone(), context.clone());
        println!("  {:?} + {:?} = {:?}", state, event, result);
    }

    // Try an invalid transition
    println!("\nTrying invalid transition:");
    let _ = state_machine.fire_event(OrderState::Shipped, OrderEvent::Pay, context);

    // Display collected data
    println!("\nHistory:");
    for record in state_machine.get_history() {
        println!(
            "  {:?} -> {:?} (success: {})",
            record.from, record.to, record.success
        );
    }

    println!("\nMetrics:");
    let metrics = state_machine.get_metrics();
    println!(
        "  Total: {}, Success: {}, Failed: {}",
        metrics.total_transitions, metrics.successful_transitions, metrics.failed_transitions
    );
}

pub fn with_entry_action<F>(&mut self, state: S, action: F) -> &mut Self

where F: Fn(&S, &C) + Send + Sync + 'static,

Add entry action for a state

Examples found in repository

examples/traffic_light_example.rs (lines 168-174)

fn configure_entry_exit_actions(
    builder: &mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) {
    // Entry actions
    builder.with_entry_action(TrafficLightState::Green, |_state, ctx| {
        println!(
            "[{}] GREEN light ON - Vehicles may proceed",
            ctx.intersection_id
        );
        // In a real system, this would control the actual light hardware
    });

    builder.with_entry_action(TrafficLightState::Yellow, |_state, ctx| {
        println!(
            "[{}] YELLOW light ON - Prepare to stop",
            ctx.intersection_id
        );
    });

    builder.with_entry_action(TrafficLightState::Red, |_state, ctx| {
        println!(
            "[{}] RED light ON - Vehicles must stop",
            ctx.intersection_id
        );
        if ctx.pedestrian_waiting {
            println!(
                "[{}] Pedestrian crossing signal activated",
                ctx.intersection_id
            );
        }
    });

    builder.with_entry_action(TrafficLightState::Emergency, |_state, ctx| {
        println!(
            "[{}] EMERGENCY MODE - All lights RED except emergency route",
            ctx.intersection_id
        );
        // Would trigger emergency protocols in real system
    });

    // Exit actions
    builder.with_exit_action(TrafficLightState::Green, |_state, ctx| {
        println!("[{}] GREEN light OFF", ctx.intersection_id);
    });

    builder.with_exit_action(TrafficLightState::Emergency, |_state, ctx| {
        println!("[{}] Exiting emergency mode", ctx.intersection_id);
    });
}

examples/order_example.rs (lines 146-151)

fn extended_example() {
    println!("\n=== Extended State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .with_entry_action(OrderState::Processing, |state, ctx| {
            println!(
                "ENTRY: Starting to process order {} in state {:?}",
                ctx.order_id, state
            );
        })
        .with_exit_action(OrderState::Processing, |state, ctx| {
            println!(
                "EXIT: Finished processing order {} from state {:?}",
                ctx.order_id, state
            );
        })
        .with_entry_action(OrderState::Shipped, |_state, ctx| {
            println!("ENTRY: Order {} has been shipped!", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("ExtendedOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-003".to_string(),
        amount: 299.99,
        customer_id: "CUST-789".to_string(),
    };

    let _ = state_machine.fire_event(
        OrderState::PaymentReceived,
        OrderEvent::Process,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::Processing, OrderEvent::Ship, context);
}

/// Example 4: With metrics (requires 'metrics' feature)
#[cfg(feature = "metrics")]
fn metrics_example() {
    println!("\n=== Metrics Collection Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Add multiple transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("MetricsOrderMachine").build();

    // Simulate multiple orders
    for i in 0..10 {
        let context = OrderContext {
            order_id: format!("ORD-{:03}", i),
            amount: (i as f64) * 10.0,
            customer_id: format!("CUST-{:03}", i),
        };

        let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());

        if i % 3 == 0 {
            // Some orders get cancelled
            let _ =
                state_machine.fire_event(OrderState::PaymentPending, OrderEvent::Cancel, context);
        } else {
            // Others proceed normally
            let _ = state_machine.fire_event(
                OrderState::PaymentPending,
                OrderEvent::ConfirmPayment,
                context,
            );
        }
    }

    // Get and display metrics
    let metrics = state_machine.get_metrics();
    println!("State Machine Metrics:");
    println!("  Total transitions: {}", metrics.total_transitions);
    println!("  Successful: {}", metrics.successful_transitions);
    println!("  Failed: {}", metrics.failed_transitions);
    println!("  Success rate: {:.2}%", metrics.success_rate() * 100.0);

    if let Some(avg_time) = metrics.average_transition_time() {
        println!("  Average transition time: {:?}", avg_time);
    }

    println!("  State visit counts:");
    for (state, count) in &metrics.state_visit_counts {
        println!("    {}: {}", state, count);
    }
}

/// Example 5: With guard priorities (requires 'guards' feature)
#[cfg(feature = "guards")]
fn guards_example() {
    println!("\n=== Guard Priorities Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Multiple transitions with different priorities
    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount < 100.0)
        .with_priority(10)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing small order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 100.0 && ctx.amount < 1000.0)
        .with_priority(20)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing medium order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 1000.0)
        .with_priority(30)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing large order {} (amount: {}) - Priority handling!",
                ctx.order_id, ctx.amount
            );
        });

    let state_machine = builder.id("GuardsOrderMachine").build();

    // Test with different order amounts
    let contexts = vec![
        OrderContext {
            order_id: "ORD-SMALL".to_string(),
            amount: 50.0,
            customer_id: "C1".to_string(),
        },
        OrderContext {
            order_id: "ORD-MEDIUM".to_string(),
            amount: 500.0,
            customer_id: "C2".to_string(),
        },
        OrderContext {
            order_id: "ORD-LARGE".to_string(),
            amount: 5000.0,
            customer_id: "C3".to_string(),
        },
    ];

    for context in contexts {
        let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);
    }
}

/// Example 6: With visualization (requires 'visualization' feature)
#[cfg(feature = "visualization")]
fn visualization_example() {
    println!("\n=== Visualization Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Build a complete order flow
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Shipped)
        .to(OrderState::Delivered)
        .on(OrderEvent::Deliver)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Cancelled)
        .to(OrderState::Refunded)
        .on(OrderEvent::Refund)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("VisualOrderMachine").build();

    println!("DOT Format:");
    println!("{}", state_machine.to_dot());

    println!("\nPlantUML Format:");
    println!("{}", state_machine.to_plantuml());
}

/// Example 7: With parallel regions (requires 'parallel' feature)
#[cfg(feature = "parallel")]
fn parallel_example() {
    println!("\n=== Parallel Regions Example ===");

    // Order processing region
    let mut order_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    order_builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, ctx| {
            println!("Order region: Processing order {}", ctx.order_id);
        });

    // Payment processing region (using same states/events for simplicity)
    let mut payment_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    payment_builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!(
                "Payment region: Payment confirmed for order {}",
                ctx.order_id
            );
        });

    let mut parallel_machine = ParallelStateMachine::new();
    parallel_machine.add_region(order_builder.id("OrderRegion").build());
    parallel_machine.add_region(payment_builder.id("PaymentRegion").build());

    let context = OrderContext {
        order_id: "ORD-PARALLEL".to_string(),
        amount: 199.99,
        customer_id: "CUST-P1".to_string(),
    };

    // Fire events in parallel regions
    println!("Firing Process event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::New, OrderState::PaymentPending],
        OrderEvent::Process,
        context.clone(),
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }

    println!("Firing ConfirmPayment event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::Processing, OrderState::PaymentPending],
        OrderEvent::ConfirmPayment,
        context,
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }
}

/// Example 8: Complete example with multiple features
#[cfg(all(feature = "history", feature = "metrics", feature = "extended"))]
fn complete_example() {
    println!("\n=== Complete Example with Multiple Features ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Configure entry/exit actions
    builder
        .with_entry_action(OrderState::Processing, |_s, ctx| {
            println!("[ENTRY] Starting to process order {}", ctx.order_id);
        })
        .with_exit_action(OrderState::Processing, |_s, ctx| {
            println!("[EXIT] Finished processing order {}", ctx.order_id);
        });

    // Build transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Payment initiated for ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed: ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, ctx| {
            println!("Order {} shipped", ctx.order_id);
        });

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        println!(
            "FAILED: Cannot handle {:?} in state {:?} for order {}",
            event, state, ctx.order_id
        );
    }));

    let state_machine = builder.id("CompleteOrderMachine").build();

    // Process an order through the complete flow
    let context = OrderContext {
        order_id: "ORD-COMPLETE".to_string(),
        amount: 999.99,
        customer_id: "CUST-VIP".to_string(),
    };

    println!("\nProcessing order through complete flow:");
    let states = [
        (OrderState::New, OrderEvent::Pay),
        (OrderState::PaymentPending, OrderEvent::ConfirmPayment),
        (OrderState::PaymentReceived, OrderEvent::Process),
        (OrderState::Processing, OrderEvent::Ship),
    ];

    for (state, event) in &states {
        let result = state_machine.fire_event(state.clone(), event.clone(), context.clone());
        println!("  {:?} + {:?} = {:?}", state, event, result);
    }

    // Try an invalid transition
    println!("\nTrying invalid transition:");
    let _ = state_machine.fire_event(OrderState::Shipped, OrderEvent::Pay, context);

    // Display collected data
    println!("\nHistory:");
    for record in state_machine.get_history() {
        println!(
            "  {:?} -> {:?} (success: {})",
            record.from, record.to, record.success
        );
    }

    println!("\nMetrics:");
    let metrics = state_machine.get_metrics();
    println!(
        "  Total: {}, Success: {}, Failed: {}",
        metrics.total_transitions, metrics.successful_transitions, metrics.failed_transitions
    );
}

pub fn with_exit_action<F>(&mut self, state: S, action: F) -> &mut Self

where F: Fn(&S, &C) + Send + Sync + 'static,

Add exit action for a state

Examples found in repository

examples/traffic_light_example.rs (lines 205-207)

fn configure_entry_exit_actions(
    builder: &mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) {
    // Entry actions
    builder.with_entry_action(TrafficLightState::Green, |_state, ctx| {
        println!(
            "[{}] GREEN light ON - Vehicles may proceed",
            ctx.intersection_id
        );
        // In a real system, this would control the actual light hardware
    });

    builder.with_entry_action(TrafficLightState::Yellow, |_state, ctx| {
        println!(
            "[{}] YELLOW light ON - Prepare to stop",
            ctx.intersection_id
        );
    });

    builder.with_entry_action(TrafficLightState::Red, |_state, ctx| {
        println!(
            "[{}] RED light ON - Vehicles must stop",
            ctx.intersection_id
        );
        if ctx.pedestrian_waiting {
            println!(
                "[{}] Pedestrian crossing signal activated",
                ctx.intersection_id
            );
        }
    });

    builder.with_entry_action(TrafficLightState::Emergency, |_state, ctx| {
        println!(
            "[{}] EMERGENCY MODE - All lights RED except emergency route",
            ctx.intersection_id
        );
        // Would trigger emergency protocols in real system
    });

    // Exit actions
    builder.with_exit_action(TrafficLightState::Green, |_state, ctx| {
        println!("[{}] GREEN light OFF", ctx.intersection_id);
    });

    builder.with_exit_action(TrafficLightState::Emergency, |_state, ctx| {
        println!("[{}] Exiting emergency mode", ctx.intersection_id);
    });
}

examples/order_example.rs (lines 152-157)

fn extended_example() {
    println!("\n=== Extended State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .with_entry_action(OrderState::Processing, |state, ctx| {
            println!(
                "ENTRY: Starting to process order {} in state {:?}",
                ctx.order_id, state
            );
        })
        .with_exit_action(OrderState::Processing, |state, ctx| {
            println!(
                "EXIT: Finished processing order {} from state {:?}",
                ctx.order_id, state
            );
        })
        .with_entry_action(OrderState::Shipped, |_state, ctx| {
            println!("ENTRY: Order {} has been shipped!", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("ExtendedOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-003".to_string(),
        amount: 299.99,
        customer_id: "CUST-789".to_string(),
    };

    let _ = state_machine.fire_event(
        OrderState::PaymentReceived,
        OrderEvent::Process,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::Processing, OrderEvent::Ship, context);
}

/// Example 4: With metrics (requires 'metrics' feature)
#[cfg(feature = "metrics")]
fn metrics_example() {
    println!("\n=== Metrics Collection Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Add multiple transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("MetricsOrderMachine").build();

    // Simulate multiple orders
    for i in 0..10 {
        let context = OrderContext {
            order_id: format!("ORD-{:03}", i),
            amount: (i as f64) * 10.0,
            customer_id: format!("CUST-{:03}", i),
        };

        let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());

        if i % 3 == 0 {
            // Some orders get cancelled
            let _ =
                state_machine.fire_event(OrderState::PaymentPending, OrderEvent::Cancel, context);
        } else {
            // Others proceed normally
            let _ = state_machine.fire_event(
                OrderState::PaymentPending,
                OrderEvent::ConfirmPayment,
                context,
            );
        }
    }

    // Get and display metrics
    let metrics = state_machine.get_metrics();
    println!("State Machine Metrics:");
    println!("  Total transitions: {}", metrics.total_transitions);
    println!("  Successful: {}", metrics.successful_transitions);
    println!("  Failed: {}", metrics.failed_transitions);
    println!("  Success rate: {:.2}%", metrics.success_rate() * 100.0);

    if let Some(avg_time) = metrics.average_transition_time() {
        println!("  Average transition time: {:?}", avg_time);
    }

    println!("  State visit counts:");
    for (state, count) in &metrics.state_visit_counts {
        println!("    {}: {}", state, count);
    }
}

/// Example 5: With guard priorities (requires 'guards' feature)
#[cfg(feature = "guards")]
fn guards_example() {
    println!("\n=== Guard Priorities Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Multiple transitions with different priorities
    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount < 100.0)
        .with_priority(10)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing small order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 100.0 && ctx.amount < 1000.0)
        .with_priority(20)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing medium order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 1000.0)
        .with_priority(30)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing large order {} (amount: {}) - Priority handling!",
                ctx.order_id, ctx.amount
            );
        });

    let state_machine = builder.id("GuardsOrderMachine").build();

    // Test with different order amounts
    let contexts = vec![
        OrderContext {
            order_id: "ORD-SMALL".to_string(),
            amount: 50.0,
            customer_id: "C1".to_string(),
        },
        OrderContext {
            order_id: "ORD-MEDIUM".to_string(),
            amount: 500.0,
            customer_id: "C2".to_string(),
        },
        OrderContext {
            order_id: "ORD-LARGE".to_string(),
            amount: 5000.0,
            customer_id: "C3".to_string(),
        },
    ];

    for context in contexts {
        let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);
    }
}

/// Example 6: With visualization (requires 'visualization' feature)
#[cfg(feature = "visualization")]
fn visualization_example() {
    println!("\n=== Visualization Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Build a complete order flow
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Shipped)
        .to(OrderState::Delivered)
        .on(OrderEvent::Deliver)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Cancelled)
        .to(OrderState::Refunded)
        .on(OrderEvent::Refund)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("VisualOrderMachine").build();

    println!("DOT Format:");
    println!("{}", state_machine.to_dot());

    println!("\nPlantUML Format:");
    println!("{}", state_machine.to_plantuml());
}

/// Example 7: With parallel regions (requires 'parallel' feature)
#[cfg(feature = "parallel")]
fn parallel_example() {
    println!("\n=== Parallel Regions Example ===");

    // Order processing region
    let mut order_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    order_builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, ctx| {
            println!("Order region: Processing order {}", ctx.order_id);
        });

    // Payment processing region (using same states/events for simplicity)
    let mut payment_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    payment_builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!(
                "Payment region: Payment confirmed for order {}",
                ctx.order_id
            );
        });

    let mut parallel_machine = ParallelStateMachine::new();
    parallel_machine.add_region(order_builder.id("OrderRegion").build());
    parallel_machine.add_region(payment_builder.id("PaymentRegion").build());

    let context = OrderContext {
        order_id: "ORD-PARALLEL".to_string(),
        amount: 199.99,
        customer_id: "CUST-P1".to_string(),
    };

    // Fire events in parallel regions
    println!("Firing Process event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::New, OrderState::PaymentPending],
        OrderEvent::Process,
        context.clone(),
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }

    println!("Firing ConfirmPayment event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::Processing, OrderState::PaymentPending],
        OrderEvent::ConfirmPayment,
        context,
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }
}

/// Example 8: Complete example with multiple features
#[cfg(all(feature = "history", feature = "metrics", feature = "extended"))]
fn complete_example() {
    println!("\n=== Complete Example with Multiple Features ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Configure entry/exit actions
    builder
        .with_entry_action(OrderState::Processing, |_s, ctx| {
            println!("[ENTRY] Starting to process order {}", ctx.order_id);
        })
        .with_exit_action(OrderState::Processing, |_s, ctx| {
            println!("[EXIT] Finished processing order {}", ctx.order_id);
        });

    // Build transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Payment initiated for ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed: ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, ctx| {
            println!("Order {} shipped", ctx.order_id);
        });

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        println!(
            "FAILED: Cannot handle {:?} in state {:?} for order {}",
            event, state, ctx.order_id
        );
    }));

    let state_machine = builder.id("CompleteOrderMachine").build();

    // Process an order through the complete flow
    let context = OrderContext {
        order_id: "ORD-COMPLETE".to_string(),
        amount: 999.99,
        customer_id: "CUST-VIP".to_string(),
    };

    println!("\nProcessing order through complete flow:");
    let states = [
        (OrderState::New, OrderEvent::Pay),
        (OrderState::PaymentPending, OrderEvent::ConfirmPayment),
        (OrderState::PaymentReceived, OrderEvent::Process),
        (OrderState::Processing, OrderEvent::Ship),
    ];

    for (state, event) in &states {
        let result = state_machine.fire_event(state.clone(), event.clone(), context.clone());
        println!("  {:?} + {:?} = {:?}", state, event, result);
    }

    // Try an invalid transition
    println!("\nTrying invalid transition:");
    let _ = state_machine.fire_event(OrderState::Shipped, OrderEvent::Pay, context);

    // Display collected data
    println!("\nHistory:");
    for record in state_machine.get_history() {
        println!(
            "  {:?} -> {:?} (success: {})",
            record.from, record.to, record.success
        );
    }

    println!("\nMetrics:");
    let metrics = state_machine.get_metrics();
    println!(
        "  Total: {}, Success: {}, Failed: {}",
        metrics.total_transitions, metrics.successful_transitions, metrics.failed_transitions
    );
}

pub fn with_state_timeout( &mut self, state: S, duration: Duration, target_state: S, timeout_event: E, ) -> &mut Self

Set timeout for a state

Examples found in repository

examples/traffic_light_example.rs (lines 273-278)

fn configure_timeouts(
    builder: &mut StateMachineBuilder<TrafficLightState, TrafficLightEvent, TrafficContext>,
) {
    use std::time::Duration;

    // Safety timeout - Yellow shouldn't last too long
    builder.with_state_timeout(
        TrafficLightState::Yellow,
        Duration::from_secs(5),
        TrafficLightState::Red,
        TrafficLightEvent::Timer,
    );

    // Emergency timeout - Auto-clear if no manual clear
    builder.with_state_timeout(
        TrafficLightState::Emergency,
        Duration::from_secs(300), // 5 minutes
        TrafficLightState::Red,
        TrafficLightEvent::EmergencyCleared,
    );
}

pub fn build(self) -> StateMachine<S, E, C>

Build the state machine

Examples found in repository

examples/traffic_light_example.rs (line 68)

pub fn build_traffic_light_system(
) -> StateMachine<TrafficLightState, TrafficLightEvent, TrafficContext> {
    let mut builder =
        StateMachineBuilderFactory::create::<TrafficLightState, TrafficLightEvent, TrafficContext>(
        );

    // Configure the state machine based on available features
    configure_basic_transitions(&mut builder);

    #[cfg(feature = "extended")]
    configure_entry_exit_actions(&mut builder);

    #[cfg(feature = "guards")]
    configure_priority_transitions(&mut builder);

    #[cfg(feature = "timeout")]
    configure_timeouts(&mut builder);

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        eprintln!(
            "WARNING: Invalid transition from {:?} with {:?} at intersection {}",
            state, event, ctx.intersection_id
        );
    }));
    builder.id("TrafficLightController").build()
}

examples/order_example.rs (line 66)

fn basic_example() {
    println!("=== Basic State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Order {} payment initiated", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed for order {}", ctx.order_id);
        });

    let state_machine = builder.id("BasicOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-001".to_string(),
        amount: 99.99,
        customer_id: "CUST-123".to_string(),
    };

    let result = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());
    println!("Transition result: {:?}", result);
}

/// Example 2: With history tracking (requires 'history' feature)
#[cfg(feature = "history")]
fn history_example() {
    println!("\n=== History Tracking Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("HistoryOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-002".to_string(),
        amount: 149.99,
        customer_id: "CUST-456".to_string(),
    };

    // Execute multiple transitions
    let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());
    let _ = state_machine.fire_event(
        OrderState::PaymentPending,
        OrderEvent::ConfirmPayment,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);

    // Check history
    let history = state_machine.get_history();
    println!("Transition history:");
    for (i, record) in history.iter().enumerate() {
        println!(
            "  {}. {:?} -> {:?} via {:?} (success: {})",
            i + 1,
            record.from,
            record.to,
            record.event,
            record.success
        );
    }
}

/// Example 3: With entry/exit actions (requires 'extended' feature)
#[cfg(feature = "extended")]
fn extended_example() {
    println!("\n=== Extended State Machine Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    builder
        .with_entry_action(OrderState::Processing, |state, ctx| {
            println!(
                "ENTRY: Starting to process order {} in state {:?}",
                ctx.order_id, state
            );
        })
        .with_exit_action(OrderState::Processing, |state, ctx| {
            println!(
                "EXIT: Finished processing order {} from state {:?}",
                ctx.order_id, state
            );
        })
        .with_entry_action(OrderState::Shipped, |_state, ctx| {
            println!("ENTRY: Order {} has been shipped!", ctx.order_id);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("ExtendedOrderMachine").build();

    let context = OrderContext {
        order_id: "ORD-003".to_string(),
        amount: 299.99,
        customer_id: "CUST-789".to_string(),
    };

    let _ = state_machine.fire_event(
        OrderState::PaymentReceived,
        OrderEvent::Process,
        context.clone(),
    );
    let _ = state_machine.fire_event(OrderState::Processing, OrderEvent::Ship, context);
}

/// Example 4: With metrics (requires 'metrics' feature)
#[cfg(feature = "metrics")]
fn metrics_example() {
    println!("\n=== Metrics Collection Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Add multiple transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("MetricsOrderMachine").build();

    // Simulate multiple orders
    for i in 0..10 {
        let context = OrderContext {
            order_id: format!("ORD-{:03}", i),
            amount: (i as f64) * 10.0,
            customer_id: format!("CUST-{:03}", i),
        };

        let _ = state_machine.fire_event(OrderState::New, OrderEvent::Pay, context.clone());

        if i % 3 == 0 {
            // Some orders get cancelled
            let _ =
                state_machine.fire_event(OrderState::PaymentPending, OrderEvent::Cancel, context);
        } else {
            // Others proceed normally
            let _ = state_machine.fire_event(
                OrderState::PaymentPending,
                OrderEvent::ConfirmPayment,
                context,
            );
        }
    }

    // Get and display metrics
    let metrics = state_machine.get_metrics();
    println!("State Machine Metrics:");
    println!("  Total transitions: {}", metrics.total_transitions);
    println!("  Successful: {}", metrics.successful_transitions);
    println!("  Failed: {}", metrics.failed_transitions);
    println!("  Success rate: {:.2}%", metrics.success_rate() * 100.0);

    if let Some(avg_time) = metrics.average_transition_time() {
        println!("  Average transition time: {:?}", avg_time);
    }

    println!("  State visit counts:");
    for (state, count) in &metrics.state_visit_counts {
        println!("    {}: {}", state, count);
    }
}

/// Example 5: With guard priorities (requires 'guards' feature)
#[cfg(feature = "guards")]
fn guards_example() {
    println!("\n=== Guard Priorities Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Multiple transitions with different priorities
    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount < 100.0)
        .with_priority(10)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing small order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 100.0 && ctx.amount < 1000.0)
        .with_priority(20)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing medium order {} (amount: {})",
                ctx.order_id, ctx.amount
            );
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .when(|_s, _e, ctx| ctx.amount >= 1000.0)
        .with_priority(30)
        .perform(|_s, _e, ctx| {
            println!(
                "Processing large order {} (amount: {}) - Priority handling!",
                ctx.order_id, ctx.amount
            );
        });

    let state_machine = builder.id("GuardsOrderMachine").build();

    // Test with different order amounts
    let contexts = vec![
        OrderContext {
            order_id: "ORD-SMALL".to_string(),
            amount: 50.0,
            customer_id: "C1".to_string(),
        },
        OrderContext {
            order_id: "ORD-MEDIUM".to_string(),
            amount: 500.0,
            customer_id: "C2".to_string(),
        },
        OrderContext {
            order_id: "ORD-LARGE".to_string(),
            amount: 5000.0,
            customer_id: "C3".to_string(),
        },
    ];

    for context in contexts {
        let _ = state_machine.fire_event(OrderState::PaymentReceived, OrderEvent::Process, context);
    }
}

/// Example 6: With visualization (requires 'visualization' feature)
#[cfg(feature = "visualization")]
fn visualization_example() {
    println!("\n=== Visualization Example ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Build a complete order flow
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Shipped)
        .to(OrderState::Delivered)
        .on(OrderEvent::Deliver)
        .perform(|_s, _e, _c| {});

    builder
        .external_transitions()
        .from_among(vec![
            OrderState::New,
            OrderState::PaymentPending,
            OrderState::Processing,
        ])
        .to(OrderState::Cancelled)
        .on(OrderEvent::Cancel)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Cancelled)
        .to(OrderState::Refunded)
        .on(OrderEvent::Refund)
        .perform(|_s, _e, _c| {});

    let state_machine = builder.id("VisualOrderMachine").build();

    println!("DOT Format:");
    println!("{}", state_machine.to_dot());

    println!("\nPlantUML Format:");
    println!("{}", state_machine.to_plantuml());
}

/// Example 7: With parallel regions (requires 'parallel' feature)
#[cfg(feature = "parallel")]
fn parallel_example() {
    println!("\n=== Parallel Regions Example ===");

    // Order processing region
    let mut order_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    order_builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, ctx| {
            println!("Order region: Processing order {}", ctx.order_id);
        });

    // Payment processing region (using same states/events for simplicity)
    let mut payment_builder =
        StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();
    payment_builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .perform(|_s, _e, ctx| {
            println!(
                "Payment region: Payment confirmed for order {}",
                ctx.order_id
            );
        });

    let mut parallel_machine = ParallelStateMachine::new();
    parallel_machine.add_region(order_builder.id("OrderRegion").build());
    parallel_machine.add_region(payment_builder.id("PaymentRegion").build());

    let context = OrderContext {
        order_id: "ORD-PARALLEL".to_string(),
        amount: 199.99,
        customer_id: "CUST-P1".to_string(),
    };

    // Fire events in parallel regions
    println!("Firing Process event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::New, OrderState::PaymentPending],
        OrderEvent::Process,
        context.clone(),
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }

    println!("Firing ConfirmPayment event in parallel regions:");
    let results = parallel_machine.fire_event(
        vec![OrderState::Processing, OrderState::PaymentPending],
        OrderEvent::ConfirmPayment,
        context,
    );

    for (i, result) in results.iter().enumerate() {
        println!("  Region {}: {:?}", i, result);
    }
}

/// Example 8: Complete example with multiple features
#[cfg(all(feature = "history", feature = "metrics", feature = "extended"))]
fn complete_example() {
    println!("\n=== Complete Example with Multiple Features ===");

    let mut builder = StateMachineBuilderFactory::create::<OrderState, OrderEvent, OrderContext>();

    // Configure entry/exit actions
    builder
        .with_entry_action(OrderState::Processing, |_s, ctx| {
            println!("[ENTRY] Starting to process order {}", ctx.order_id);
        })
        .with_exit_action(OrderState::Processing, |_s, ctx| {
            println!("[EXIT] Finished processing order {}", ctx.order_id);
        });

    // Build transitions
    builder
        .external_transition()
        .from(OrderState::New)
        .to(OrderState::PaymentPending)
        .on(OrderEvent::Pay)
        .perform(|_s, _e, ctx| {
            println!("Payment initiated for ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentPending)
        .to(OrderState::PaymentReceived)
        .on(OrderEvent::ConfirmPayment)
        .when(|_s, _e, ctx| ctx.amount > 0.0)
        .perform(|_s, _e, ctx| {
            println!("Payment confirmed: ${}", ctx.amount);
        });

    builder
        .external_transition()
        .from(OrderState::PaymentReceived)
        .to(OrderState::Processing)
        .on(OrderEvent::Process)
        .perform(|_s, _e, _c| {});

    builder
        .external_transition()
        .from(OrderState::Processing)
        .to(OrderState::Shipped)
        .on(OrderEvent::Ship)
        .perform(|_s, _e, ctx| {
            println!("Order {} shipped", ctx.order_id);
        });

    builder.set_fail_callback(Arc::new(|state, event, ctx| {
        println!(
            "FAILED: Cannot handle {:?} in state {:?} for order {}",
            event, state, ctx.order_id
        );
    }));

    let state_machine = builder.id("CompleteOrderMachine").build();

    // Process an order through the complete flow
    let context = OrderContext {
        order_id: "ORD-COMPLETE".to_string(),
        amount: 999.99,
        customer_id: "CUST-VIP".to_string(),
    };

    println!("\nProcessing order through complete flow:");
    let states = [
        (OrderState::New, OrderEvent::Pay),
        (OrderState::PaymentPending, OrderEvent::ConfirmPayment),
        (OrderState::PaymentReceived, OrderEvent::Process),
        (OrderState::Processing, OrderEvent::Ship),
    ];

    for (state, event) in &states {
        let result = state_machine.fire_event(state.clone(), event.clone(), context.clone());
        println!("  {:?} + {:?} = {:?}", state, event, result);
    }

    // Try an invalid transition
    println!("\nTrying invalid transition:");
    let _ = state_machine.fire_event(OrderState::Shipped, OrderEvent::Pay, context);

    // Display collected data
    println!("\nHistory:");
    for record in state_machine.get_history() {
        println!(
            "  {:?} -> {:?} (success: {})",
            record.from, record.to, record.success
        );
    }

    println!("\nMetrics:");
    let metrics = state_machine.get_metrics();
    println!(
        "  Total: {}, Success: {}, Failed: {}",
        metrics.total_transitions, metrics.successful_transitions, metrics.failed_transitions
    );
}

pub(crate) fn add_transition(&mut self, transition: Transition<S, E, C>)

Trait Implementations

impl<S, E, C> Default for StateMachineBuilder<S, E, C>

where S: State, E: Event, C: Context,

fn default() -> Self

Returns the “default value” for a type.