silk.machine.chart.

Statecharts written as a static table over union types: Chart and Machine.

When to use#

Use this module to describe behavior that depends on a state: a download that retries, a form with steps, a connection that opens and closes. Write the states as a union, the events as a union, and implement Machine for the state union with a Chart that connects them. Use the silk.machine.simple module when the machine keeps no data and queues no effects.

Details#

A chart row names the state it leaves and the event it takes, and the compiler checks both names against the unions. The state a row enters is a value of the state union, so a state can hold data. A machine never performs work: enter, exit and handle queue effects as values through Enqueue, and the caller performs them. Guards are built with Guards. A field of a state that holds a machine of its own is a region, declared with Chart.region.

Gotchas#

Rows for one state and event are tried in the order they are written. Put a guarded row before the plain row for the same state and event.

Import as Chart with import silk.machine.chart { Chart }.

Public declarations: 25.

Guard#

silk
pub struct Guard

A guard: one function, or guards combined with and, or and not. Built with Guards.

Field name#

silk
pub name: string<'static>

The name Guards.named gave the guard, or an empty string.

Guards#

silk
pub struct Guards

Builds guards out of several functions for Chart.onWhen and the other When builders.

When to use#

Use it when a transition depends on more than one check, so each check stays a small function that can be named and reused: Guards.and(Guards.of(isPaid), Guards.not(Guards.of(isLocked))). A When builder takes such a guard or one function directly.

Details#

The functions of one guard all have the contract of the place the guard is used: fn(&C, &E) -> bool on a transition that takes an event, fn(&C) -> bool on an eventless one. A function with another contract is a compile error where the chart is used. and and or stop at the first part that decides the answer, in the order written.

Implementation Guards#

silk
impl Guards

Associated function of#

silk
pub static fn of<F>(function: F) -> Guard

A guard that holds when function returns true.

Associated function named#

silk
pub static fn named<G>(name: string<'static>, guard: G) -> Guard

Gives guard the name name, which says in words when the guard holds, such as "the version is installed". guard is a function or a Guard.

When to use#

Name the guards of a chart that people read as a table. The Definition of the machine keeps the name, so a generated page can say why a row applies. A guard without a name is only known as guarded.

Associated function from#

silk
pub static fn from<G>(guard: G) -> Guard

Returns guard when it is a Guard, and the guard of the function guard otherwise.

Associated function holds#

silk
pub fn holds<C, E>(static guard: Guard, context: &C, event: &E) -> bool

Returns whether guard holds for context and event. The functions of guard have the contract fn(&C, &E) -> bool, as on a transition that takes an event.

Associated function not#

silk
pub static fn not(guard: Guard) -> Guard

A guard that holds when guard does not.

Associated function and#

silk
pub static fn and(first: Guard, second: Guard) -> Guard

A guard that holds when both first and second hold.

Associated function or#

silk
pub static fn or(first: Guard, second: Guard) -> Guard

A guard that holds when first or second holds.

Edge#

silk
pub struct Edge<S>

One declared transition.

Field state#

silk
pub state: string<'static>

Field event#

silk
pub event: string<'static>

Field target#

silk
pub target: Intrinsic.StaticSequence<S>

The value the transition enters, or nothing for a transition that takes the event and stays.

Field guard#

silk
pub guard: Intrinsic.StaticSequence<Guard>

The guard of the transition, over functions fn(&C, &E) -> bool. Empty when unguarded.

Field history#

silk
pub history: bool

Whether the target is entered as it was when it was last left, see Chart.history.

Field meta#

silk
pub meta: Intrinsic.StaticSequence<Meta>

The meta data of the transition, see Chart.metaOn.

Field refusal#

silk
pub refusal: Intrinsic.StaticSequence<string<'static>>

The reason the state refuses the event, see Chart.refuse. Empty for any other row.

Field index#

silk
pub index: u32

The position of the row among the edges of its chart.

Leaves#

silk
pub struct Leaves<X>

The effects that one row of a chart leaves, see Chart.leaves.

Field kind#

silk
pub kind: u8

The kind of row: ROW_EDGE, ROW_ALWAYS, ROW_DONE or ROW_DELAY.

Field index#

silk
pub index: u32

The position of the row among the rows of its kind.

Field effects#

silk
pub effects: Intrinsic.StaticSequence<X>

Field condition#

silk
pub condition: Intrinsic.StaticSequence<Guard>

The guard of Chart.leavesWhen: the row leaves the effects only when it holds. Empty for Chart.leaves.

Awaited#

silk
pub struct Awaited

An event that a state waits for the world to answer with, see Chart.awaits.

Field state#

silk
pub state: string<'static>

Field event#

silk
pub event: string<'static>

ROW_NONE#

silk
pub const ROW_NONE: u8

The Leaves.kind of no row.

ROW_EDGE#

silk
pub const ROW_EDGE: u8

The Leaves.kind of a row that takes an event: Chart.edges.

ROW_ALWAYS#

silk
pub const ROW_ALWAYS: u8

The Leaves.kind of an eventless row: Chart.eventless.

ROW_DONE#

silk
pub const ROW_DONE: u8

The Leaves.kind of a row taken when the regions are done: Chart.dones.

ROW_DELAY#

silk
pub const ROW_DELAY: u8

The Leaves.kind of a delayed row: Chart.delays.

Tag#

silk
pub struct Tag

A tag of a state: a name that several states can share, asked for with Machines.hasTag.

Field state#

silk
pub state: string<'static>

Field tag#

silk
pub tag: string<'static>

Meta#

silk
pub struct Meta

One entry of the meta data of a state: a text value under a key, read with Machines.meta.

Field state#

silk
pub state: string<'static>

Field key#

silk
pub key: string<'static>

Field value#

silk
pub value: string<'static>

ANY#

silk
pub const ANY: string<'static>

The event name of a transition that any event takes.

Remember#

silk
pub struct Remember

A state whose value is kept when its chart leaves it, so a transition can come back to it.

Field state#

silk
pub state: string<'static>

Field field#

silk
pub field: string<'static>

The label of the field of the context that keeps the value, a History<S>.

Field deep#

silk
pub deep: bool

Whether the regions come back whole. When false only their own states come back, and the regions below those start again.

History#

silk
pub struct History<S>

The value a state had when its chart last left it. A field of the context of this type keeps the history of one state, see Chart.history.

Field last#

silk
pub last: Option<S>

Implementation Schema for History<S>#

silk
impl<S: Schema> Schema for History<S>

Implementation History<S>#

silk
impl<S> History<S>

Associated function empty#

silk
pub fn empty() -> History<S>

Returns a history that remembers nothing.

Method take#

silk
pub fn take(self: &mut Self) -> Option<S>

Takes the remembered value out, leaving nothing remembered.

Always#

silk
pub struct Always<S>

One declared eventless transition, taken as soon as its state is active and its condition holds.

Field state#

silk
pub state: string<'static>

Field target#

silk
pub target: S

Field condition#

silk
pub condition: Intrinsic.StaticSequence<Guard>

The condition of the transition, over functions fn(&C) -> bool. Empty when it has none.

Field index#

silk
pub index: u32

The position of the row among the rows of its kind in its chart.

Delay#

silk
pub struct Delay<S>

The static description of one level of a machine: the variants of S are its states, the variants of E its events, C its context and X its effects. A delayed transition: target is taken when state stayed active for duration, in nanoseconds.

Field state#

silk
pub state: string<'static>

Field target#

silk
pub target: S

Field duration#

silk
pub duration: u64

Field index#

silk
pub index: u32

The position of this delay in its chart. With the chart's type name it identifies a timer.

Chart#

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

Field start#

silk
pub start: Intrinsic.StaticSequence<S>

The value the machine starts with: empty until Chart.initial gives one.

Field edges#

silk
pub edges: Intrinsic.StaticSequence<Edge<S>>

Field regions#

silk
pub regions: Intrinsic.StaticSequence<string<'static>>

The labels of the variant fields that hold a child region.

Field eventless#

silk
pub eventless: Intrinsic.StaticSequence<Always<S>>

Field dones#

silk
pub dones: Intrinsic.StaticSequence<Always<S>>

The transitions taken when every region of their state is in a final state.

Field finals#

silk
pub finals: Intrinsic.StaticSequence<string<'static>>

The labels of the final states.

Field delays#

silk
pub delays: Intrinsic.StaticSequence<Delay<S>>

Field histories#

silk
pub histories: Intrinsic.StaticSequence<Remember>

The states that are remembered when the chart leaves them.

Field tags#

silk
pub tags: Intrinsic.StaticSequence<Tag>

Field metas#

silk
pub metas: Intrinsic.StaticSequence<Meta>

The meta data of the states.

Field effects#

silk
pub effects: Intrinsic.StaticSequence<Leaves<X>>

The effects the rows leave, see Chart.leaves.

Field awaited#

silk
pub awaited: Intrinsic.StaticSequence<Awaited>

The answers the states wait for, see Chart.awaits.

Field lastKind#

silk
pub lastKind: u8

The kind and position of the row declared last, which Chart.leaves writes to.

Field lastIndex#

silk
pub lastIndex: u32

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

silk
impl<S, E, C, X> Chart<S, E, C, X>

Associated function of#

silk
pub static fn of() -> Chart<S, E, C, X>

Associated function initial#

silk
pub static fn initial(chart: Chart<S, E, C, X>, state: S) -> Chart<S, E, C, X>

Makes state the value the machine starts with. It is a value of the state union, with its fields: the data the state holds and, for a state with regions, the state each region starts in.

Associated function region#

silk
pub static fn region(chart: Chart<S, E, C, X>, field: Intrinsic.FieldName<S>) -> Chart<
    S,
    E,
    C,
    X
  >

Associated function on#

silk
pub static fn on(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    target: S,
  ) -> Chart<S, E, C, X>

Adds a transition: in the state named state, the event named event takes the machine to target.

Details#

state and event are names, because a transition leaves a state and takes an event whatever their fields hold. target is a value of the state union, so it gives the fields of the state it enters: its data, and the state of each of its regions. This holds for the target of every kind of transition.

A transition between two values of one state runs no exit and no entry function of that state, only those of the regions that changed.

Associated function onWhen#

silk
pub static fn onWhen<G>(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    target: S,
    guard: G,
  ) -> Chart<S, E, C, X>

Like Chart.on, taken only when guard holds. guard is a function fn(&C, &E) -> bool, or a Guard that Guards builds from several. This holds for every When builder.

Associated function onAny#

silk
pub static fn onAny(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    target: S,
  ) -> Chart<S, E, C, X>

Adds a transition that any event takes when no transition of state that names the event is taken. This is xstate's wildcard transition.

Associated function onAnyWhen#

silk
pub static fn onAnyWhen<G>(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    target: S,
    guard: G,
  ) -> Chart<S, E, C, X>

Like Chart.onAny, taken only when guard holds.

Associated function stay#

silk
pub static fn stay(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
  ) -> Chart<S, E, C, X>

Makes state take event without a transition, so the states above it do not get the event. This is xstate's forbidden transition.

Associated function stayWhen#

silk
pub static fn stayWhen<G>(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    guard: G,
  ) -> Chart<S, E, C, X>

Like Chart.stay, only when guard holds.

Associated function stayAny#

silk
pub static fn stayAny(chart: Chart<S, E, C, X>, state: Intrinsic.VariantName<S>) -> Chart<
    S,
    E,
    C,
    X
  >

Makes state take every event that no transition of the state names, without a transition, so the states above it get none of them.

Associated function refuse#

silk
pub static fn refuse(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    reason: string<'static>,
  ) -> Chart<S, E, C, X>

Makes state refuse event for the reason reason: the state takes the event, changes nothing, and the states above it do not get the event.

When to use#

Use it for a command that must fail in this state and leave everything as it was, such as removing something that is not there. A Chart.leaves after the row gives what the refusal leaves behind, such as a message and an exit status.

Details#

When the machine runs, a refusal is a Chart.stay. The difference is for people and for tools that read the chart: the Definition keeps reason, so a refused event is told apart from one nobody wrote a row for.

Associated function refuseWhen#

silk
pub static fn refuseWhen<G>(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    guard: G,
    reason: string<'static>,
  ) -> Chart<S, E, C, X>

Makes state refuse event for the reason reason when guard holds: the state takes the event and changes nothing. guard is a function fn(&C, &E) -> bool or a Guard. The Definition of the machine keeps reason.

Associated function leaves#

silk
pub static fn leaves(chart: Chart<S, E, C, X>, effects: &[X]) -> Chart<S, E, C, X>

Gives the row declared just before it the effects it leaves: when the machine takes the row, it queues effects in order.

When to use#

Use it to say in the chart what a transition does, so a reader, a generated page and a test can all see it: Chart.on("Idle", "Start", Job.Running) |> Chart.leaves(&[...]). Effects queued in Machine.enter, Machine.exit and Machine.handle are code, and only the running machine sees them.

Details#

The row is the last one added with a builder that adds a transition: on, stay, refuse, resume, always, onDone, after and their When forms. A second leaves for one row adds to the first. The effects are queued after the exit functions of the states the row leaves and before the entry functions of the states it enters. A row without a target queues them and changes no state. For each effect the machine first calls Machine.absorb, so the context can take in what the effect means. The Definition of the machine keeps the effects as text.

Gotchas#

It is a compile error when the chart has no row yet.

Associated function leavesWhen#

silk
pub static fn leavesWhen<G>(chart: Chart<S, E, C, X>, condition: G, effects: &[X]) -> Chart<
    S,
    E,
    C,
    X
  >

Says that the last row added also leaves effects, in this order, when condition holds as the row is taken.

When to use#

Use it for a part of a row's footprint that depends on the context, such as a note the row prints only when a project pins another version. It keeps one row for one decision where two rows with two guards would differ in one effect.

Details#

condition is a function fn(&C) -> bool or a Guard of such functions, whatever the kind of the row. It sees the context after Machine.handle ran for the event and before the context absorbed any effect of the row, so two guards of one row never see what the other's effects changed. The effects keep their place among the other leaves of the row. The Definition of the machine keeps each effect as text followed by when and the name of the guard. One row takes at most 63 lists of effects.

Gotchas#

It is a compile error when the chart has no row yet.

Associated function awaits#

silk
pub static fn awaits(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
  ) -> Chart<S, E, C, X>

Says that state waits for the world to answer, and that event is one of the answers.

When to use#

Use it for a state that stands for work in progress whose result the machine cannot know, such as a download that arrives or is cut. Call it one time for each answer. A program that runs the machine does the work when the machine rests in the state, and sends the answer. A tool that walks the machine tries every answer of the state and no other event there.

Details#

It adds no transition: each answer still needs its row. Machines.awaiting tells whether an active state waits for an answer, and Machines.awaits whether it waits for one event.

Associated function tag#

silk
pub static fn tag(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    tag: string<'static>,
  ) -> Chart<S, E, C, X>

Gives state the tag tag. Several states can have one tag, and a state several tags.

Associated function meta#

silk
pub static fn meta(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    key: string<'static>,
    value: string<'static>,
  ) -> Chart<S, E, C, X>

Gives state the meta data value under key: static text about the state for the program to read while the state is active, such as a label or the name of a view. A state can have several keys.

Associated function metaOn#

silk
pub static fn metaOn(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    key: string<'static>,
    value: string<'static>,
  ) -> Chart<S, E, C, X>

Gives the transition that event takes in state the meta data value under key: static text about the transition for tools that read the chart, such as a label for a diagram or a note for a test generator.

Details#

The meta data goes to the last transition declared so far for state and event, so write it right after the row it describes. When a state has a guarded row and a plain row for one event, each one takes its own. It is a compile error when no row was declared. The meta data is part of the Definition of the machine and of its xstate config. It is not read while the machine runs: for that, give the target state a Chart.meta.

Associated function metaOnAny#

silk
pub static fn metaOnAny(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    key: string<'static>,
    value: string<'static>,
  ) -> Chart<S, E, C, X>

Like Chart.metaOn, for the transition that any event takes, see Chart.onAny.

Associated function history#

silk
pub static fn history(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    field: Intrinsic.FieldName<C>,
  ) -> Chart<S, E, C, X>

Keeps the value of state, with its regions, in the context field field when the chart leaves the state. The field is a History<S>. A transition added with Chart.resume enters the state as it was, which is xstate's deep history.

Details#

The kept value is a copy of the state, so the data fields of the states of a chart with a history, and of the regions below them, must be Copy.

The value is kept whenever the state is left: when this chart leaves it, and when a parent state that holds this chart as a region is left.

Associated function shallowHistory#

silk
pub static fn shallowHistory(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    field: Intrinsic.FieldName<C>,
  ) -> Chart<S, E, C, X>

Like Chart.history, but a transition that comes back restores only the state of each region, and the regions below those start at their initial states. This is xstate's shallow history.

Associated function resume#

silk
pub static fn resume(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    target: S,
  ) -> Chart<S, E, C, X>

Adds a transition to the history of the state of target: the state is entered as it was when the chart last left it, or as target when nothing is remembered. Entry functions run for every state entered.

Associated function resumeWhen#

silk
pub static fn resumeWhen<G>(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    event: Intrinsic.VariantName<E>,
    target: S,
    guard: G,
  ) -> Chart<S, E, C, X>

Like Chart.resume, taken only when guard holds.

Associated function final#

silk
pub static fn final(chart: Chart<S, E, C, X>, state: Intrinsic.VariantName<S>) -> Chart<
    S,
    E,
    C,
    X
  >

Associated function always#

silk
pub static fn always(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    target: S,
  ) -> Chart<S, E, C, X>

Associated function alwaysWhen#

silk
pub static fn alwaysWhen<G>(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    target: S,
    condition: G,
  ) -> Chart<S, E, C, X>

Associated function onDone#

silk
pub static fn onDone(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    target: S,
  ) -> Chart<S, E, C, X>

Adds a transition taken as soon as every region of state is in a final state of its chart: the region of a compound state, or all the regions of a parallel state. This is xstate's onDone.

Details#

It is an eventless transition, tried after the Chart.always rows of the state. Its target must leave the state's variant or start a region outside its final state, or the machine never settles and the step fails with TransitionLoopError.

Associated function after#

silk
pub static fn after(
    chart: Chart<S, E, C, X>,
    state: Intrinsic.VariantName<S>,
    duration: u64,
    target: S,
  ) -> Chart<S, E, C, X>

Adds a delayed transition: after duration in state, the machine goes to target. A duration is nanoseconds, so a duration literal such as 500ms or 1m30s gives one. The timer starts when the state is entered and is cancelled when the state is left.

Associated function isFinal#

silk
pub static fn isFinal(chart: Chart<S, E, C, X>, label: string<'static>) -> bool

Associated function isRegion#

silk
pub static fn isRegion(chart: Chart<S, E, C, X>, label: string<'static>) -> bool

Next#

silk
pub union Next<S>

What a transition function decided.

Pass#

silk
Pass

Not handled here: the parent state gets the event.

Stay#

silk
Stay

Handled without a state change.

To#

silk
To

Handled by moving to state.

Field state#

silk
pub state: S

Enqueue#

silk
pub struct Enqueue<E, X>

What a step queued: events for the machine itself and effects to perform after the commit.

Field raised#

silk
pub raised: List<E>

Field effects#

silk
pub effects: List<X>

Field timers#

silk
pub timers: List<TimerChange>

Timers started and cancelled by the states entered and left, in order.

Field clock#

silk
pub clock: u64

The machine's clock at this step, in nanoseconds of wall clock time. A handler that starts a child machine passes it on.

TimerChange#

silk
pub union TimerChange

A timer of a delayed transition that a step started or cancelled.

Start#

silk
Start

Field path#

silk
pub path: string<'static>

Field index#

silk
pub index: u32

Field duration#

silk
pub duration: u64

Cancel#

silk
Cancel

Field path#

silk
pub path: string<'static>

Field index#

silk
pub index: u32

Implementation Enqueue<E, X>#

silk
impl<E, X> Enqueue<E, X>

Associated function make#

silk
pub fn make() -> Enqueue<E, X>

Associated function at#

silk
pub fn at(clock: u64) -> Enqueue<E, X>

Returns an empty queue for a step taken at the wall clock time clock, in nanoseconds.

Method raise#

silk
pub effect fn raise(self: &mut Self, event: E) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Method perform#

silk
pub effect fn perform(self: &mut Self, effect_: X) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Machine#

silk
pub interface Machine<E, C, X>

Operation chart#

silk
static fn chart() -> Chart<Self, E, C, X>

Operation handle#

silk
effect fn handle(state: &Self, context: &mut C, event: &E, enq: &mut Enqueue<E, X>) -> Next<Self>
    ! OutOfMemoryError
    ? &mut Allocator

The transition function of this level. The default handles nothing.

Operation enter#

silk
effect fn enter(state: &Self, context: &mut C, enq: &mut Enqueue<E, X>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Operation exit#

silk
effect fn exit(state: &Self, context: &mut C, enq: &mut Enqueue<E, X>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Operation absorb#

silk
fn absorb(state: &Self, context: &mut C, effect_: &X) -> ()

Takes in an effect that a row of this chart leaves, before the effect is queued. The default does nothing.

When to use#

Implement it when the context is a model of what the effects change, so one function says what each effect means for the context: an effect that creates a file marks the file as present. It runs for the effects of Chart.leaves only, not for effects that enter, exit and handle queue.

Operation deadline#

silk
fn deadline(state: &Self, context: &C) -> Option<u64>

The next time something the context holds needs Machine.tick, in nanoseconds of wall clock time. A machine with a child returns the child's next deadline. The default has none. Only the machine's own states are asked, not its regions.

Operation tick#

silk
effect fn tick(state: &Self, context: &mut C, now: u64, enq: &mut Enqueue<E, X>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Runs when the clock reaches Machine.deadline. A machine with a child advances the child to now here and moves its effects into enq. The default does nothing.

hasGuard#

silk
pub static fn hasGuard<S>(edge: Edge<S>) -> bool

hasCondition#

silk
pub static fn hasCondition<S>(always: Always<S>) -> bool

Machines#

silk
pub struct Machines

Implementation Machines#

silk
impl Machines

Associated function start#

silk
pub fn start<S: Machine<E, C, X>, E, C, X>() -> S

The initial state of S: the value its chart gives to Chart.initial.

Associated function enterAll#

silk
pub effect fn enterAll<S: Machine<E, C, X>, E, C, X>(
    state: &S,
    context: &mut C,
    enq: &mut Enqueue<E, X>,
  ) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Runs the entry functions of state, parents before children, and starts the timers of the states entered.

Associated function exitAll#

silk
pub effect fn exitAll<S: Machine<E, C, X>, E, C, X>(
    state: &S,
    context: &mut C,
    enq: &mut Enqueue<E, X>,
  ) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Runs the exit functions of state, children before parents, and cancels the timers of the states left.

Associated function dispatch#

silk
pub effect fn dispatch<S: Machine<E, C, X>, E, C, X>(
    state: &mut S,
    context: &mut C,
    event: &E,
    enq: &mut Enqueue<E, X>,
  ) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Offers event to state, deepest states first, and returns whether a state handled it.

Details#

The step has two passes, as an xstate microstep does. The first one picks, in every active state, the declared transition the event takes, so every guard sees the context as it was before the event. The second one takes them, deepest states first, with their exit and entry functions. Machine.handle runs in the second pass, before the declared transitions of its state, so it sees what the states below it and the regions before it changed. A final state takes no events.

Associated function awaiting#

silk
pub fn awaiting<S: Machine<E, C, X>, E, C, X>(state: &S) -> bool

Returns whether an active state of state, at any depth, waits for an answer of the world: its chart names it in a Chart.awaits.

Associated function awaits#

silk
pub fn awaits<S: Machine<E, C, X>, E, C, X>(state: &S, event: &E) -> bool

Returns whether an active state of state, at any depth, waits for event as an answer of the world: its chart names the state and the variant of event in a Chart.awaits.

Associated function isAnswer#

silk
pub fn isAnswer<S: Machine<E, C, X>, E, C, X>(event: &E) -> bool

Returns whether a state of the machine S, at any depth, waits for event as an answer of the world: a chart of the machine names the variant of event in a Chart.awaits. The states that are active do not matter.

Associated function active#

silk
pub effect fn active<S: Machine<E, C, X>, E, C, X>(
    state: &S,
    names: &mut List<string<'static>>,
  ) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends to names the name of every active state of state, parents before children. A name is the type of the chart and the state, as in Door.Open.

Associated function states#

silk
pub effect fn states<S: Machine<E, C, X>, E, C, X>(names: &mut List<string<'static>>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends to names the name of every state of the machine S: the states of its chart, then the states of the chart of each region. A name is the type of the chart and the state, as in Door.Open. A chart that several states hold as a region is named each time.

Associated function contenders#

silk
pub fn contenders<S: Machine<E, C, X>, E, C, X>(state: &S, context: &C, event: &E) -> u32

Returns the largest number of declared transitions that event could take in one active state of state: the rows of that state for the event, or for any event, whose guards hold.

When to use#

A tool that checks a chart calls it to find rows that overlap. When the result is more than 1, two rows of one state apply at once and the order they were written in decides which one the machine takes. A final state counts as 0.

Associated function hasTag#

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

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

Associated function meta#

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

Returns the meta data under key of the active state of state. When that state has none, returns the first one its regions have, in the order of their fields.

Associated function settle#

silk
pub effect fn settle<S: Machine<E, C, X>, E, C, X>(
    state: &mut S,
    context: &mut C,
    enq: &mut Enqueue<E, X>,
  ) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Takes one enabled eventless transition, and returns whether it took one.

Details#

The regions of the active state come first, deepest first, then the state's own transitions: its Chart.always rows, then its Chart.onDone rows, which are taken when every region of the state is in a final state.

Associated function elapse#

silk
pub effect fn elapse<S: Machine<E, C, X>, E, C, X>(
    state: &mut S,
    context: &mut C,
    path: string,
    index: u32,
    enq: &mut Enqueue<E, X>,
  ) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Takes the delayed transition index of the chart at path, if its state is active, and returns whether it was taken. path is the one the timer was started with.

Associated function isFinal#

silk
pub fn isFinal<S: Machine<E, C, X>, E, C, X>(state: &S) -> bool

Returns whether state is a final state of its chart.

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