Struct CompiledSim 

pub struct CompiledSim { /* private fields */ }

Available on crate feature sim and stageleft_runtime only.

A handle to a compiled Hydro simulation, which can be instantiated and run.

Implementations

impl CompiledSim

pub fn with_instance<T>( &self, thunk: impl FnOnce(CompiledSimInstance<'_>) -> T, ) -> T

Executes the given closure with a single instance of the compiled simulation.

pub fn with_instantiator<T>( &self, thunk: impl FnOnce(&dyn Instantiator<'_>) -> T, always_log: bool, ) -> T

Executes the given closure with an Instantiator, which can be called to create independent instances of the simulation. This is useful for fuzzing, where we need to re-execute the simulation several times with different decisions.

The always_log parameter controls whether to log tick executions and stream releases. If it is true, logging will always be enabled. If it is false, logging will only be enabled if the HYDRO_SIM_LOG environment variable is set to 1.

pub fn fuzz<'a>( &'a self, thunk: impl AsyncFn(CompiledSimInstance<'_>) + RefUnwindSafe, )

Uses a fuzzing strategy to explore possible executions of the simulation. The provided closure will be repeatedly executed with instances of the Hydro program where the batching boundaries, order of messages, and retries are varied.

During development, you should run the test that invokes this function with the cargo sim command, which will use libfuzzer to intelligently explore the execution space. If a failure is found, a minimized test case will be produced in a sim-failures directory. When running the test with cargo test (such as in CI), if a reproducer is found it will be executed, and if no reproducer is found a small number of random executions will be performed.

pub fn fuzz_repro<'a>( &'a self, bytes: Vec<u8>, thunk: impl AsyncFnOnce(CompiledSimInstance<'_>) + RefUnwindSafe, )

Executes the given closure with a single instance of the compiled simulation, using the provided bytes as the source of fuzzing decisions. This can be used to manually reproduce a failure found during fuzzing.

pub fn exhaustive<'a>( &'a self, thunk: impl AsyncFn(CompiledSimInstance<'_>) + RefUnwindSafe, ) -> usize

Exhaustively searches all possible executions of the simulation. The provided closure will be repeatedly executed with instances of the Hydro program where the batching boundaries, order of messages, and retries are varied.

Exhaustive searching is feasible when the inputs to the Hydro program are finite and there are no dataflow loops that generate infinite messages. Exhaustive searching provides a stronger guarantee of correctness than fuzzing, but may take a long time to complete. Because no fuzzer is involved, you can run exhaustive tests with cargo test.

Returns the number of distinct executions explored.