silk.machine.snapshot.
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#
pub union StatusWhether a machine can still take events.
Active#
ActiveIt takes events.
Done#
DoneIt reached a final state of its root chart.
Stopped#
StoppedIt was stopped before it finished.
Failed#
FailedA 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#
impl Schema for StatusTimer#
pub struct TimerA running timer of a delayed transition.
Field path#
pub path: StringThe 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#
pub index: u32The position of the delayed transition in that chart.
Field deadline#
pub deadline: u64When the timer fires, in nanoseconds of wall clock time.
Implementation Schema for Timer#
impl Schema for TimerSnapshot#
pub struct Snapshot<S, E, C, X>Everything needed to continue a machine.
Field version#
pub version: u32Field status#
pub status: StatusField value#
pub value: SThe state, regions included.
Field context#
pub context: CField mailbox#
pub mailbox: List<E>Events received but not yet processed.
Field pending#
pub pending: List<X>Effects queued by transitions and not yet performed.
Field clock#
pub clock: u64The wall clock time of the last step, in nanoseconds. New timers count from it.
Field timers#
pub timers: List<Timer>Timers of the delayed transitions of the active states.
Implementation Schema for Snapshot<S, E, C, X>#
impl<S: Schema, E: Schema, C: Schema, X: Schema> Schema for Snapshot<S, E, C, X>TransitionLoopError#
pub struct TransitionLoopErrorA machine stuck in eventless transitions.
Implementation Debug for TransitionLoopError#
impl Debug for TransitionLoopErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterWrites TransitionLoopError.
Steps#
pub struct StepsImplementation Steps#
impl StepsAssociated function begin#
pub effect fn begin<S: Machine<E, C, X>, E, C, X>(context: C, now: u64) -> Snapshot<S, E, C, X>
! OutOfMemoryError | TransitionLoopError
? &mut AllocatorReturns 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#
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 AllocatorProcesses 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#
pub fn hasTag<S: Machine<E, C, X>, E, C, X>(
snapshot: &Snapshot<S, E, C, X>,
tag: string,
) -> boolReturns whether an active state of the machine, at any depth, has the tag tag.
Associated function meta#
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#
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#
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 AllocatorMoves 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.