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:

  1. It applies the states that clients forced with setActiveState since the last tick, as 3.1.11 Forcing a state describes.
  2. 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.
  3. With the feature TickLimit on, it counts this tick for every active state.
  4. It removes events whose time to live is over.
  5. 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.
  6. 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.
  7. 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.

  1. With the feature History on, it notes the active inner states of every state that has a history.
  2. 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.
  3. With the feature TickLimit on, it fires the timeout of a state whose time is over.
  4. 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.
  5. It runs the DO block of the innermost active state.
  6. It looks for a transition that can fire and fires it.
  7. 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:

TickEventlampwallSwitch
1ENTRY of off runs. Stack offStack down
2Stack offStack down
3press"off" -> "full" fires. Stack on, full"down" -> "up" fires. Stack up
4ENTRY of on and of full run. watts is 40ENTRY of up runs
5dim"full" -> "dimmed" fires. Stack on, dimmedStack up
6ENTRY of dimmed runs. watts is 20Stack up
7press"on" -> "off" fires. Stack off"up" -> "back down" fires
8ENTRY of off runs. watts is 0ENTRY 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:

TickEventlamp
2dimStack off. No transition of off waits for dim, so the event stays
4press"off" -> "full" fires. Stack on, full
5ENTRY of on runs, then "full" -> "dimmed" fires on the waiting dim. Stack on, dimmed
6ENTRY 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:

TickEventlamp
2press"off" -> "full" fires
3ENTRY of on and full run
4dim, bright false"full" -> "dimmed" fires
5ENTRY of dimmed runs
6dim, bright falseNothing fires. The event is consumed
7dim, bright true"dimmed" -> "full" fires
8ENTRY 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:

Ticklamp
1"off" -> "on" fires
2ENTRY of on runs, then "on" -> "on" fires
3ENTRY 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".

ActionWhat 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#

ActionWhat 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 nameCreates 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") }
        }
    }
}
TickEventwallSwitchlamp
2push in domain button"down" -> "up" firesStack off
3ENTRY of up runs and raises press"off" -> "full" fires
4Stack upENTRY 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:

  1. It fires a transition. The option engine.eventConsumptionOnFire is true by default. With false, the event that fired a transition stays and can fire further transitions in later ticks.
  2. 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.
  3. 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" { }
    }
}
TickEventBranch 1Branch 2
2pressThe split fires. Stack test bulbStack test switch
3ENTRY of test bulb runs, then "test bulb" -> "bulb ok" fires"test switch" -> "check position" fires
4ENTRY of bulb ok runs"check position" -> "switch ok" fires
5The join fires. Stack on
6ENTRY 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") }
        }
    }
}
TickEventlamp
1ENTRY of on and full run
2dim"full" -> "dimmed" fires
3ENTRY of dimmed runs
4press"on" -> "off" fires
5ENTRY of off runs
6press"off" -> "on" fires. Stack on
7ENTRY of on runs, then the history leads on to dimmed
8ENTRY 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") }
        }
    }
}
TickEventlamp
1ENTRY of off runs. First tick of off
2pressSecond tick of off. The delay holds the transition, the press stays
3"off" -> "on" fires on the waiting press
4ENTRY of on runs. First tick of on
5Second tick of on
6Third tick of on
7The timeout leads to off
8ENTRY of off runs
9pressSecond 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 after the definition and the object is in the model when the environment starts;
  • its type behaves after the definition and a rule creates the object;
  • an ATTACH clause names the definition for the object its rule creates;
  • EXCHANGE gives 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:

  1. the attached state machines, in the order of their first upload;
  2. the instances for behaves after of 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;
  3. 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:

ErrorText in the trace log
The value is not a stringThe name of a state machine must be a string, but the value is <value>
No definition has the nameNo attachable state machine is named '<name>'
The definition does not list the type of the objectThe state machine '<name>' is attachable to '<A>', '<B>', not to '<type>'
ATTACH after a knows relationATTACH needs a has relation, but '<relation>' is a knows relation; use EXCHANGE for an existing object
The path of EXCHANGE leads to no objectEXCHANGE 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:

TickEventliving roombulbgen_Bulb_0
1Stack waitingENTRY of dark of glowing runs. watts is 0, so it stays
3press"waiting" -> "stocked" firesStack dark
4ENTRY of stocked creates gen_Bulb_0 with ATTACH "blinking"Stack darkJoins at the end of the tick, after bulb
5Stack stockedStack darkENTRY of off runs, then "off" -> "on" fires
6press"stocked" -> "party" firesStack darkENTRY of on runs, then "on" -> "off" fires
7ENTRY of party exchanges the state machine of bulbNo step. Leaves at the end of the tick, an instance of blinking takes its placeENTRY of off runs
8Stack partyENTRY of off of blinking runs, then "off" -> "on" firesENTRY 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 ATTACH and EXCHANGE gave 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:

TickEventlamp
1ENTRY of off runs. Stack off
2press"off" -> "self test" fires. Stack self test, self test/lit
3ENTRY of self test/lit runs. lit is true
4dim"self test/lit" -> "self test/dark" fires
5ENTRY of self test/dark runs. lit is false
6dim"self test/dark" -> "self test/passed" fires. Stack self test, self test/passed
7DONE holds and "self test" -> "on" fires. Stack on
8ENTRY 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:

PointCompound stateContainer state
A transition into the state itselfEnters the state alone and rests on it. Its inner states are not enteredEnters 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 stateEnters the compound state too, when it was not activeNot possible: no file names a state of a fragment it uses
ENTRY and DOThe compound state has its own blocks; its DO runs while it is the innermost stateThe container state has none
Names in the trace log and in stateChangeThe names as written: self test, litQualified: self test, self test/lit
Re-entry with a historyRests on itself for one tick, then leads on to the remembered stateGoes to the remembered state at once
End of the inner behaviourA transition of an inner state leads outThe fragment rests on a final state, and DONE on a transition of the container state leads out
A transition of the outer stateLeaves every inner stateLeaves 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:

TickCompound stateContainer state
1"off" -> "lit" fires. Stack self test, lit"off" -> "self test" fires. Stack self test, self test/lit
2ENTRY of lit runs, then "lit" -> "dark" firesENTRY of self test/lit runs, then "self test/lit" -> "self test/dark" fires
3ENTRY of dark runs, then "dark" -> "passed" fires. Stack self test, passedENTRY of self test/dark runs, then "self test/dark" -> "self test/passed" fires. Stack self test, self test/passed
4"passed" -> "on" fires. Stack onDONE holds and "self test" -> "on" fires. Stack on
5ENTRY of on runsENTRY 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.

WayWhen the stack changesENTRY of the entered states
Start of the environmentBefore tick 1. The stack is the start path of 3.1.3.1 Initial stateTick 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 machineThe next tick, its first step
TransitionIn the step that fires itThe next tick
SplitIn the step that fires it; one stack per targetThe next tick, in each branch
JoinAt the start of the step, before every other transition; one stackThe next tick
Timeout of a tick limitIn the step, after the ENTRY blocks and before the DO block, which then does not runThe next tick
History of a compound stateIn the step after the compound state was entered, right after its ENTRY block; its DO block does not runThe tick after that
History of a container stateIn the same step as the transition into the container stateThe next tick
setActiveStateAt the start of the next tick, before any stepNever. 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#

TargetStack afterwardsEnteredThe branch rests on
A state without inner statesThe path from the top level to the stateThe states of the path that were not activeThe state
A compound stateThe path to the compound state, nothing below itThe states of the path that were not activeThe 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 stateThe path to the inner stateThe compound state too, when it was not activeThe inner state
A container stateThe path to the container state and the start path of its fragment, or the remembered state of its historyThe container state, when it was not active, and every state below itThe innermost state of the fragment, never the container state alone
A state of a fragment, by a transition of the fragmentThe path to the state, inside the container stateThe states of the path that were not active; the container state stays active and is not entered againThe state
A final stateThe path to the final stateThe final stateThe 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:

TickEventlamp
2press"off" -> "on" fires. Stack on
3ENTRY of on runs. Stack on; full and dimmed are not entered
4press"on" -> "off" fires. Stack off
6dim"off" -> "dimmed" fires. Stack on, dimmed
7ENTRY 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:

TickEventlamp
kpress"off" -> "on" fires. Stack on
k+1ENTRY of on runs, then the history leads on. Stack on, dimmed
k+2ENTRY 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:

TickEventlamp
kpress"off" -> "self test" fires. Stack self test, self test/dark
k+1ENTRY 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.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.