15. Machines¶
A bike that comes into the shop goes through stages: it is received, someone looks at it, it waits for parts or
it does not, it is repaired, it is ready, and one day its owner takes it home. At each stage only some things can
happen next: nobody collects a bike that is still in pieces. Code that keeps track of that with flags, waiting?
here and ready? there, soon has a bike that is both. A machine says the stages and the ways between them
once, in a block, and then keeps the bike in exactly one of them.
States and events¶
The stages are states, and what makes the bike move from one to another is an event. A machine starts
in its initial state; each from ... to ... on ... is a way out of a state, taken when its event comes:
repair: machine [
initial received
state received []
state repairing []
state ready []
from received to repairing on start
from repairing to ready on fixed
from ready to received on again
]
send gives the machine an event, and answers with the state it is in afterwards:
>> repair/state
== received
>> send repair 'start
== repairing
>> send repair 'fixed
== ready
An event that has no way out of the current state changes nothing. The bike that is ready is not started again:
>> send repair 'start
== ready
An event that no way of the machine names at all is another thing: most likely a slip of the keyboard, so send
says so instead of losing it:
>> error? e: try [send repair 'strat]
== true
>> e/message
== "send: the machine has no way on strat; did you mean start?"
A machine with ttl, or a state with on-activity, takes any event, since an event there counts even when no
way names it.
in? says whether the machine is in a state, and can? whether it has a way out on an event from where it is:
>> in? repair 'ready
== true
>> can? repair 'again
== true
>> can? repair 'start
== false
What a state does¶
A state can run code when the machine comes into it, on-enter, and when it leaves, on-exit:
repair: machine [
initial received
state received [on-exit [print "Into the workshop"]]
state repairing [on-enter [print "Tools out"]]
from received to repairing on start
]
>> send repair 'start
Into the workshop
Tools out
== repairing
Data¶
A machine keeps its own data, in an object whose fields are given after data. Code inside the machine reads it
as data/field, and the fields an event brings as event/field. An event with fields is a block: its name, then
the fields as in an object. After the event, where gives a condition for taking a way out, and set gives the
fields of the data to change when it is taken:
repair: machine [
data [bike: none parts: 0]
initial received
state received []
state repairing [on-enter [print ["Repairing" data/bike]]]
from received to repairing on start where [event/bike <> ""] set [bike: event/bike]
]
>> send repair [start bike: ""]
== received
>> send repair [start bike: "Ada's road bike"]
Repairing Ada's road bike
== repairing
>> repair/data/bike
== "Ada's road bike"
A condition that cannot be worked out does not hold: an event with no bike field leaves the bike where it was.
The values after set are all worked out before anything changes, so set [a: data/b b: data/a] swaps them.
The machine knows its data’s fields, so a misspelt one is a mistake as soon as the machine is made, not when that line runs:
>> error? e: try [machine [data [bike: none] initial a state a [on-enter [print data/bkie]]]]
== true
>> e/message
== "machine: data has no bkie; did you mean bike?"
Other mistakes show when the machine is made too: a state or a word misspelt (with the one it may have meant), a
state no way leads to, and a choose with no event and no else out of a state with no other way out, which
would keep the machine there for good when no when holds. trebol check finds them all without running the
program.
States inside states¶
Repairing is really several stages: first someone finds out what is wrong, then the bike may wait for parts,
then it is worked on. A state can hold states of its own, with its own initial and its own ways between them.
The machine is then in both, the outer state and one inside it, and state is a path:
repair: machine [
data [parts: 0]
initial received
state received []
state work [
initial checking
state checking []
state waiting [on-enter [print [data/parts "parts ordered"]]]
state fixing []
from checking to waiting on need-parts set [parts: event/count]
from checking to fixing on fixable
from waiting to fixing on arrived
from fixing to ready on fixed
]
state ready []
state on-hold []
state cancelled []
from received to work on start
from work to on-hold on hold
from on-hold to work on resume
from work to cancelled on cancel
]
>> send repair 'start
== work/checking
>> send repair [need-parts count: 2]
2 parts ordered
== work/waiting
>> in? repair 'work
== true
in? tells whether the machine is in a state, by its name or by a path like 'work/waiting.
A way out written at the top, from work to cancelled on cancel, leaves work from whichever state inside it the
machine is in. The ways inside a state are tried first, and the ones around it catch the events they do not take.
A target is looked for first among the states next to the way out, then further out: inside work, to ready
finds the ready at the top.
When the machine comes back into a state that holds others, it goes back to the one it was in when it left, and
that state’s on-enter runs again:
>> send repair 'hold
== on-hold
>> send repair 'resume
2 parts ordered
== work/waiting
That memory is the state’s history. A state that should always start again from its initial says
no history.
Things at once¶
A bike in for a service waits for two things that have nothing to do with each other: the parts to come, and the
customer to say yes to the price. A parallel state is in all of its states at once, each with its own
states inside, and each event goes to every one of them:
service: machine [
initial waiting
parallel waiting [
state parts [
initial ordered
state ordered []
final arrived
from ordered to arrived on delivered
]
state customer [
initial asked
state asked []
final agreed
final declined
from asked to agreed on yes
from asked to declined on no
]
]
state working []
final returned
from waiting choose [
when [event/customer = 'declined] to returned
when [all [event/parts = 'arrived event/customer = 'agreed]] to working
]
]
>> service/state
== [waiting/parts/ordered waiting/customer/asked]
>> send service 'yes
== waiting/parts/ordered
>> send service 'delivered
== working
When the machine is in several states, state is a block of paths, one for each. A state of a parallel that
has ended is no longer in it. The ways out of the parallel with no event see in event how each of its states
ended: its outcome, or the name of the final state it got to, and none while it goes on. A plain
from waiting to working is taken when all of them have ended; a choose is looked at each time one ends, so
the customer saying no sends the bike back at once, parts or no parts.
An event goes first to the states of the parallel; the ways out of the parallel itself take it only when none
of them does. Leaving the parallel leaves every state still on inside it. All of them share the machine’s
data.
Choosing¶
Sometimes the same event leads to different places, depending on the data. choose tries its when conditions
in order and takes the first that holds; else is where it goes when none does:
quote: machine [
data [total: $0]
initial counting
state counting []
state small []
state ask-the-owner []
from counting choose on counted [
when [data/total < $100] to small
else to ask-the-owner
]
]
>> quote/data/total: $250
== $250.00
>> send quote 'counted
== ask-the-owner
A choose with no else, when no condition holds, does not happen. A way out with no on is taken as soon as
the machine comes into its state; a choose with no on decides then where to go.
When the place depends on a value worked out once, not on a list of conditions, select runs its block and
takes the branch for the value it gives, as switch does. The block may ask the server first:
order: machine [
data [tries: 0]
initial paying
state paying []
final paid
final cancelled given-up
from paying to paid on accepted
from paying select [data/tries: data/tries + 1 either data/tries < 3 ['again] ['stop]] on declined [
again to paying
stop to cancelled
]
]
>> send order 'declined
== paying
>> send order 'declined
== paying
>> send order 'declined
== cancelled
The block of a select runs once each time the event comes. A value with no branch, and no else, is a
mistake, and fails like one.
Time¶
Some ways out are taken by the clock, not by an event. A state with timeout starts a timer when the machine
comes into it and stops it when the machine leaves; when the time is up, the machine sends itself the event
timeout, taken like any other:
booking: machine [
initial held
state held [timeout 0:15]
state paid []
final released
from held to paid on pay
from held to released on timeout
]
>> send booking 'pay
== paid
A customer who pays within fifteen minutes keeps the bike; one who does not loses it. The time is in seconds,
a time! such as 0:15, or data/field, read as the state is entered. The timeout is taken from its own
state first, then from the ones around it, so a state with states inside can give the whole of them a time.
A machine may also have a time for silence: with ttl at the top, it expires when nobody sends it an event
for that long. Each event sent starts the time again, and its own timeouts do not count. When the time is up the
machine takes on expired, which goes to a final state; with none, it just ends, with the outcome expired.
Here the time is a tenth of a second, to see it happen:
session: machine [
ttl 0.1
initial open
state open []
final closed timed-out
from open to open on click
from open to closed on expired
]
>> wait 0.2
== none
>> session/state
== closed
>> session/outcome
== timed-out
Work that takes a while¶
A state may have work to do while the machine is in it: ask the supplier for a price, load the list of repairs.
run starts its block as a task when the machine comes into the state, and stops it
if the machine leaves first. When the block ends, the machine sends itself done, with the value the block gave
in event/value; when it fails, error, taken by on error as any failure:
prices: machine [
data [price: none]
initial asking
state asking [run [wait 0.05 $120]]
state shown []
state failed []
from asking to shown on done set [price: event/value]
from asking to failed on error
]
>> prices/state
== asking
>> wait 0.1
== none
>> prices/state
== shown
>> prices/data/price
== $120.00
A real one would fetch from the server in that block; the rest of the program goes on meanwhile.
A state may also be a whole machine of its own: invoke makes the machine of a block when the state is
entered and starts it, with with giving fields of its data. When it is done, the outer machine gets done, with
event/outcome and event/data of the inner one. The inner machine is a black box: it takes no events from
outside, so it runs on its own, by its own ways with no event, its timeouts and its run:
payment: [
data [amount: $0]
initial deciding
state deciding []
final ok authorized
final no declined
from deciding choose [when [data/amount <= $100] to ok else to no]
]
order: machine [
data [amount: $80]
initial charging
state charging [invoke payment with [amount: data/amount]]
final paid
final refused
from charging choose on done [when [event/outcome = 'authorized] to paid else to refused]
]
>> order/state
== paid
When the same work is done once for each thing in a list, invoke ... for makes one machine of the block for each
value of a block of the data. Inside with, the word after for is that value, so each machine gets its own. They
run side by side, each a black box, and the outer machine gets done when all of them are: event/outcomes and
event/data are blocks, in the order of the list. With an empty list, done comes at once:
ship: [
data [parcel: none]
initial shipping
state shipping []
final shipped success
final lost failed
from shipping choose [when [data/parcel <> "C"] to shipped else to lost]
]
delivery: machine [
data [parcels: ["A" "B" "C"] outcomes: none]
initial dispatching
state dispatching [invoke ship for parcel in data/parcels with [parcel: parcel]]
final delivered
final stuck
from dispatching choose on done [
when [parse event/outcomes [any 'success]] to delivered
else to stuck set [outcomes: event/outcomes]
]
]
>> delivery/state
== stuck
>> delivery/data/outcomes
== [success success failed]
Leaving the state stops every machine it started.
Events that come early¶
An event the state has no way out for is lost. Sometimes it only came early: the bank says the payment went
through before the shop has said the order is ready. defer holds such events until the machine is in a state
that takes them, in the order they came:
payment: machine [
defer confirmed
initial charging
state charging []
state waiting []
final done
from charging to waiting on sent
from waiting to done on confirmed
]
>> send payment 'confirmed
== charging
>> send payment 'sent
== done
A defer at the top holds the event in every state; inside a state, only while the machine is in it. An event
held keeps its fields, and a machine that is done drops the ones still held.
The end¶
A state with no way out ends the stage it is in. Inside another state, the machine is then in that outer state,
and its own ways out apply, the one with no event at once. At the top, the machine is done. A final state
says so on purpose, and may give the outcome, a word for how it ended:
sale: machine [
initial open
state open []
final paid sold
final gone lost
from open to paid on pay
from open to gone on walk-away
]
>> send sale 'pay
== paid
>> sale/done
== true
>> sale/outcome
== sold
>> send sale 'walk-away
== paid
A machine that is done takes no more events. restart starts it again from its initial state, with its data
as it was when it was made.
When something fails¶
Code in a state can fail: a request to the server that does not answer, a division by zero. Without anything
said, the error reaches whoever sent the event, as any error does. With on error, the machine takes a way out
instead, and the error is the event, so event/message says what happened:
call: machine [
initial asking
state asking [on-enter [1 / 0]]
state failed [on-enter [print ["Failed:" event/message]]]
from asking to failed on error
]
>> call/state
== failed
The Failed: line printed when the machine was made, since it starts in asking. A where after on error can
pick by the error, where [event/id = 'zero-divide]. Code that fails in an on-exit is not taken out this way:
the machine was already leaving, and the error reaches the sender.
Events sent while the machine is still busy with one, from its own code for instance, wait their turn: each event is finished, states left and entered, before the next one starts.
Keeping a machine¶
A user who fills half a form and closes the page expects to find it where it was. snapshot gives the state of a
machine as a block of plain data: the states it is in, its data, where each state with history was left, the
events held by defer, when each timer goes off and the machines it invoked. machine/from makes the machine of
the same block again where the snapshot left it, instead of starting it:
signup: [
data [email: none]
initial account
state account []
state profile [on-enter [print "Now the profile"]]
final done success
from account to profile on next set [email: event/email]
from profile to done on finish
]
form-flow: machine signup
send form-flow [next email: "ana@example.com"]
kept: mold/all snapshot form-flow
again: machine/from signup load kept
>> again/state
== profile
>> again/data/email
== "ana@example.com"
The text kept is what goes into the browser with save-local, or to the server. Coming back runs no on-enter
again: the machine was already in profile. A timeout goes off when it was going to, at once if that time has
passed while the page was closed, and a run starts over.
on-save [...] at the top of a machine runs after each event, with snapshot in it being the machine as it is
then, so the machine keeps itself:
cart: machine [
on-save [save-local 'cart snapshot]
data [items: 0]
initial shopping
state shopping []
from shopping to shopping on add set [items: data/items + 1]
]
send cart 'add
>> second find load-local 'cart 'data
== [items: 1]
A machine resumed from a snapshot of another machine, with states or data its block does not have, is an error.
One machine for every tab¶
A user may open the same app in two tabs or two windows of the browser. Each one makes its own machines, which
know nothing of each other: signing out in one leaves the other signed in. With shared name at the top, every
tab of the site that makes a machine with that name has the same one:
session: machine [
shared session
data [user: none]
initial out
state out []
state in []
from out to in on sign-in set [user: event/user]
from in to out on sign-out set [user: none]
]
send session [sign-in user: "ana"]
One tab runs the machine: the first one that made it. Only there do on-enter, on-exit, timeouts, run,
invoke and on-save happen, so a request is never made twice because the app is open twice. The other tabs
have a copy: its state and data follow the machine after each event, and send on it sends the event to the
tab that runs it and waits until it is done there, so the line after send already sees the new state. When the
tab that runs the machine is closed, another one goes on from where the machine was, as machine/from does: no
on-enter again, each timeout at its time, a run starting over.
The tabs share it through the browser (a lock and a channel named after the machine), so it reaches the tabs and
windows of the same browser for the same site, not other browsers or other computers. With machine/from, the
snapshot is taken only when no other tab runs the machine yet. The data and the fields of the events go from tab
to tab as mold/all gives them: plain values, no functions or handles. Where there is no browser, as in the
console, a shared machine is a machine like the others.
The machine as data¶
graph-of gives the states of a machine and the ways between them as a block of plain data, for a tool that
draws it or checks it. It takes the machine, or the block of one, which it reads without running anything:
g: graph-of [
initial off
state off []
state on [timeout 60]
from off to on on press
from on to off on [press timeout]
]
>> extract select g 'states 2
== [off on]
>> select select select g 'states 'on 'timeout
== 60
>> first select g 'ways
== [from off to on on [press] where none set none]
Each state has its kind (state, parallel or final), whether its level starts in it (initial),
whether the machine is in it now (on), its timeout, what it runs or invokes (an invoked machine written
in place comes as a graph of its own) and the events it holds with defer. A state inside another is named
by its path, work/checking, as state gives it; a path inside a block is found with select/only. Each way
has from, to (or choose and its branches), the events on, and its where and set blocks. trebol dev draws the machines of a running app from it (see When it goes wrong in the UI tutorial).
What’s next¶
This was the last page about the language on its own. The block that view takes on the first page of this
guide is a dialect like the machine’s, read by rules written in Trebol. The second tutorial uses it to give the
shop its screens.