silk.machine.explore.

Walks a machine through every state it can reach: Explorer and Walk.

When to use#

Use this module to check a machine as a whole, in a test. Explorer.walk runs the machine for real, with its guards, its context and its regions, and gives back every step it could take. The walk then answers questions about the whole machine: which events no state handles, which states nothing reaches, which rows overlap, and what a command leaves from start to end. Use the silk.machine.paths module for one path to each state of one chart read as data.

Details#

The walk starts from the snapshots it is given and sends every event of a list to each snapshot it has not seen. Two snapshots are the same when their MessagePack bytes are, so the state union, the event union, the context and the effects must implement Schema. A state that waits for the world, see Chart.awaits, gets only the events it waits for. Every other state gets only the events that no state waits for.

Gotchas#

The walk ends only when the machine has a finite number of snapshots. Give Explorer.walk a limit, and check Walk.complete.

Import as Explorer with import silk.machine.explore { Explorer }.

Public declarations: 5.

Step#

silk
pub struct Step<X>

One event sent to one snapshot of a walk.

Field from#

silk
pub from: usize

The position in Walk.nodes of the snapshot the event was sent to.

Field event#

silk
pub event: usize

The position of the event in the list given to Explorer.walk.

Field handled#

silk
pub handled: bool

Whether a state handled the event. A step that no state handled is a hole: nobody wrote a row for this event in this state.

Field contenders#

silk
pub contenders: u32

The largest number of rows of one state that applied to the event, see Machines.contenders. More than 1 means that the order of the rows decided.

Field effects#

silk
pub effects: List<X>

The effects the step queued, in order.

Field to#

silk
pub to: usize

The position in Walk.nodes of the snapshot the step reached.

Node#

silk
pub struct Node<S, E, C, X>

One snapshot a walk reached.

Field snapshot#

silk
pub snapshot: Snapshot<S, E, C, X>

Field awaiting#

silk
pub awaiting: bool

Whether an active state waits for an answer of the world, see Chart.awaits.

Run#

silk
pub struct Run

What one event leaves from the moment it is sent until the machine waits for nothing: the step of the event, then one step for each answer of the world.

Field from#

silk
pub from: usize

The position in Walk.nodes of the snapshot the run starts from.

Field steps#

silk
pub steps: List<usize>

The positions in Walk.steps of the steps of the run, in order. The first one is the step of the event, the others are the steps of the answers.

Field to#

silk
pub to: usize

The position in Walk.nodes of the snapshot the run ends in.

Field settled#

silk
pub settled: bool

Whether the run ends in a snapshot that waits for nothing. A run that does not is one that went on for more steps than the limit given to Walk.runs, or that waits for an answer no step gives.

Walk#

silk
pub struct Walk<S, E, C, X>

Every snapshot a machine reached and every step between them, from Explorer.walk.

Field nodes#

silk
pub nodes: List<Node<S, E, C, X>>

Field steps#

silk
pub steps: List<Step<X>>

Field complete#

silk
pub complete: bool

Whether the walk saw every snapshot the machine can reach. It is false when the walk stopped at its limit.

Explorer#

silk
pub struct Explorer

Implementation Explorer#

silk
impl Explorer

Associated function walk#

silk
pub effect fn walk<S: Machine<E, C, X> + Schema, E: Schema, C: Schema, X: Schema>(
    starts: List<Snapshot<S, E, C, X>>,
    events: &[E],
    limit: usize,
  ) -> Walk<S, E, C, X>
    ! SchemaError | OutOfMemoryError | TransitionLoopError
    ? &mut Allocator

Walks the machine from each snapshot of starts, sending every event of events to every snapshot it reaches, until it has seen them all or holds limit snapshots.

Details#

A snapshot whose active state waits for the world, see Chart.awaits, gets the events of events that it waits for. Any other snapshot gets the events that no state of the machine waits for. A machine that is done, stopped or failed gets none. The effects a step queued are moved into its Step, so every snapshot of the walk has none pending.

Errors#

SchemaError when a snapshot or an event cannot be written as MessagePack or read back. TransitionLoopError when a step never settles. OutOfMemoryError.

Implementation Walk<S, E, C, X>#

silk
impl<S: Machine<E, C, X>, E, C, X> Walk<S, E, C, X>

Method holes#

silk
pub effect fn holes(self: &Self) -> List<usize>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the positions in Walk.steps of the steps that no state handled, in the order the walk took them. Each one is a state and an event that nobody wrote a row for.

Method overlaps#

silk
pub effect fn overlaps(self: &Self) -> List<usize>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the positions in Walk.steps of the steps where more than one row of one state applied, so the order the rows were written in decided which one was taken.

Method unreached#

silk
pub effect fn unreached(self: &Self) -> List<string<'static>>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the names of the states that are active in no snapshot of the walk, as Machines.states names them, such as Door.Open.

Method stuck#

silk
pub effect fn stuck(self: &Self) -> List<usize>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the positions in Walk.nodes of the snapshots that can take no event: the machine is active there and no step from the snapshot was handled.

Method runs#

silk
pub effect fn runs(self: &Self, limit: usize) -> List<Run>
    ! OutOfMemoryError
    ? &mut Allocator

Returns every run of the walk: for each step from a snapshot that waits for nothing, the step and each way the world can answer until the machine waits for nothing again.

Details#

A step that reaches a snapshot that waits for the world continues with each step from that snapshot, so one event gives one run for each combination of answers. A run stops after limit steps with Run.settled false, which is how a machine whose answers go in a circle shows. Steps that no state handled start no run.

Category: State machines.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page