Module sim_hooks 

Handle types for simulator hooks: scripting the decisions of unsafe operators.

Every unsafe operator (like Stream::batch or Singleton::snapshot) takes a NonDet guard. A guard can optionally carry a hook handle, which lets a simulation test take manual control of the non-deterministic decision made by that operator (which elements form the next batch, which version of a piece of state a snapshot reveals, …). See hydro_lang::sim::hooks for the test-side scripting API.

Handles are created from the FlowBuilder via FlowBuilder::sim_hook before the program under test is constructed, and attached to the operator they control with the nondet!(... hook = handle) syntax. Handles are small and Copy: the same value is passed into the program during construction and used later inside the test body to script decisions.

Hook scopes

Every handle type carries a scope parameter naming the kind of root location the hooked operator runs on, mirroring Location::SimHookScope:

• OnProcess<P> (the default): the operator has one instance, scripted directly.
• OnCluster<C>: every cluster member runs its own instance of the operator; select the one to script with .on(member_id), which yields an OnMember<C>-scoped handle.

Operators name the scope in their NonDet payload type, so scope mismatches fail to compile.

This module contains only the handle types themselves (plain data), so components can expose hookable signatures (e.g. nondet_batch: NonDet<Option<BatchHook<u32>>>, passed directly to the batch operator it controls) without pulling in any simulator machinery; binding a hook in a flow that is deployed rather than simulated is harmless metadata that non-simulator backends ignore.

Structs

BatchHook

A hook handle controlling a batch operator over a stream of T elements with ordering O and retry guarantee R (mirroring the type of the stream being batched). S is the handle’s scope.

KeyedBatchHook

A hook handle controlling a batch operator over a keyed stream with keys K, values V, per-key value ordering O, and retry guarantee R (mirroring the type of the keyed stream being batched). S is the handle’s scope.

KeyedMergeOrderedHook

A hook handle controlling a merge_ordered operator over keyed streams with keys K and values V. S is the handle’s scope.

KeyedOrderingHook

A hook handle controlling an assume_ordering operator over a keyed stream with keys K and values V. S is the handle’s scope.

KeyedSnapshotHook

A hook handle controlling a snapshot (or batch) operator over a keyed singleton with keys K and values V. S is the handle’s scope.

MergeOrderedHook

A hook handle controlling a merge_ordered operator over streams of T elements. S is the handle’s scope.

OnCluster

Hook scope marker: the hooked operator runs on a Cluster with tag C, so every member runs its own independent instance of the operator.

OnMember

Hook scope marker: one selected member’s instance of an operator running on a Cluster with tag C, produced by .on(member_id).

OnProcess

Hook scope marker: the hooked operator runs on a Process with tag P and has one instance, which the handle scripts directly.

OrderingHook

A hook handle controlling an assume_ordering operator over T elements. S is the handle’s scope.

PartialOrderingHook

A hook handle controlling an entries_partially_ordered operator over a keyed stream with keys K and values V. S is the handle’s scope.

SnapshotHook

A hook handle controlling a snapshot operator over a singleton of T. S is the handle’s scope.

Traits

BindableHookScope

Hook scopes a handle can be created and bound with: OnProcess and OnCluster. Operator signatures select the scope through Location::SimHookScope.

ScriptableHookScope

Hook scopes that name a single instance of the hooked operator and can therefore script decisions and pauses: OnProcess and OnMember. An OnCluster-scoped handle must first select a member with .on(member_id).

SimHook

A simulator hook handle (or a set of them) that can be created in one call to FlowBuilder::sim_hook.