Struct SimulationBuilder 

pub struct SimulationBuilder { /* private fields */ }

Builder pattern for configuring and running simulation experiments.

Implementations

impl SimulationBuilder

pub fn new() -> Self

Create a new empty simulation builder.

pub fn register_workload<S, F, Fut>(self, name: S, workload: F) -> Self

where S: Into<String>, F: Fn(SimRandomProvider, SimNetworkProvider, SimTimeProvider, TokioTaskProvider, WorkloadTopology) -> Fut + 'static, Fut: Future<Output = SimulationResult<SimulationMetrics>> + 'static,

Register a workload with the simulation builder.

Arguments

• name - Name for the workload (for reporting purposes)
• workload - Async function that takes a RandomProvider, NetworkProvider, TimeProvider, TaskProvider, and WorkloadTopology and returns simulation metrics

pub fn set_iterations(self, iterations: usize) -> Self

Set the number of iterations to run.

pub fn set_iteration_control(self, control: IterationControl) -> Self

Set the iteration control strategy.

pub fn set_time_limit(self, duration: Duration) -> Self

Run for a specific wall-clock time duration.

pub fn run_until_all_sometimes_reached(self, safety_limit: usize) -> Self

Run until all sometimes_assert! assertions have been reached.

pub fn set_debug_seeds(self, seeds: Vec<u64>) -> Self

Set specific seeds for deterministic debugging and regression testing.

This method is specifically designed for debugging scenarios where you need to reproduce specific problematic behavior. Unlike set_seeds(), the name makes it clear this is for debugging/testing specific scenarios.

Key differences from set_seeds():

• Intent: Clearly indicates debugging/testing purpose
• Usage: Typically used with FixedCount(1) for reproducing exact scenarios
• Documentation: Self-documenting that these seeds are for specific test cases

Common use cases:

• Reproducing TCP ordering bugs (e.g., seed 42 revealed the ordering issue)
• Regression testing for specific edge cases
• Deterministic testing in CI/CD pipelines
• Investigating assertion failures at specific seeds

Example: set_debug_seeds(vec![42]) with FixedCount(1) ensures the test always runs with seed 42, making it reproducible for debugging the TCP ordering fix.

pub fn use_random_config(self) -> Self

Enable randomized network configuration for chaos testing

pub fn with_invariants(self, invariants: Vec<InvariantCheck>) -> Self

Register invariant check functions to be executed after every simulation event.

Invariants receive a snapshot of all actor states and the current simulation time, and should panic if any global property is violated.

Arguments

• invariants - Vector of invariant check functions

Example

SimulationBuilder::new()
    .with_invariants(vec![
        Box::new(|states, _time| {
            let total_sent: u64 = states.values()
                .filter_map(|v| v.get("messages_sent").and_then(|s| s.as_u64()))
                .sum();
            let total_received: u64 = states.values()
                .filter_map(|v| v.get("messages_received").and_then(|r| r.as_u64()))
                .sum();
            assert!(total_received <= total_sent, "Message conservation violated");
        })
    ])

pub async fn run(self) -> SimulationReport

Run the simulation and generate a report.

Trait Implementations

impl Default for SimulationBuilder

fn default() -> Self

Returns the “default value” for a type.