silk.machine.chart.
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#
pub struct GuardA guard: one function, or guards combined with and, or and not. Built with Guards.
Field name#
pub name: string<'static>The name Guards.named gave the guard, or an empty string.
Guards#
pub struct GuardsBuilds 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#
impl GuardsAssociated function of#
pub static fn of<F>(function: F) -> GuardA guard that holds when function returns true.
Associated function named#
pub static fn named<G>(name: string<'static>, guard: G) -> GuardGives 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#
pub static fn from<G>(guard: G) -> GuardReturns guard when it is a Guard, and the guard of the function guard otherwise.
Associated function holds#
pub fn holds<C, E>(static guard: Guard, context: &C, event: &E) -> boolReturns 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#
pub static fn not(guard: Guard) -> GuardA guard that holds when guard does not.
Associated function and#
pub static fn and(first: Guard, second: Guard) -> GuardA guard that holds when both first and second hold.
Associated function or#
pub static fn or(first: Guard, second: Guard) -> GuardA guard that holds when first or second holds.
Edge#
pub struct Edge<S>One declared transition.
Field state#
pub state: string<'static>Field event#
pub event: string<'static>Field target#
pub target: Intrinsic.StaticSequence<S>The value the transition enters, or nothing for a transition that takes the event and stays.
Field guard#
pub guard: Intrinsic.StaticSequence<Guard>The guard of the transition, over functions fn(&C, &E) -> bool. Empty when unguarded.
Field history#
pub history: boolWhether the target is entered as it was when it was last left, see Chart.history.
Field meta#
pub meta: Intrinsic.StaticSequence<Meta>The meta data of the transition, see Chart.metaOn.
Field refusal#
pub refusal: Intrinsic.StaticSequence<string<'static>>The reason the state refuses the event, see Chart.refuse. Empty for any other row.
Field index#
pub index: u32The position of the row among the edges of its chart.
Leaves#
pub struct Leaves<X>The effects that one row of a chart leaves, see Chart.leaves.
Field kind#
pub kind: u8The kind of row: ROW_EDGE, ROW_ALWAYS, ROW_DONE or ROW_DELAY.
Field index#
pub index: u32The position of the row among the rows of its kind.
Field effects#
pub effects: Intrinsic.StaticSequence<X>Field condition#
pub condition: Intrinsic.StaticSequence<Guard>The guard of Chart.leavesWhen: the row leaves the effects only when it holds. Empty
for Chart.leaves.
Awaited#
pub struct AwaitedAn event that a state waits for the world to answer with, see Chart.awaits.
Field state#
pub state: string<'static>Field event#
pub event: string<'static>ROW_NONE#
pub const ROW_NONE: u8The Leaves.kind of no row.
ROW_EDGE#
pub const ROW_EDGE: u8The Leaves.kind of a row that takes an event: Chart.edges.
ROW_ALWAYS#
pub const ROW_ALWAYS: u8The Leaves.kind of an eventless row: Chart.eventless.
ROW_DONE#
pub const ROW_DONE: u8The Leaves.kind of a row taken when the regions are done: Chart.dones.
ROW_DELAY#
pub const ROW_DELAY: u8The Leaves.kind of a delayed row: Chart.delays.
Tag#
pub struct TagA tag of a state: a name that several states can share, asked for with Machines.hasTag.
Field state#
pub state: string<'static>Field tag#
pub tag: string<'static>Meta#
pub struct MetaOne entry of the meta data of a state: a text value under a key, read with
Machines.meta.
Field state#
pub state: string<'static>Field key#
pub key: string<'static>Field value#
pub value: string<'static>ANY#
pub const ANY: string<'static>The event name of a transition that any event takes.
Remember#
pub struct RememberA state whose value is kept when its chart leaves it, so a transition can come back to it.
Field state#
pub state: string<'static>Field field#
pub field: string<'static>The label of the field of the context that keeps the value, a History<S>.
Field deep#
pub deep: boolWhether the regions come back whole. When false only their own states come back, and the regions below those start again.
History#
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#
pub last: Option<S>Implementation Schema for History<S>#
impl<S: Schema> Schema for History<S>Implementation History<S>#
impl<S> History<S>Associated function empty#
pub fn empty() -> History<S>Returns a history that remembers nothing.
Method take#
pub fn take(self: &mut Self) -> Option<S>Takes the remembered value out, leaving nothing remembered.
Always#
pub struct Always<S>One declared eventless transition, taken as soon as its state is active and its condition holds.
Field state#
pub state: string<'static>Field target#
pub target: SField condition#
pub condition: Intrinsic.StaticSequence<Guard>The condition of the transition, over functions fn(&C) -> bool. Empty when it has none.
Field index#
pub index: u32The position of the row among the rows of its kind in its chart.
Delay#
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#
pub state: string<'static>Field target#
pub target: SField duration#
pub duration: u64Field index#
pub index: u32The position of this delay in its chart. With the chart's type name it identifies a timer.
Chart#
pub struct Chart<S, E, C, X>Field start#
pub start: Intrinsic.StaticSequence<S>The value the machine starts with: empty until Chart.initial gives one.
Field edges#
pub edges: Intrinsic.StaticSequence<Edge<S>>Field regions#
pub regions: Intrinsic.StaticSequence<string<'static>>The labels of the variant fields that hold a child region.
Field eventless#
pub eventless: Intrinsic.StaticSequence<Always<S>>Field dones#
pub dones: Intrinsic.StaticSequence<Always<S>>The transitions taken when every region of their state is in a final state.
Field finals#
pub finals: Intrinsic.StaticSequence<string<'static>>The labels of the final states.
Field delays#
pub delays: Intrinsic.StaticSequence<Delay<S>>Field histories#
pub histories: Intrinsic.StaticSequence<Remember>The states that are remembered when the chart leaves them.
Field tags#
pub tags: Intrinsic.StaticSequence<Tag>Field metas#
pub metas: Intrinsic.StaticSequence<Meta>The meta data of the states.
Field effects#
pub effects: Intrinsic.StaticSequence<Leaves<X>>The effects the rows leave, see Chart.leaves.
Field awaited#
pub awaited: Intrinsic.StaticSequence<Awaited>The answers the states wait for, see Chart.awaits.
Field lastKind#
pub lastKind: u8The kind and position of the row declared last, which Chart.leaves writes to.
Field lastIndex#
pub lastIndex: u32Implementation Chart<S, E, C, X>#
impl<S, E, C, X> Chart<S, E, C, X>Associated function of#
pub static fn of() -> Chart<S, E, C, X>Associated function initial#
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#
pub static fn region(chart: Chart<S, E, C, X>, field: Intrinsic.FieldName<S>) -> Chart<
S,
E,
C,
X
>Associated function on#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
pub static fn final(chart: Chart<S, E, C, X>, state: Intrinsic.VariantName<S>) -> Chart<
S,
E,
C,
X
>Associated function always#
pub static fn always(
chart: Chart<S, E, C, X>,
state: Intrinsic.VariantName<S>,
target: S,
) -> Chart<S, E, C, X>Associated function alwaysWhen#
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#
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#
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#
pub static fn isFinal(chart: Chart<S, E, C, X>, label: string<'static>) -> boolAssociated function isRegion#
pub static fn isRegion(chart: Chart<S, E, C, X>, label: string<'static>) -> boolNext#
pub union Next<S>What a transition function decided.
Pass#
PassNot handled here: the parent state gets the event.
Stay#
StayHandled without a state change.
To#
ToHandled by moving to state.
Field state#
pub state: SEnqueue#
pub struct Enqueue<E, X>What a step queued: events for the machine itself and effects to perform after the commit.
Field raised#
pub raised: List<E>Field effects#
pub effects: List<X>Field timers#
pub timers: List<TimerChange>Timers started and cancelled by the states entered and left, in order.
Field clock#
pub clock: u64The machine's clock at this step, in nanoseconds of wall clock time. A handler that starts a child machine passes it on.
TimerChange#
pub union TimerChangeA timer of a delayed transition that a step started or cancelled.
Start#
StartField path#
pub path: string<'static>Field index#
pub index: u32Field duration#
pub duration: u64Cancel#
CancelField path#
pub path: string<'static>Field index#
pub index: u32Implementation Enqueue<E, X>#
impl<E, X> Enqueue<E, X>Associated function make#
pub fn make() -> Enqueue<E, X>Associated function at#
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#
pub effect fn raise(self: &mut Self, event: E) -> ()
! OutOfMemoryError
? &mut AllocatorMethod perform#
pub effect fn perform(self: &mut Self, effect_: X) -> ()
! OutOfMemoryError
? &mut AllocatorMachine#
pub interface Machine<E, C, X>Operation chart#
static fn chart() -> Chart<Self, E, C, X>Operation handle#
effect fn handle(state: &Self, context: &mut C, event: &E, enq: &mut Enqueue<E, X>) -> Next<Self>
! OutOfMemoryError
? &mut AllocatorThe transition function of this level. The default handles nothing.
Operation enter#
effect fn enter(state: &Self, context: &mut C, enq: &mut Enqueue<E, X>) -> ()
! OutOfMemoryError
? &mut AllocatorOperation exit#
effect fn exit(state: &Self, context: &mut C, enq: &mut Enqueue<E, X>) -> ()
! OutOfMemoryError
? &mut AllocatorOperation absorb#
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#
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#
effect fn tick(state: &Self, context: &mut C, now: u64, enq: &mut Enqueue<E, X>) -> ()
! OutOfMemoryError
? &mut AllocatorRuns 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#
pub static fn hasGuard<S>(edge: Edge<S>) -> boolhasCondition#
pub static fn hasCondition<S>(always: Always<S>) -> boolMachines#
pub struct MachinesImplementation Machines#
impl MachinesAssociated function start#
pub fn start<S: Machine<E, C, X>, E, C, X>() -> SThe initial state of S: the value its chart gives to Chart.initial.
Associated function enterAll#
pub effect fn enterAll<S: Machine<E, C, X>, E, C, X>(
state: &S,
context: &mut C,
enq: &mut Enqueue<E, X>,
) -> ()
! OutOfMemoryError
? &mut AllocatorRuns the entry functions of state, parents before children, and starts the timers of
the states entered.
Associated function exitAll#
pub effect fn exitAll<S: Machine<E, C, X>, E, C, X>(
state: &S,
context: &mut C,
enq: &mut Enqueue<E, X>,
) -> ()
! OutOfMemoryError
? &mut AllocatorRuns the exit functions of state, children before parents, and cancels the timers of
the states left.
Associated function dispatch#
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 AllocatorOffers 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#
pub fn awaiting<S: Machine<E, C, X>, E, C, X>(state: &S) -> boolReturns 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#
pub fn awaits<S: Machine<E, C, X>, E, C, X>(state: &S, event: &E) -> boolReturns 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#
pub fn isAnswer<S: Machine<E, C, X>, E, C, X>(event: &E) -> boolReturns 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#
pub effect fn active<S: Machine<E, C, X>, E, C, X>(
state: &S,
names: &mut List<string<'static>>,
) -> ()
! OutOfMemoryError
? &mut AllocatorAppends 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#
pub effect fn states<S: Machine<E, C, X>, E, C, X>(names: &mut List<string<'static>>) -> ()
! OutOfMemoryError
? &mut AllocatorAppends 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#
pub fn contenders<S: Machine<E, C, X>, E, C, X>(state: &S, context: &C, event: &E) -> u32Returns 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#
pub fn hasTag<S: Machine<E, C, X>, E, C, X>(state: &S, tag: string) -> boolReturns whether an active state of state, at any depth, has the tag tag.
Associated function meta#
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#
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 AllocatorTakes 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#
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 AllocatorTakes 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#
pub fn isFinal<S: Machine<E, C, X>, E, C, X>(state: &S) -> boolReturns 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.