3.1 Execution semantics
The rules in this section say what the runtime does with a state machine while an environment runs: which states are active, when ENTRY and DO blocks run, which transition fires, what actions do to the model and how events travel. The syntax of the constructs is in 2.3 KStates. The tables of ticks in this section come from runs of the runtime with the state machines shown here.
3.1.1 Example state machine#
Most examples use the lamp. The metamodel has a Lamp with a property mode, a Bulb in the relation bulb and a Switch in the relation control. The model has the lamp lamp, its bulb bulb and the wall switch wallSwitch, as in the IDE example examples/lamp. The event definitions have the events press and dim, and dim carries the property bright:
type "press" "Presses the wall switch" {
}
type "dim" "Turns the dimmer one step" {
prop("bright", "boolean")
}
The state machine of the lamp in this section has the inner states full and dimmed with fixed watts:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" {
ENTRY {
SET("mode", "off")
SET("bulb->lit", "false")
SET("bulb->watts", "0")
}
}
STATE "on" {
ENTRY {
SET("mode", "on")
SET("bulb->lit", "true")
}
STATE "full" {
ENTRY { SET("bulb->watts", "40") }
}
STATE "dimmed" {
ENTRY { SET("bulb->watts", "20") }
}
}
}
TRANSITIONS {
TRANSITION "off" -> "full" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "on" -> "off" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "full" -> "dimmed" {
CONDITION { EVENT("switch", "dim") }
}
TRANSITION "dimmed" -> "full" {
CONDITION {
EVENT("switch", "dim")
VALUE("event->bright")
}
}
}
}
The wall switch has its own state machine, attached to wallSwitch. It reacts to the same press events:
STATEMACHINE ATTACHED TO "Switch" {
STATES {
INITIAL STATE "down" { }
STATE "up" {
ENTRY {
SET("position", "up")
APPEND("presses", "up")
}
}
STATE "back down" {
ENTRY {
SET("position", "down")
APPEND("presses", "down")
}
}
}
TRANSITIONS {
TRANSITION "down" -> "up" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "up" -> "back down" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "back down" -> "up" {
CONDITION { EVENT("switch", "press") }
}
}
}
3.1.2 Ticks#
An environment runs in ticks. Ticks are numbered from 1 on the first start; a start after a stop goes on with the next number, as 3.1.13.9 Stop and start, forcing and clients describes. In one tick the runtime does these steps in this order:
-
It applies the states that clients forced with
setActiveStatesince the last tick, as 3.1.11 Forcing a state describes. - With the feature EventRecording recording, it hands the events that clients sent since the last tick to the state machines and records them under the number of this tick. With the feature EventInjection injecting, it hands over the injected events that are due. Both are in 3.2 Runtime features.
- With the feature TickLimit on, it counts this tick for every active state.
- It removes events whose time to live is over.
- It runs one step of every state machine instance, one after the other, in the order of 3.1.13.2 The order of the steps: the attached state machines in the order of their first upload, then the instances of attachable state machines. An instance that ended earlier in the tick does no step. With the feature TrueParallel on, the branches of a split state machine do their steps at the same time, and this step ends when all of them are done.
- It reports the active states of every state machine whose active states changed in this tick. In the first tick after the first start it reports every state machine.
- It lets the instances that ended in this tick leave and the instances that rules asked for join, as 3.1.13.3 When instances join and leave describes.
The tick delay is the least time from the start of one tick to the start of the next one, in milliseconds. A tick that takes 30 ms with a tick delay of 500 ms is followed by a wait of 470 ms. A tick that takes longer than the tick delay is followed by the next tick at once. The environment takes the tick delay from setTickDelay or, without it, from the option engine.defaultTickDelayMs of 3.3 Running the runtime.
Events that clients send without EventRecording reach the state machines as soon as they arrive. The runtime looks for them every 10 ms, also in the middle of a tick, so a state machine later in the order can see an event that an earlier one did not see in the same tick.
The state machines of one environment run on one thread, one after the other. A state machine that waits for Python in an EVAL holds up all others of its environment. The feature TrueParallel gives each branch of a split a thread of its own, as 3.2.9 TrueParallel describes.
3.1.3 Active states#
The active states of a state machine form a stack: an outer state, the state inside it, and so on down to the innermost active state. With the lamp in dimmed, the stack is on, dimmed. Outside a split, a state machine has one stack. In a split it has one stack per branch, as 3.1.8 Splits and joins describes. Clients see the stack in the message stateChange of 3.5 WebSocket.
3.1.3.1 Initial state#
At the start, the runtime builds the stack level by level, by the rule of 2.3.2.2 The initial state, which the checks of dsl-tools and the IDE use as well. On each level it takes the state that is marked INITIAL or that holds the marked state somewhere inside it, and the first state of the level when there is none. It goes on below the chosen state while that state has inner states, and stops at a state without inner states.
The reader of KStates allows exactly one INITIAL in a state machine (check kstates.initial-state-count). So the state machine starts in the marked state and in every state around it, wherever these stand among their siblings. In the following text, the stack at the start is on, dimmed, although off is the first top level state, because the mark sits inside on:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
STATE "off" { }
STATE "on" {
STATE "full" { }
INITIAL STATE "dimmed" { }
}
}
TRANSITIONS { }
}
With INITIAL STATE "on" and no mark inside it, the stack at the start is on, full. All states of the start stack are entered in tick 1, from the outside in. A container state on the way counts as a state with inner states, so the start goes on into its fragment, as 3.1.14.3 Entering a container state describes.
3.1.3.2 Entering states#
A state that becomes active is entered: its ENTRY block runs once. The ENTRY blocks of the states that a transition enters run in the tick after the transition, from the outermost to the innermost entered state. The ENTRY blocks of the start stack run in tick 1.
The DO block of the innermost active state runs once in every tick in which no transition fired before it, also in the tick in which the state was entered. The DO blocks of the outer states never run while an inner state is active.
States have no exit blocks. Nothing runs when a state is left.
Where the runtime goes for each way of entering a state and each kind of target, and in which tick, is gathered in 3.1.15 Where the engine goes.
3.1.3.3 Steps of a tick#
In its step of a tick, a state machine does these things in this order. The first transition that fires ends the step.
- With the feature History on, it notes the active inner states of every state that has a history.
- It enters the states not yet entered, from the outside in. Before each ENTRY block a breakpoint on the entry of the state can halt the run. After each ENTRY block that has at least one action, it looks for a transition that can fire, over the whole stack. If one fires, the ENTRY blocks of the states further inside do not run.
- With the feature TickLimit on, it fires the timeout of a state whose time is over.
- With the feature History on, it leads on into the remembered inner state when the innermost active state has a history and something to remember.
- It runs the DO block of the innermost active state.
- It looks for a transition that can fire and fires it.
- When no transition fired, it consumes the events that a transition of an active state waited for but could not use, as 3.1.7.3 Consumption describes.
The lamp and the switch, with a press sent before tick 3, a dim with bright false before tick 5 and a press before tick 7:
| Tick | Event | lamp | wallSwitch |
|---|---|---|---|
| 1 | ENTRY of off runs. Stack off | Stack down | |
| 2 | Stack off | Stack down | |
| 3 | press | "off" -> "full" fires. Stack on, full | "down" -> "up" fires. Stack up |
| 4 | ENTRY of on and of full run. watts is 40 | ENTRY of up runs | |
| 5 | dim | "full" -> "dimmed" fires. Stack on, dimmed | Stack up |
| 6 | ENTRY of dimmed runs. watts is 20 | Stack up | |
| 7 | press | "on" -> "off" fires. Stack off | "up" -> "back down" fires |
| 8 | ENTRY of off runs. watts is 0 | ENTRY of back down runs |
After tick 8 the list presses of the switch is ["up", "down"].
A transition can fire right after an ENTRY block. In the next run the dim arrives while the lamp is off, waits there and fires right after the ENTRY of on. The ENTRY of full never runs:
| Tick | Event | lamp |
|---|---|---|
| 2 | dim | Stack off. No transition of off waits for dim, so the event stays |
| 4 | press | "off" -> "full" fires. Stack on, full |
| 5 | ENTRY of on runs, then "full" -> "dimmed" fires on the waiting dim. Stack on, dimmed | |
| 6 | ENTRY of dimmed runs. watts is 20 |
3.1.4 Transitions#
3.1.4.1 Which transition fires#
The runtime looks for a transition from the innermost active state outwards. For each state it tries the transitions that start at this state, TRANSITION and SPLIT, in the order of the file. The first one whose condition holds fires. At most one transition fires per stack in one step. A transition that starts at an outer state applies while any of its inner states is active: "on" -> "off" switches the lamp off from full and from dimmed. A transition of an inner state wins over one of an outer state when both could fire.
A JOIN is tried before all other transitions, as 3.1.8 Splits and joins describes.
3.1.4.2 Conditions#
A transition without CONDITION block fires whenever it is tried. A condition holds when all of its clauses hold.
EVENT("switch", "press") holds when an event named press in the domain switch is there for this state machine. When several such events are there, the runtime tries them from the oldest to the newest and takes the first one for which the other clauses hold. The other clauses see this event as event. A condition has at most one EVENT clause. It may stand anywhere among the clauses; the runtime treats it the same as a first clause.
VALUE("path") holds when the path leads to the boolean true or to the string true in any case. VALUE("true") always holds and VALUE("false") never. A path starts at the object of the state machine, VALUE("bulb->lit"), or at the event, VALUE("event->bright"). A path that leads nowhere makes the clause false.
EVAL { ... } holds when its Python code returns True. Any other result and any error make it false; the error goes to the console of the runtime. 3.1.6 EVAL and macros has the details.
A condition without EVENT clause sees as event the event that led into the current state, as 3.1.7.5 Scoped events describes.
DONE holds when the container state the transition leaves rests on a final state of its fragment, as 3.1.14.5 Final states and DONE describes.
In the lamp, "dimmed" -> "full" needs a dim with bright true. A dim with bright false in dimmed fires nothing and is consumed:
| Tick | Event | lamp |
|---|---|---|
| 2 | press | "off" -> "full" fires |
| 3 | ENTRY of on and full run | |
| 4 | dim, bright false | "full" -> "dimmed" fires |
| 5 | ENTRY of dimmed runs | |
| 6 | dim, bright false | Nothing fires. The event is consumed |
| 7 | dim, bright true | "dimmed" -> "full" fires |
| 8 | ENTRY of full runs. Stack on, full |
3.1.4.3 Where a transition leads#
After a transition, the stack is the path from the top level down to the target state. The runtime does not descend into the inner states of the target: "full" -> "on" leaves the stack on, and from then on the DO block of on runs. A container state is the one exception: the runtime goes down into its fragment, as 3.1.14.3 Entering a container state describes.
The runtime enters the states of the new stack that were not on the old stack. A transition from a state to itself, and a transition from a state to one of its outer states, enter the target again together with the state around it. With the stack on, full, the transition "full" -> "full" enters on and full again, and "full" -> "on" enters on again. A transition to itself on the top level, "on" -> "on", enters on again.
3.1.4.4 NOT LOOPING#
A transition marked NOT LOOPING does not fire when it was the last transition that fired in its stack. Then the runtime tries the next one. With this state machine
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "on" {
ENTRY { SET("mode", "on") }
}
}
TRANSITIONS {
TRANSITION "off" -> "on" { }
TRANSITION "on" -> "on" NOT LOOPING { }
TRANSITION "on" -> "off" { }
}
}
the lamp runs in a circle of three ticks:
| Tick | lamp |
|---|---|
| 1 | "off" -> "on" fires |
| 2 | ENTRY of on runs, then "on" -> "on" fires |
| 3 | ENTRY of on runs. "on" -> "on" was the last transition, so "on" -> "off" fires |
| 4 | "off" -> "on" fires |
3.1.5 Actions#
3.1.5.1 Blocks and errors#
An ENTRY or DO block runs its actions in order. The changes of one block reach the clients together, after the block, as the messages objectChanged and objectDeleted of 3.5 WebSocket.
An action that fails stops the rest of its block. The changes of the actions before it stay. The runtime writes the error to its console and to the trace log, and the run goes on. In this ENTRY block the second action fails because Bulb has no property colour. mode becomes broken and lit stays as it was:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" {
ENTRY {
SET("mode", "broken")
SET("bulb->colour", "red")
SET("bulb->lit", "true")
}
}
}
TRANSITIONS { }
}
The trace log has the line:
ACTION_ERROR: Error in onEntry for state 'off': 'colour' on 'Bulb' is not a scalar property (use SETOBJ for relations)
3.1.5.2 Values on the right side#
The value of an action is a string, an EVAL block or a MACRO call.
A string is read as the type of the property it goes to. For a property of type number, "40" is the number 40, and a string that is no number is an error of the action. For a property of type boolean, the string must be true or false. For a property of type string, the string is taken as it is.
An EVAL block or a MACRO call computes the value, as 3.1.6 EVAL and macros describes. When it returns nothing, the action does nothing.
3.1.5.3 Properties and lists#
A path names a property of the object of the state machine, "mode", or of an object reached over relations, "bulb->watts".
| Action | What it does |
|---|---|
SET("path", value) | Sets a property that holds one value |
APPEND("path", value) | Adds the value at the end of a list property. A list that has no value yet is created |
SETLIST("path", value) | Replaces the whole list. A string gives a list of one element, an EVAL or MACRO gives the list it returns |
DROPLIST("path") | Removes the list property |
STATEMACHINE ATTACHED TO "Switch" {
STATES {
INITIAL STATE "down" {
ENTRY {
SET("position", "down")
SETLIST("presses", "reset")
APPEND("presses", "down")
}
}
}
TRANSITIONS { }
}
After the ENTRY block, presses is ["reset", "down"].
3.1.5.4 Objects and relations#
| Action | What it does |
|---|---|
SETOBJ("source", "relation", value) | Sets a relation that holds one object |
APPENDOBJ("source", "relation", value) | Adds an object to a relation that holds a list |
DROPOBJ("path") | Removes an object from the model |
SETOBJ(...) ATTACH name, APPENDOBJ(...) ATTACH name | Creates the object with an instance of the attachable state machine name |
EXCHANGE("path", name) | Gives the object at the path an instance of the attachable state machine name |
The source is the path to the object that owns the relation. "" and "self" stand for the object of the state machine.
A has relation needs a new object. The value is an EVAL or MACRO that returns the object as a dictionary with the properties of its type. The runtime builds the object; its key is the entry __id__ of the dictionary or, without it, gen_<Type>_<n>. A dictionary whose __id__ is the key of an object that already exists changes that object in place. SETOBJ on a has relation removes the object that was there before, with everything it holds.
A knows relation needs an object that exists. The value is a string with the path from the object of the state machine to that object, or an EVAL or MACRO that returns a dictionary with its __id__ or the key as a string.
The type of the object must be the type of the relation. A has relation given an existing object, a knows relation given a new one, and an object of the wrong type are errors of the action.
A dictionary with the __id__ of an existing object changes that object in place, wherever an EVAL or a MACRO returns it, also nested inside another dictionary. Its properties take the values of the dictionary. A has relation in the dictionary holds afterwards the objects the dictionary lists: an object it held before and the dictionary does not list leaves the model as with DROPOBJ, with everything it holds, and a dictionary without __id__, or with an __id__ no object has, is a new object. An object that another object holds cannot be listed; that is an error of the action. A knows relation in the dictionary must list objects that exist. So the lamp is given a new bulb, and the old bulb is removed, by:
SETOBJ("self", "light", EVAL { return {"__id__": "lamp", "bulb": {"maxWatts": 60, "watts": 0}} })
where light is a knows relation of the object of the state machine to the lamp.
DROPOBJ removes the object at the path with everything it holds. The runtime removes every knows reference to a removed object. The object of the state machine itself cannot be removed by its own path. The state machine instances of all removed objects end, also those of the objects that a replacing SETOBJ removes. New objects get the instances their types behave after, and ATTACH and EXCHANGE give objects other instances, as 3.1.13 State machine management and lifecycle describes. The lamp of the IDE example drops its spare bulb when it breaks:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "working" { }
STATE "broken" {
ENTRY {
DROPOBJ("spare")
SET("mode", "broken")
}
}
}
TRANSITIONS {
TRANSITION "working" -> "broken" {
CONDITION { EVENT("service", "smash") }
}
}
}
3.1.5.5 Raising events#
EVENT("domain", "name") as an action raises an event without payload. It is on the bus at once with the time to live of the environment. State machines later in the order see it in the same tick, the state machine that raised it sees it when it next looks for a transition. In this run the switch, which comes first, raises press when it enters up, and the lamp reacts in the same tick:
STATEMACHINE ATTACHED TO "Switch" {
STATES {
INITIAL STATE "down" { }
STATE "up" {
ENTRY {
SET("position", "up")
EVENT("switch", "press")
}
}
}
TRANSITIONS {
TRANSITION "down" -> "up" {
CONDITION { EVENT("button", "push") }
}
}
}
| Tick | Event | wallSwitch | lamp |
|---|---|---|---|
| 2 | push in domain button | "down" -> "up" fires | Stack off |
| 3 | ENTRY of up runs and raises press | "off" -> "full" fires | |
| 4 | Stack up | ENTRY of on and full run |
3.1.5.6 IF IN SCOPE and WITH#
IF IN SCOPE("path", ...) { ... } runs its actions only when every path leads to a value. A path into event needs a scoped event that has this property. A property with the value false counts as a value.
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "on" {
ENTRY {
IF IN SCOPE("event->bright") {
SET("mode", "dimmed by event")
}
}
}
}
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "dim") }
}
}
}
A dim switches the lamp on and sets mode to dimmed by event.
WITH MACRO("name", ...) AS "binding" { ... } computes the macro once and runs the actions in the block. The actions read the result as $(binding) and $(binding->property) in their EVAL blocks and paths.
3.1.6 EVAL and macros#
An EVAL block holds Python code that ends with return. Before the code runs, the runtime replaces every $(path) by the value at the path as a Python value. A number becomes a Python number, a string a Python string, a boolean True or False, a list a Python list and an object a dictionary with the entries __id__, __type__, its properties and its relations, with the objects of the relations as dictionaries again. $(event->bright) reads the event in scope. A path that cannot be followed, such as event->bright with no event in scope, is an error of the EVAL.
The value that the code returns goes to the action or the condition. In a condition only True makes the clause hold.
An EVAL whose code is one return of numbers, True, False, arithmetic, comparisons, and, or, not and parentheses, once the paths are filled in, is computed by the runtime itself. Every other EVAL runs in Python. The runtime calls python3, python or py, whichever it finds first on the path. Code with import or def runs in a Python process that stays open for the run of the environment. With the feature TrueParallel, branches that run such code at the same time each get a process of their own.
The lamp of the IDE example computes its watts this way:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "on" {
ENTRY {
SET("bulb->watts", EVAL { return $(bulb->maxWatts) })
}
}
}
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION {
EVENT("switch", "press")
EVAL { return $(bulb->watts) + 10 <= $(bulb->maxWatts) }
}
}
}
}
A macro is a named piece of Python code in the MACROS block of the file. MACRO("name", "path", ...) calls it. Each argument is a path from the object of the state machine, from event or from a binding of WITH, and its value is handed over for the parameter of the same place in TAKES. In the code of the macro, $(parameter) is the value of the parameter and $(parameter->property) reads into it. The result must fit the type in RETURNS. Inside Python code, @name(arguments) calls another macro of the file as a Python function.
3.1.7 Events#
3.1.7.1 Domains and names#
Every event has a domain and a name, switch and press. A transition waits for an event with EVENT("switch", "press"). Events come from clients over the WebSocket, from the feature EventInjection and from the action EVENT. The domain is free text. Clients that listen to a domain get every event of that domain pushed, as 3.5 WebSocket describes.
3.1.7.2 Time to live#
An event expires when it is older than its time to live. The time to live of an environment comes from setEventTtl or, without it, from the option engine.defaultEventTtlMs. A time to live of 0 means that events never expire. The runtime removes expired events at the start of each tick and every 10 ms in between.
3.1.7.3 Consumption#
Each state machine sees every event once. An event that the lamp consumed is still there for the switch. Within one state machine an event is consumed in one of these ways:
-
It fires a transition. The option
engine.eventConsumptionOnFireistrueby default. Withfalse, the event that fired a transition stays and can fire further transitions in later ticks. - No transition fired in the step, and a transition of an active state waits for an event with this domain and name. Then the event is consumed, also when the other clauses of the transition did not hold.
- It expires.
An event that no transition of the active states waits for stays until it expires, and fires a transition when a state that waits for it becomes active within its time to live. The dim in the second table of 3.1.3.3 Steps of a tick waits in off this way.
3.1.7.4 Payloads#
An event from a client carries a payload as JSON or as KModel text. The runtime reads it against the type of the event definitions that has the name of the event. A dim with the payload {"bright": true} gives the event the property bright with the value true. A payload that cannot be read leaves the event without properties: JSON that does not fit the event type, and KModel text with any error of the KModel reader, such as a syntax error, an unknown property or a value of the wrong type. The runtime writes the errors to its console. The event still fires transitions by its name, paths into event lead nowhere, and the run goes on. The forms of the message are in 3.5 WebSocket.
Events raised with the action EVENT have no payload. Events replayed by EventInjection are not read against the event definitions, so paths into them lead nowhere.
3.1.7.5 Scoped events#
The event that fired a transition becomes the scoped event of the target state. While this state is active, its ENTRY and DO blocks, its IF IN SCOPE paths and the conditions without EVENT clause read it as event. An inner state that was entered without an event of its own reads the scoped event of the nearest outer state. A state loses its scoped event when it is left.
3.1.7.6 Several state machines#
All state machines of an environment share one bus of events. Each takes the events it waits for and consumes them for itself only. The lamp and the switch both react to the same press in the same tick in the first table of 3.1.3.3 Steps of a tick. This holds for every instance: two objects with instances of the same attachable state machine consume their events each for itself, and an instance that joins during the run sees the events on the bus whose time to live is not over.
3.1.8 Splits and joins#
A SPLIT with its condition holding replaces the one stack of the state machine with one branch per target state. Each branch has the stack from the top level down to its target and enters its states in the next tick. The event that fired the split is the scoped event of every target.
While the state machine has branches, it first tries every JOIN. A join fires when its condition holds and each of its source states is active in a different branch, with exactly as many branches as the join has sources. Then the state machine has one stack again, the path to the target of the join, and the other branches do no more step in this tick. When no join fires, each branch does its step as in 3.1.3.3 Steps of a tick, one branch after the other in the order of the targets of the split, on the one thread of the environment. With the feature TrueParallel on, the branches do their steps at the same time on threads of their own, as 3.2.9 TrueParallel describes. The stack that clients see is the stacks of all branches one after the other.
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "test bulb" {
ENTRY { SET("bulb->lit", "true") }
}
STATE "bulb ok" {
ENTRY { SET("bulb->lit", "false") }
}
STATE "test switch" { }
STATE "check position" { }
STATE "switch ok" {
ENTRY { SET("mode", "tested") }
}
STATE "on" {
ENTRY { SET("mode", "on") }
}
}
TRANSITIONS {
SPLIT "off" -> "test bulb", "test switch" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "test bulb" -> "bulb ok" { }
TRANSITION "test switch" -> "check position" { }
TRANSITION "check position" -> "switch ok" { }
JOIN "bulb ok", "switch ok" -> "on" { }
}
}
| Tick | Event | Branch 1 | Branch 2 |
|---|---|---|---|
| 2 | press | The split fires. Stack test bulb | Stack test switch |
| 3 | ENTRY of test bulb runs, then "test bulb" -> "bulb ok" fires | "test switch" -> "check position" fires | |
| 4 | ENTRY of bulb ok runs | "check position" -> "switch ok" fires | |
| 5 | The join fires. Stack on | ||
| 6 | ENTRY of on runs |
The ENTRY of switch ok never runs, because the join fires before the branch enters it, so mode never becomes tested.
A join sees the events of all branches. It consumes its event for the new stack only.
A split into container states goes down into each of them, so every branch starts inside its fragment. DONE on a join waits for all container states among its sources, as 3.1.14.5 Final states and DONE describes.
The trace log gives every branch a path number of its own, as 3.3.5 Trace log describes. In the example the lamp runs on path 0 up to the split, branch 1 on path 1, branch 2 on path 2, and the stack on after the join on path 3. A second split would start paths 4 and 5. Every line of a branch names its path, so the lines of the two branches can be told apart, also when they interleave with TrueParallel on.
3.1.9 Histories#
With the feature History on, a state marked SHALLOW HISTORY or DEEP HISTORY remembers where it was. At the start of each step the runtime notes, for every active state with a history that has an active inner state, the inner state: the state right inside it for SHALLOW HISTORY, the innermost active state for DEEP HISTORY. When a transition later leads into the state itself, the state is entered, and in the same tick the runtime leads on into the remembered state. That ends the step; the remembered state is entered in the next tick. Each state machine instance has its own histories. A history stays when the environment is stopped and started again, and is forgotten when its instance leaves. Without the feature History, the marks have no effect. A container state with a history goes to the remembered state at once, as 3.1.14.6 Histories, tick limits and breakpoints describes.
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
STATE "off" {
ENTRY { SET("mode", "off") }
}
INITIAL SHALLOW HISTORY STATE "on" {
ENTRY { SET("mode", "on") }
STATE "full" {
ENTRY { SET("bulb->watts", "40") }
}
STATE "dimmed" {
ENTRY { SET("bulb->watts", "20") }
}
}
}
TRANSITIONS {
TRANSITION "on" -> "off" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "full" -> "dimmed" {
CONDITION { EVENT("switch", "dim") }
}
}
}
| Tick | Event | lamp |
|---|---|---|
| 1 | ENTRY of on and full run | |
| 2 | dim | "full" -> "dimmed" fires |
| 3 | ENTRY of dimmed runs | |
| 4 | press | "on" -> "off" fires |
| 5 | ENTRY of off runs | |
| 6 | press | "off" -> "on" fires. Stack on |
| 7 | ENTRY of on runs, then the history leads on to dimmed | |
| 8 | ENTRY of dimmed runs. watts is 20 |
3.1.10 Tick limits#
With the feature TickLimit on, a TICK LIMIT block counts the ticks of its state. The tick in which the ENTRY block of the state runs is its first tick. Each state machine instance counts its own ticks. The counts stay when the environment is stopped and started again, and are forgotten when the instance leaves. Without the feature TickLimit, TICK LIMIT blocks have no effect.
DELAY: n TICKS holds the state for its first n ticks. A transition that would leave the state in that time fires nothing. Its event stays, and no other transition fires in this step. TIMEOUT: AFTER n TICKS TRANSITION TO "state" leads to the named state in the tick after the first n ticks, after the ENTRY blocks and before the DO block. When several active states have a timeout that is due, the innermost one wins. A delay holds back a timeout as well.
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" {
TICK LIMIT { DELAY: 2 TICKS }
ENTRY { SET("mode", "off") }
}
STATE "on" {
TICK LIMIT { TIMEOUT: AFTER 3 TICKS TRANSITION TO "off" }
ENTRY { SET("mode", "on") }
}
}
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "on" -> "off" {
CONDITION { EVENT("switch", "press") }
}
}
}
| Tick | Event | lamp |
|---|---|---|
| 1 | ENTRY of off runs. First tick of off | |
| 2 | press | Second tick of off. The delay holds the transition, the press stays |
| 3 | "off" -> "on" fires on the waiting press | |
| 4 | ENTRY of on runs. First tick of on | |
| 5 | Second tick of on | |
| 6 | Third tick of on | |
| 7 | The timeout leads to off | |
| 8 | ENTRY of off runs | |
| 9 | press | Second tick of off. The delay holds the transition |
| 10 | "off" -> "on" fires |
3.1.11 Forcing a state#
The route setActiveState of 3.4 HTTP API puts a state machine into a named state while the environment runs. The runtime applies it at the start of the next tick. The stack becomes the path to the named state, with one branch. A state inside a container state is named with its qualified name, such as self test/lit, and a container state is gone down into as by a transition, see 3.1.14.3 Entering a container state. No ENTRY block runs. The runtime drops every event of the domain whose name is the key of the object of the state machine and every client event that has not reached the state machines yet. The state machine is the instance the object has in the latest tick, also one that joined during the run. In the trace log the forced state ends the paths the state machine ran and starts the next path; the line Forced state names both.
3.1.12 Errors in a tick#
An error in an action stops its block, as 3.1.5.1 Blocks and errors describes. An error in an EVAL or VALUE clause makes the clause false. In all these cases the run goes on. The runtime writes the error to its console; errors of actions also go to the trace log as ACTION_ERROR.
3.1.13 State machine management and lifecycle#
An environment runs state machine instances. An instance is one state machine running on one object, with its own stack, branches, events, histories, tick counts and breakpoint overrides. One object has at most one instance at a time, so the key of the object names the instance. This section tells when instances begin, in which order they step and when they end. How to write attachable state machines, behaves after, ATTACH and EXCHANGE is in 2.3.11 State machine management and lifecycle.
3.1.13.1 Where instances come from#
An environment holds two kinds of state machines. An attached state machine, STATEMACHINE ATTACHED TO "Type", is uploaded with attachedTo and belongs to the object with that key. An attachable state machine, STATEMACHINE "name" ATTACHABLE TO "Type", ..., is uploaded without attachedTo and kept as a definition under its name. 3.4.3 Uploads has both forms.
An object gets an instance of a definition in four ways:
-
its type
behaves afterthe definition and the object is in the model when the environment starts; -
its type
behaves afterthe definition and a rule creates the object; -
an
ATTACHclause names the definition for the object its rule creates; -
EXCHANGEgives the object the definition.
An attached state machine wins over the behaves after of the type of its object. An ATTACH clause wins over the behaves after of the type of the object the rule creates. Every new instance starts in its initial state, as 3.1.3.1 Initial state describes.
runEnvironment refuses an environment in which a type of the metamodel behaves after a name that no attachable state machine has, or after one that does not list the type, as 3.4.7 Running shows. So every object of such a type can get its instance, also one that a rule creates later.
3.1.13.2 The order of the steps#
The instances step one after the other in a fixed order:
- the attached state machines, in the order of their first upload;
-
the instances for
behaves afterof the objects in the model at the start, in the order of the objects in the model: an object first, then the objects it holds, relation by relation, as the KModel text writes them; - the instances that joined during the run, in the order in which they joined.
An instance that EXCHANGE gives an object takes the place of the instance it replaces. An object without an instance that gets one through EXCHANGE joins at the end.
3.1.13.3 When instances join and leave#
The order changes only at the end of a tick, after every instance has done its step. A rule that creates an object asks for the instances of the new objects, and EXCHANGE asks for the new instance. At the end of the tick these instances join. Each does its first step in the next tick, so its ENTRY blocks run there.
An instance ends at the moment its object leaves the model or EXCHANGE replaces it. It does no further step from that moment: an instance later in the order skips its step in this tick. An instance that ends during its own action block, because the block removed an object that holds its own object or exchanged its own state machine, finishes the block, and then its step ends without looking for a transition. At the end of the tick the ended instances leave the order. Its histories, tick counts and the overrides of breakpoints for its object leave with it.
The same holds with the feature TrueParallel on, where the branches of a split create, remove and exchange objects at the same time on threads of their own: the requests of all branches are collected and carried out together at the end of the tick. A request for an object that is no longer in the model at that point is dropped. With TrueParallel on, an instance that ends during a step stops each of its branches after the block that branch is in.
3.1.13.4 New objects#
SETOBJ and APPENDOBJ on a has relation create an object and every object it holds, as 3.1.5.4 Objects and relations describes. A dictionary with the __id__ of an existing object creates the new objects it lists in a has relation in the same way. Every new object whose type behaves after a definition gets an instance of it. With ATTACH name after the rule, the object the rule creates gets an instance of name instead; the objects it holds still follow their types.
The runtime reads the name of ATTACH before it computes the new object and checks it against the type of the relation. A name that fails is an error of the action, and the rule creates nothing.
3.1.13.5 EXCHANGE#
EXCHANGE("path", name) ends the instance of the object at the path and gives the object an instance of name. The path is read like the path of DROPOBJ: it starts at the object of the state machine and self is no keyword in it. The object at the path may be the object of the state machine itself, reached over relations; then the instance finishes its block and leaves, as 3.1.13.3 describes. EXCHANGE with the name of the running definition starts the object again in the initial state of a new instance. Two EXCHANGE on one object in one tick leave the object with the instance of the second.
The trace log shows an exchange as one line STATE_MACHINE_EXCHANGED, which names the object, the state machine that ended and the one that started, the paths that ended and the path of the new instance. Two EXCHANGE on one object in one tick give one such line, from the state machine before the tick to the one named last. EXCHANGE on an object without an instance gives the line STATE_MACHINE_ATTACHED. An instance that joins after another one left the same object, for example after the object was removed and created again with the same key, goes on with the next path number of the object. The lines are described in 3.3.5 Trace log.
3.1.13.6 Removed objects#
An object leaves the model through DROPOBJ, through a SETOBJ that replaces the object of a has relation, and through a dictionary with the __id__ of the object that holds it, when the dictionary no longer lists it, as 3.1.5.4 Objects and relations describes. In all cases every object it holds leaves with it, and the instances of all these objects end. An instance that a rule asked for in the same tick for one of these objects never joins. DROPOBJ still cannot remove the object of its own state machine by its own path, but it can remove an object that holds it.
3.1.13.7 Errors#
A name is a string, an EVAL or a MACRO, as 3.1.5.2 Values on the right side describes. A string is the name itself; an EVAL and a MACRO must return a string. These are errors of the action, handled like the others of 3.1.5.1 Blocks and errors:
| Error | Text in the trace log |
|---|---|
| The value is not a string | The name of a state machine must be a string, but the value is <value> |
| No definition has the name | No attachable state machine is named '<name>' |
| The definition does not list the type of the object | The state machine '<name>' is attachable to '<A>', '<B>', not to '<type>' |
ATTACH after a knows relation | ATTACH needs a has relation, but '<relation>' is a knows relation; use EXCHANGE for an existing object |
The path of EXCHANGE leads to no object | EXCHANGE path '<path>' does not resolve to an object |
The type of ATTACH is the type of the relation, the type of EXCHANGE the type of the object at the path. A failed ATTACH fails its whole rule, and a failed EXCHANGE leaves the instance of the object as it was.
3.1.13.8 Example#
The example uses the metamodel of 2.3.11: Bulb behaves after glowing, and Room has spare bulbs. The model has the room living room with the lamp lamp, its bulb bulb with maxWatts 40 and watts 0, and the switch wallSwitch. The environment holds the attachable state machines glowing and blinking of 2.3.11, and the state machine of the room, also from 2.3.11, is attached to living room:
STATEMACHINE ATTACHED TO "Room" {
STATES {
INITIAL STATE "waiting" { }
STATE "stocked" {
ENTRY {
APPENDOBJ("self", "spares", MACRO("new bulb", "lamp->bulb->maxWatts")) ATTACH "blinking"
}
}
STATE "party" {
ENTRY {
EXCHANGE("lamp->bulb", "blinking")
}
}
}
TRANSITIONS {
TRANSITION "waiting" -> "stocked" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "stocked" -> "party" {
CONDITION { EVENT("switch", "press") }
}
}
MACROS {
MACRO "new bulb" {
TAKES("watts", "number")
RETURNS("Bulb")
DEFINITION {
EVAL { return {"maxWatts": $(watts), "watts": $(watts)} }
}
}
}
}
At the start the room gets its attached state machine and bulb an instance of glowing, in this order. The new spare bulb gets the key gen_Bulb_0. A press comes before tick 3 and one before tick 6:
| Tick | Event | living room | bulb | gen_Bulb_0 |
|---|---|---|---|---|
| 1 | Stack waiting | ENTRY of dark of glowing runs. watts is 0, so it stays | ||
| 3 | press | "waiting" -> "stocked" fires | Stack dark | |
| 4 | ENTRY of stocked creates gen_Bulb_0 with ATTACH "blinking" | Stack dark | Joins at the end of the tick, after bulb | |
| 5 | Stack stocked | Stack dark | ENTRY of off runs, then "off" -> "on" fires | |
| 6 | press | "stocked" -> "party" fires | Stack dark | ENTRY of on runs, then "on" -> "off" fires |
| 7 | ENTRY of party exchanges the state machine of bulb | No step. Leaves at the end of the tick, an instance of blinking takes its place | ENTRY of off runs | |
| 8 | Stack party | ENTRY of off of blinking runs, then "off" -> "on" fires | ENTRY of on runs |
In tick 8 the order is living room, bulb, gen_Bulb_0. The trace log shows the change of tick 7 as one line, STATE_MACHINE_EXCHANGED: State machine 'glowing' exchanged for 'blinking' for bulb, with ends=0, path=1. A DROPOBJ("lamp") in the room would end the instance of bulb in the same way, because the lamp holds the bulb, and nothing would take its place.
3.1.13.9 Stop and start, forcing and clients#
Only the first start builds instances over the model. A stop freezes the environment, and a start after it continues the run with the next tick, as if there had been no stop. Everything stays as the stop found it:
-
every instance, also those that
ATTACHandEXCHANGEgave objects, with its place in the order; - the stacks and branches of every instance, the events it consumed and its scoped events;
- the histories, the counts of tick limits, and the state and overrides of breakpoints;
- the number of the tick, and with it the lists of EventRecording and EventInjection;
- the path numbers of the trace log, so the branches go on with their paths and new ones count on;
- the pause of TickByTick and a halt at a breakpoint;
- the events on the bus, which keep the time to live they had left at the stop, because the time while the environment is stopped does not count.
A stopped environment stays frozen in the runtime until it is started, dropped with POST /dropEnvironment of 3.4.2 Environments, or the runtime ends. A drop ends it for good, also when it is stopped while a breakpoint halts it.
Nothing runs again that ran before the stop: no ENTRY block runs twice, and no instance starts anew. A stop lets the running tick end first. When the run waits at a breakpoint inside a tick, the halted tick stays as it is until the start and a resume. Events that clients send while the environment is stopped wait and reach the state machines after the start.
setActiveState of 3.1.11 Forcing a state works on the instance an object has in the latest tick, also on one that joined during the run.
Clients learn about instances through the messages stateMachineAttached and stateMachineDetached of 3.5 WebSocket, which name the object and the definition, and through the member stateMachines of the model snapshot. At the first start every instance is reported before the first tick; a start after a stop reports nothing anew. An instance that joins is reported at the end of the tick it joined in, its first stack after its first step. An instance that leaves is reported at the end of the tick it ended in, and its stack disappears from the snapshot.
3.1.14 Pages#
Container states, fragments, final states and the clause DONE split a state machine into pages. How to write them is in 2.3.12 Pages. They belong to the core language and need no feature.
3.1.14.1 Flattening at activation#
runEnvironment flattens every attached state machine and every attachable state machine of the environment with the fragments of the environment, before anything runs. A container state then holds a copy of the states of its fragment as its inner states, and a fragment used by two container states runs as two copies that share nothing. The engine runs only these flat state machines. A state machine that does not flatten, for example because its container state uses a fragment the environment does not hold, refuses the activation, as 3.4.7 Running shows. The environment then stays configurable for the missing upload and another runEnvironment.
An attachable state machine is flattened once. Every instance of it runs the same flat state machine, whether it comes from behaves after, ATTACH or EXCHANGE. The texts the environment keeps are the uploaded ones, and observatory/statemachine answers them, not the flat state machines.
3.1.14.2 Qualified names#
A state of a fragment runs under the name of its container state, a slash and its name in the fragment. The state lit of the fragment bulb test below runs as self test/lit. When a fragment uses a fragment again, the names nest, as in self test/wiring/lit. A state that stands inside another state of the fragment keeps its name in the fragment behind the container state: high inside second runs as self test/high. The states of the state machine itself keep their names.
The trace log, the message stateChange, the member activeStates of the snapshot and setActiveState use these names. A state machine without container states looks exactly as before.
3.1.14.3 Entering a container state#
Whenever a container state is entered, the runtime goes down into it at once: into the states its fragment starts in, by the rule of 3.1.3.1 Initial state, and further down while one of them is a container state again. This holds for every way a state is entered: the start of an instance, a transition, a split, a join, the timeout of a tick limit, a history and setActiveState, and for the instances that behaves after, ATTACH and EXCHANGE start. A stack therefore never ends on a container state. A state with inner states written in its braces is different: a transition enters it as itself, as 3.1.4.3 Where a transition leads describes.
The states entered below the container state are entered in the next tick, from the outside in, like the other states a transition enters. A container state has no ENTRY and no DO block.
The examples use this fragment:
STATEMACHINE "bulb test" FRAGMENT {
STATES {
INITIAL STATE "lit" {
ENTRY { SET("bulb->lit", "true") }
}
STATE "dark" {
ENTRY { SET("bulb->lit", "false") }
}
FINAL STATE "passed" { }
}
TRANSITIONS {
TRANSITION "lit" -> "dark" {
CONDITION { EVENT("switch", "dim") }
}
TRANSITION "dark" -> "passed" {
CONDITION { EVENT("switch", "dim") }
}
}
}
The lamp runs it in its container state self test:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" {
ENTRY { SET("mode", "off") }
}
CONTAINER STATE "self test" USE "bulb test" { }
STATE "on" {
ENTRY { SET("mode", "on") }
}
}
TRANSITIONS {
TRANSITION "off" -> "self test" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "self test" -> "on" {
CONDITION { DONE }
}
TRANSITION "self test" -> "off" {
CONDITION { EVENT("switch", "press") }
}
}
}
With a press before tick 2 and a dim before tick 4 and before tick 6:
| Tick | Event | lamp |
|---|---|---|
| 1 | ENTRY of off runs. Stack off | |
| 2 | press | "off" -> "self test" fires. Stack self test, self test/lit |
| 3 | ENTRY of self test/lit runs. lit is true | |
| 4 | dim | "self test/lit" -> "self test/dark" fires |
| 5 | ENTRY of self test/dark runs. lit is false | |
| 6 | dim | "self test/dark" -> "self test/passed" fires. Stack self test, self test/passed |
| 7 | DONE holds and "self test" -> "on" fires. Stack on | |
| 8 | ENTRY of on runs |
3.1.14.4 Leaving a container state#
The container state is active around the states of its fragment, so its transitions apply in every one of them, as for any outer state. A transition that leaves the container state drops all its inner states. A press during the self test above leads back to off from self test/lit and from self test/dark. On self test/passed the transition with DONE is written before the one on the press and fires first, so the lamp goes on to on in the next step. The next press after off starts the fragment again in self test/lit. The runtime looks for transitions from the innermost state outwards, so a transition of a state of the fragment wins over one of the container state when both could fire.
3.1.14.5 Final states and DONE#
A final state has no actions and no transitions of its own. The stack rests on it, and the runtime still tries the transitions of the states around it, as for every state. Without a transition that leads out of the container state, the stack stays on the final state.
DONE on a TRANSITION or SPLIT holds exactly while the state right inside the container state the transition leaves is a final state of its fragment. With other clauses in the same condition all of them must hold. An event that such a condition waits for is treated as for every condition whose other clauses do not hold: when nothing fires in the step, the event is consumed, as 3.1.7.3 Consumption describes. With CONDITION { EVENT("switch", "abort") DONE }, an abort that arrives before the fragment rests on a final state is lost, and only an abort after that leads out. On a JOIN the event waits until DONE holds. DONE holds again whenever the fragment rests on a final state, also after the container state was left and entered again and its fragment ran to its end once more.
Leaving through a final state takes one step more than a transition that leads straight out. The transition into the final state ends its step, and DONE fires in the next tick at the earliest, as ticks 6 and 7 of the example in 3.1.14.3 Entering a container state show.
DONE on a JOIN holds when every source of the join that is a container state rests on a final state in the branch that stands in it. Sources that are no container states do not count for it. The join still needs one branch per source, as 3.1.8 Splits and joins describes. In the second lamp of 2.3.12.2 Container states and DONE, the split starts one branch in bulb check/powered and one in switch check/waiting. A branch that reaches a final state rests there until the other one has reached one as well, and then the join fires. With the feature TrueParallel on, the branches run on threads of their own, and the join works the same way.
3.1.14.6 Histories, tick limits and breakpoints#
With the feature History on, a container state with a history remembers like any other state: SHALLOW HISTORY the state right inside it, DEEP HISTORY the innermost active state. When the container state is entered again, the runtime goes to the remembered state at once, in the same step, instead of starting the fragment. This is different from a state with inner states written in its braces, which first rests on itself for one tick, as 3.1.9 Histories describes. A remembered state that has inner states of its own is entered as itself, as by a transition, and a remembered container state is gone down into. Without something to remember, or without the feature History, the fragment starts as usual.
A TICK LIMIT of a container state counts the ticks of the container state while any state of its fragment is active. Its delay holds back the transitions that leave the container state, not those inside the fragment, and its timeout leads out of the container state. A timeout that leads into a container state goes down into it.
A BREAKPOINT on the entry of a container state halts the run before the container state is entered, and the states of its fragment are entered after it. Breakpoints of the states of a fragment work as on every state; each copy of a fragment has its own states, so a breakpoint of one copy halts only that copy.
3.1.14.7 The trace log#
The lines of the trace log name the states with their qualified names. In the example of 3.1.14.3 Entering a container state, tick 4 writes the line TRANSITION_FIRED: self test/lit -> self test/dark with from=self test/lit, to=self test/dark and stack=self test,self test/dark. An instance that starts in a container state writes Initial state stack: self test > self test/lit, and setActiveState with self test writes Forced state: self test > self test/lit. The lines are described in 3.3.5 Trace log.
3.1.14.8 Compound states and container states#
A compound state holds inner states written in its braces. A container state holds the copy of a fragment. What each can be written with, their names and their macros are compared in 2.3.13 Compound states and container states. At run time they differ in these points:
| Point | Compound state | Container state |
|---|---|---|
| A transition into the state itself | Enters the state alone and rests on it. Its inner states are not entered | Enters the state and the start of its fragment in the same step. The stack never ends on the container state |
| A transition into an inner state | Enters the compound state too, when it was not active | Not possible: no file names a state of a fragment it uses |
| ENTRY and DO | The compound state has its own blocks; its DO runs while it is the innermost state | The container state has none |
Names in the trace log and in stateChange | The names as written: self test, lit | Qualified: self test, self test/lit |
| Re-entry with a history | Rests on itself for one tick, then leads on to the remembered state | Goes to the remembered state at once |
| End of the inner behaviour | A transition of an inner state leads out | The fragment rests on a final state, and DONE on a transition of the container state leads out |
| A transition of the outer state | Leaves every inner state | Leaves every state of the fragment |
The same self test written both ways. With a compound state, the transitions lead into its inner states:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "self test" {
STATE "lit" {
ENTRY { SET("bulb->lit", "true") }
}
STATE "dark" {
ENTRY { SET("bulb->lit", "false") }
}
STATE "passed" { }
}
STATE "on" {
ENTRY { SET("mode", "on") }
}
}
TRANSITIONS {
TRANSITION "off" -> "lit" { }
TRANSITION "lit" -> "dark" { }
TRANSITION "dark" -> "passed" { }
TRANSITION "passed" -> "on" { }
}
}
With a container state, the fragment holds the steps and DONE leads out:
STATEMACHINE "bulb test" FRAGMENT {
STATES {
INITIAL STATE "lit" {
ENTRY { SET("bulb->lit", "true") }
}
STATE "dark" {
ENTRY { SET("bulb->lit", "false") }
}
FINAL STATE "passed" { }
}
TRANSITIONS {
TRANSITION "lit" -> "dark" { }
TRANSITION "dark" -> "passed" { }
}
}
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
CONTAINER STATE "self test" USE "bulb test" { }
STATE "on" {
ENTRY { SET("mode", "on") }
}
}
TRANSITIONS {
TRANSITION "off" -> "self test" { }
TRANSITION "self test" -> "on" {
CONDITION { DONE }
}
}
}
Both run in the same ticks; only the names differ. An ENTRY block with actions is followed at once by the search for a transition, so lit and dark are left in the tick they are entered:
| Tick | Compound state | Container state |
|---|---|---|
| 1 | "off" -> "lit" fires. Stack self test, lit | "off" -> "self test" fires. Stack self test, self test/lit |
| 2 | ENTRY of lit runs, then "lit" -> "dark" fires | ENTRY of self test/lit runs, then "self test/lit" -> "self test/dark" fires |
| 3 | ENTRY of dark runs, then "dark" -> "passed" fires. Stack self test, passed | ENTRY of self test/dark runs, then "self test/dark" -> "self test/passed" fires. Stack self test, self test/passed |
| 4 | "passed" -> "on" fires. Stack on | DONE holds and "self test" -> "on" fires. Stack on |
| 5 | ENTRY of on runs | ENTRY of on runs |
With TRANSITION "off" -> "self test" { } in the first text, the compound state is entered alone. The stack stays self test, no inner state is ever entered, and bulb->lit never changes. The container state cannot be entered that way: it always starts its fragment.
3.1.15 Where the engine goes#
This section gathers in one place where a stack goes when states are entered, which states are entered and in which tick their ENTRY blocks run. The rules behind it are in 3.1.3 Active states, 3.1.4 Transitions and 3.1.14 Pages.
3.1.15.1 Ways of entering#
A step of a state machine ends with the first transition that fires. The states a transition enters run their ENTRY blocks in the next step of the same branch, which is the next tick, from the outside in. An ENTRY block with at least one action is followed by a search for a transition; when one fires, the ENTRY blocks further inside do not run.
| Way | When the stack changes | ENTRY of the entered states |
|---|---|---|
| Start of the environment | Before tick 1. The stack is the start path of 3.1.3.1 Initial state | Tick 1, every state of the start path |
Instance that joins during the run (behaves after of a created object, ATTACH, EXCHANGE) | At the end of the tick that asked for it. The stack is the start path of its state machine | The next tick, its first step |
| Transition | In the step that fires it | The next tick |
| Split | In the step that fires it; one stack per target | The next tick, in each branch |
| Join | At the start of the step, before every other transition; one stack | The next tick |
| Timeout of a tick limit | In the step, after the ENTRY blocks and before the DO block, which then does not run | The next tick |
| History of a compound state | In the step after the compound state was entered, right after its ENTRY block; its DO block does not run | The tick after that |
| History of a container state | In the same step as the transition into the container state | The next tick |
setActiveState | At the start of the next tick, before any step | Never. The forced states count as entered without running their ENTRY blocks, and the step of that tick goes on with the DO block of the innermost one |
The first tick of a newly joined instance and every other step look for transitions as usual, so a transition can follow right after the ENTRY blocks.
3.1.15.2 Kinds of target#
| Target | Stack afterwards | Entered | The branch rests on |
|---|---|---|---|
| A state without inner states | The path from the top level to the state | The states of the path that were not active | The state |
| A compound state | The path to the compound state, nothing below it | The states of the path that were not active | The compound state; its DO block runs from the next tick. With a history that remembers a state, it leads on one tick later |
| An inner state of a compound state | The path to the inner state | The compound state too, when it was not active | The inner state |
| A container state | The path to the container state and the start path of its fragment, or the remembered state of its history | The container state, when it was not active, and every state below it | The innermost state of the fragment, never the container state alone |
| A state of a fragment, by a transition of the fragment | The path to the state, inside the container state | The states of the path that were not active; the container state stays active and is not entered again | The state |
| A final state | The path to the final state | The final state | The final state, until a transition of a state around it fires |
A transition from a state to itself, or to one of the states around it, enters the target again together with the state around it, as 3.1.4.3 Where a transition leads describes. For a container state this means: "self test" -> "self test" leaves the fragment, enters self test again and starts its fragment anew.
3.1.15.3 The start and the INITIAL mark#
The start follows the INITIAL mark through every compound state, wherever the mark stands, by the rule of 2.3.2.2 The initial state. In the lamp
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
STATE "off" { }
STATE "on" {
STATE "full" { }
INITIAL STATE "dimmed" { }
}
}
TRANSITIONS { }
}
the stack at the start is on, dimmed, although off is the first state of the top level. Both states are entered in tick 1.
The mark of a fragment is not seen from the state machine that uses it. A container state never counts as holding a mark, so the start does not choose it for the mark inside its fragment. In this lamp the fragment levels marks its state dimmed, and the start is spare, ready:
STATEMACHINE "levels" FRAGMENT {
STATES {
STATE "full" { }
INITIAL STATE "dimmed" { }
FINAL STATE "out" { }
}
TRANSITIONS { }
}
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
STATE "off" { }
CONTAINER STATE "on" USE "levels" { }
STATE "spare" {
INITIAL STATE "ready" { }
}
}
TRANSITIONS { }
}
A state machine must mark one of its own states, so on is the start only when it is marked itself, INITIAL CONTAINER STATE "on" USE "levels". Then the start is on, on/dimmed: inside the container state the mark of its fragment counts. Without any mark of its own the text is refused at the upload with kstates.initial-state-count.
3.1.15.4 Entering and leaving, tick by tick#
A compound state entered by a transition. With
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "on" {
ENTRY { SET("mode", "on") }
STATE "full" { }
STATE "dimmed" { }
}
}
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "off" -> "dimmed" {
CONDITION { EVENT("switch", "dim") }
}
TRANSITION "on" -> "off" {
CONDITION { EVENT("switch", "press") }
}
}
}
and a press before tick 2, a press before tick 4 and a dim before tick 6:
| Tick | Event | lamp |
|---|---|---|
| 2 | press | "off" -> "on" fires. Stack on |
| 3 | ENTRY of on runs. Stack on; full and dimmed are not entered | |
| 4 | press | "on" -> "off" fires. Stack off |
| 6 | dim | "off" -> "dimmed" fires. Stack on, dimmed |
| 7 | ENTRY of on runs, then the stack rests on dimmed |
A compound state with a history. With SHALLOW HISTORY STATE "on" in the text above, the feature History on, the stack on, dimmed left by a press, and a press again:
| Tick | Event | lamp |
|---|---|---|
| k | press | "off" -> "on" fires. Stack on |
| k+1 | ENTRY of on runs, then the history leads on. Stack on, dimmed | |
| k+2 | ENTRY of dimmed runs |
A container state with a history goes there in tick k already. With SHALLOW HISTORY CONTAINER STATE "self test" USE "bulb test" in the lamp of 3.1.14.3 Entering a container state, left by a press in self test/dark and entered again by a press:
| Tick | Event | lamp |
|---|---|---|
| k | press | "off" -> "self test" fires. Stack self test, self test/dark |
| k+1 | ENTRY of self test/dark runs |
Without the feature History, or while the history remembers nothing yet, the stack in tick k is self test, self test/lit.
Leaving. A transition from a state leaves every state inside it, whatever is active there, and no block runs for the states left. The stack becomes the path to the target, entered as the tables above describe. A transition of a state inside wins over one of the state around it when both could fire, because the runtime looks from the innermost state outwards.