Module hooks 

Available on stageleft_runtime and crate feature sim only.

Test-side API for simulator hooks: scripting the decisions of unsafe operators.

A hook handle (see crate::sim_hooks) is created from the FlowBuilder via FlowBuilder::sim_hook and attached to one specific unsafe operator with nondet!(/** reason */ hook = handle). Inside a simulation test body (under SimFlow::deterministic, fuzz, or exhaustive), the handle scripts the operator’s decisions.

The script is a schedule

Decision calls are async, and the sequence of calls in the test body is a schedule, read in program order:

• Consecutive decisions that target different hooks of the same tick form a group: one execution of that tick will consume all of them together.
• A decision that targets a different tick — or the next execution of the same tick (scripting a hook that already has a decision in the current group) — starts a new group. The .await on the first decision of a new group suspends the test until the previous group’s tick execution has actually happened, so the test body advances in lockstep with the execution it describes. Decisions whose turn has already come return immediately without suspending.
• Output awaits are group barriers: an output await completes only after every decision scripted so far has been consumed.

A decision may be scripted before its data exists (release(3) immediately after send_many([1, 2, 3])): the tick simply fires at the first moment the decision can be honored in full. A decision that can never be honored is reported when the simulation runs out of other work, attributed to the test line that is suspended waiting on it.

Holding data on purpose

A hook with buffered data and no decision is an error the simulator reports at every scheduling boundary. When buffering is the scenario, declare it with the pause family (BatchHook::pause, BatchHook::pause_while, BatchHook::pause_until_count, BatchHook::auto_pause, and the snapshot equivalents).

Re-exports

pub use crate::sim_hooks::BatchHook;

pub use crate::sim_hooks::OrderingHook;

pub use crate::sim_hooks::SimHook;

pub use crate::sim_hooks::SnapshotHook;

Structs

BatchStatus

The pending-input view a batch hook reports to its test-side handle (see [ScriptableHook::status]), used by pause_until_* predicates.

DecisionFuture

A scripted decision that has been issued but not yet installed into the schedule.

OrderingStatus

PauseUntilFuture

A pause_until wait: resolves once the hook’s pending-input status satisfies the predicate, un-pausing the hook. The status is read from the hook on demand at every poll (the test body is polled between every pair of scheduler steps), so the wait resolves at the first scheduling point where the predicate holds. Panics (at the .await’s location) if the simulation can no longer satisfy it.

SnapshotStatus

The pending-input view a snapshot hook reports to its test-side handle (see [ScriptableHook::status]), used by pause_until_* predicates.