silk.machine.snapshot.

The whole state of a running machine as one value, and the steps that advance it: Snapshot and Steps.

When to use#

Use Steps.begin to start a machine and Steps.send to give it an event without performing any effect, for example in a test. Use the silk.machine.actor module when the effects must also be performed.

Details#

A Snapshot holds the state value, the context, the queued events and effects, the clock and the running timers. When the four types of the machine implement Schema, the snapshot does too, so a program can write it as JSON, read it back and continue. Every time is u64 nanoseconds. Steps.advance moves the clock and takes the delayed transitions that are due.

Gotchas#

A step that never settles, or that runs out of memory, leaves the machine with Status.Failed. It takes no more events after that.

Import as Snapshot with import silk.machine.snapshot { Snapshot }.

Public declarations: 5.

Status#

silk
pub union Status

Whether a machine can still take events.

Active#

silk
Active

It takes events.

Done#

silk
Done

It reached a final state of its root chart.

Stopped#

silk
Stopped

It was stopped before it finished.

Failed#

silk
Failed

A step failed: its eventless transitions never settled, or memory ran out. The value is where the step stopped, its timers are cancelled and it takes no more events.

Implementation Schema for Status#

silk
impl Schema for Status

Timer#

silk
pub struct Timer

A running timer of a delayed transition.

Field path#

silk
pub path: String

The place of the chart that declares the delayed transition: the machine's type name, then the variant and field of each region down to it, as in Editor.Open.bold.

Field index#

silk
pub index: u32

The position of the delayed transition in that chart.

Field deadline#

silk
pub deadline: u64

When the timer fires, in nanoseconds of wall clock time.

Implementation Schema for Timer#

silk
impl Schema for Timer

Snapshot#

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

Everything needed to continue a machine.

Field version#

silk
pub version: u32

Field status#

silk
pub status: Status

Field value#

silk
pub value: S

The state, regions included.

Field context#

silk
pub context: C

Field mailbox#

silk
pub mailbox: List<E>

Events received but not yet processed.

Field pending#

silk
pub pending: List<X>

Effects queued by transitions and not yet performed.

Field clock#

silk
pub clock: u64

The wall clock time of the last step, in nanoseconds. New timers count from it.

Field timers#

silk
pub timers: List<Timer>

Timers of the delayed transitions of the active states.

Implementation Schema for Snapshot<S, E, C, X>#

silk
impl<S: Schema, E: Schema, C: Schema, X: Schema> Schema for Snapshot<S, E, C, X>

TransitionLoopError#

silk
pub struct TransitionLoopError

A machine stuck in eventless transitions.

Implementation Debug for TransitionLoopError#

silk
impl Debug for TransitionLoopError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Writes TransitionLoopError.

Steps#

silk
pub struct Steps

Implementation Steps#

silk
impl Steps

Associated function begin#

silk
pub effect fn begin<S: Machine<E, C, X>, E, C, X>(context: C, now: u64) -> Snapshot<S, E, C, X>
    ! OutOfMemoryError | TransitionLoopError
    ? &mut Allocator

Returns the first snapshot of a machine: its initial state entered with context at the wall clock time now, in nanoseconds. A machine without delayed transitions can pass 0.

Associated function send#

silk
pub effect fn send<S: Machine<E, C, X>, E, C, X>(
    snapshot: &mut Snapshot<S, E, C, X>,
    event: E,
  ) -> bool
    ! OutOfMemoryError | TransitionLoopError
    ? &mut Allocator

Processes event and everything it raises, and returns whether a state handled event.

Errors#

TransitionLoopError when eventless transitions or raised events never settle, and OutOfMemoryError. Either one leaves the machine Status.Failed, with its timers cancelled, so it takes no more events. Steps.advance fails the same way.

Associated function hasTag#

silk
pub fn hasTag<S: Machine<E, C, X>, E, C, X>(
    snapshot: &Snapshot<S, E, C, X>,
    tag: string,
  ) -> bool

Returns whether an active state of the machine, at any depth, has the tag tag.

Associated function meta#

silk
pub fn meta<S: Machine<E, C, X>, E, C, X>(snapshot: &Snapshot<S, E, C, X>, key: string) -> Option<
    string<'static>
  >

Returns the meta data under key of the active state of the machine, or of the first of its regions that has one.

Associated function nextDeadline#

silk
pub fn nextDeadline<S: Machine<E, C, X>, E, C, X>(snapshot: &Snapshot<S, E, C, X>) -> Option<
    u64
  >

Returns the deadline of the timer that fires first, in nanoseconds of wall clock time.

Details#

It is the earliest of the machine's own timers and of Machine.deadline, which is how the timers of a child machine are counted.

Associated function advance#

silk
pub effect fn advance<S: Machine<E, C, X>, E, C, X>(
    snapshot: &mut Snapshot<S, E, C, X>,
    now: u64,
  ) -> bool
    ! OutOfMemoryError | TransitionLoopError
    ? &mut Allocator

Moves the machine's clock to now and takes the delayed transitions that are due, earliest first. Returns whether one was taken.

Details#

now is wall clock time in nanoseconds. A deadline is kept as it was set, so a timer whose deadline passed while the program was not running fires on the first call after a restore. When Machine.deadline is due, Machine.tick runs one time after the machine's own timers.

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