3.2 Runtime features
A feature is a part of the runtime that a client switches on for one environment. Two features give language constructs their effect at run time: History for SHALLOW HISTORY and DEEP HISTORY, TickLimit for TICK LIMIT blocks. TrueParallel runs the branches of a split on threads of their own. The other features let a client step through a run, halt it at breakpoints, and record and replay the events of a run. All features are off in a new environment.
| Feature | What it does | Needs |
|---|---|---|
History | Gives the history marks of states their effect | |
TickLimit | Gives TICK LIMIT blocks their effect | |
TickByTick | Pauses the run and advances it tick by tick | |
Breakpoint | Halts the run at the entry and exit of states and at the start and end of transitions | TickByTick |
EventRecording | Records the events that clients send, by tick | |
EventInjection | Hands a list of events to the state machines at given ticks | |
EventReplayController | Turns a recording into the list of EventInjection | EventRecording, EventInjection |
TrueParallel | Lets the branches of a split do their steps at the same time, each on a thread of its own |
3.2.1 Switching features#
The routes for features are in 3.4.10 Features. A client switches a feature on with activateFeature and off with deactivateFeature, in any phase of the environment. A switch takes effect at once, also in the middle of a run.
Switching on a feature also switches on the features it needs. Switching off a feature also switches off the features that need it, and the features that were only switched on because it needed them. Switching off TickByTick switches off Breakpoint.
A client talks to a feature with sendMessageToFeature. The body of the request is the message as text, and the body of the answer is the answer of the feature. History, TickLimit and TrueParallel take no messages; they answer every message with an empty body. The messages of every other feature are listed below.
curl -X POST "http://127.0.0.1:8080/activateFeature?envKey=env-1763035112345&featureName=TickByTick"
curl -X POST "http://127.0.0.1:8080/sendMessageToFeature?envKey=env-1763035112345&featureName=TickByTick" -d "status"
running
3.2.2 History#
With History on, a state marked SHALLOW HISTORY or DEEP HISTORY leads on into the inner state it was in when it is entered again. The rules and an example are in 3.1.9 Histories, and for a container state in 3.1.14.6 Histories, tick limits and breakpoints. What a state remembers stays when the environment is stopped and started again, and is forgotten when History is switched off.
3.2.3 TickLimit#
With TickLimit on, DELAY holds a state for its first ticks and TIMEOUT leaves a state after a number of ticks. The rules and an example are in 3.1.10 Tick limits. The counts stay when the environment is stopped and started again.
3.2.4 TickByTick#
TickByTick pauses the run between two ticks and lets it advance by a number of ticks. While the run is paused, the environment still takes events from clients and answers snapshots of its model.
| Message | Answer | What happens |
|---|---|---|
pause | execution paused | The run waits before its next tick |
resume | execution resumed | The run goes on |
tick:N | execution is advancing N tick(s) | The paused run does N more ticks and waits again. The answer says tick for 1 and ticks for more |
status | paused or running |
tick:N works only while the run is paused and no earlier tick:N is still under way. Otherwise the answer is execution is currently not paused, ticks will not be applied. With N less than 1 the answer is amount of ticks must not be less than one. Any other message is refused with status 400 and the text Invalid message: <message>.
The first start of an environment resumes a paused run. To step from the first ticks on, send pause after the start. Switching TickByTick off also resumes the run. A stop keeps the pause: after the start the run still waits, and a resume or tick:N sent while the environment is stopped takes effect only after the start.
While TickByTick is on, every client connected to the environment over the WebSocket gets the message engineStatus each time the run starts to wait and each time it goes on, as 3.5 WebSocket describes.
curl -X POST "http://127.0.0.1:8080/sendMessageToFeature?envKey=env-1763035112345&featureName=TickByTick" -d "pause"
curl -X POST "http://127.0.0.1:8080/sendMessageToFeature?envKey=env-1763035112345&featureName=TickByTick" -d "tick:3"
execution paused
execution is advancing 3 ticks
3.2.5 Breakpoint#
Breakpoint halts the run at a place inside a tick. The run then waits as if paused with TickByTick. resume lets the run go on, and tick:1 lets it go on to the next breakpoint or to the start of the next tick, whichever comes first. Both are messages to TickByTick.
3.2.5.1 Places#
A run halts at these places:
| Place | When |
|---|---|
| Entry of a state | Before the ENTRY block of the state runs, also when the block is empty |
| Exit of a state | When a transition leaves the state, before the transition starts. The states left are taken from the innermost outwards. A transition from a state to itself leaves no state |
| Start of a transition | Before the transition changes the active states |
| End of a transition | After the transition changed the active states |
A transition that a DELAY holds back halts nowhere. The timeout of a TICK LIMIT and the step into the state that a history remembers count as transitions. They have no text, so only an override halts at their start or end.
3.2.5.2 Breakpoints in the text and overrides#
A state machine marks breakpoints in its text with BREAKPOINT { ENTRY EXIT } in a state and BREAKPOINT { START END } in a transition, as 2.3 KStates shows. An override switches a breakpoint on or off at run time, whatever the text says. Overrides belong to the environment and stay when it starts again. The overrides of an object are dropped when its state machine instance leaves, as 3.1.13 State machine management and lifecycle describes, so an instance that later runs on the object starts with the breakpoints of its text.
All messages to Breakpoint are JSON objects with the entry action:
| Action | Further entries | Answer |
|---|---|---|
addStateOverride | modelElementId, stateIdentifier, timing (entry or exit), breakpointStatus (true or false) | Breakpoint override has added a breakpoint on state <state> entry in statemachine attached to <object>, with removed for false and exit for the exit |
removeStateOverride | modelElementId, stateIdentifier, timing | Breakpoint override on state <state> entry has been removed in statemachine attached to <object> |
addTransitionOverride | modelElementId, transitionIdentifier, timing (start or end), breakpointStatus | Breakpoint override has added a breakpoint on transition <transition> start in statemachine attached to <object> |
removeTransitionOverride | modelElementId, transitionIdentifier, timing | Breakpoint override on transition <transition> start has been removed in statemachine attached to <object> |
getOverrides | The overrides in four groups, as shown below | |
getStatus | The status of the run as JSON, as shown below |
modelElementId is the key of the object the state machine instance runs on. stateIdentifier is the name of the state. A wrong timing gives an answer that starts with Breakpoint override could not be added or Breakpoint override could not be removed, an unknown action the answer Invalid action: <action>, and a message that is no JSON or lacks an entry an answer that starts with Error when parsing the message:. All these answers have status 200.
transitionIdentifier names the transition as the runtime writes it. For TRANSITION "off" -> "full" with an EVENT clause it is:
Transition(fromState=off, toState=full, allowLoops=true, startBreakpoint=false, endBreakpoint=false, condition=EVENT)
allowLoops is false for a transition marked NOT LOOPING. startBreakpoint and endBreakpoint say whether the text marks the breakpoints. condition is VALUE for a transition without CONDITION, EVENT, EVAL or VALUE for a condition of one clause, and COMPOSITE for a condition of more clauses. A split starts with SplitTransition(fromState=off, toStates=[test bulb, test switch], ... and a join with JoinTransition(fromStates=[bulb ok, switch ok], toState=on, .... The entry halt of the status below names the transition in the same form. Transitions with the same identifier share their overrides.
{
"action": "addStateOverride",
"modelElementId": "lamp",
"stateIdentifier": "on",
"timing": "entry",
"breakpointStatus": true
}
Breakpoint override has added a breakpoint on state on entry in statemachine attached to lamp
The answer of getOverrides:
{Entry Breakpoints={lamp={on=true}}, Exit Breakpoints={}, Start Breakpoints={}, End Breakpoints={}}
3.2.5.3 Status#
getStatus answers a JSON object. paused is true once a pause was asked for and until the run is resumed. waiting is true while the run waits. halt is there only while the run waits at a breakpoint and names the place. The same object is the payload of the WebSocket message engineStatus.
For a state:
{"paused":true,"waiting":true,"halt":{"modelElementId":"lamp","timing":"entry","state":"on"}}
For a transition, kind is TRANSITION, SPLIT or JOIN, from and to are the states, and index is the place of the transition in the TRANSITIONS block of its file, counted from 0. A timeout and the step into a remembered state have the index -1:
{"paused":true,"waiting":true,"halt":{"modelElementId":"lamp","timing":"start","transition":"Transition(fromState=off, toState=full, allowLoops=true, startBreakpoint=false, endBreakpoint=false, condition=EVENT)","kind":"TRANSITION","from":["off"],"to":["full"],"index":0}}
The order of the entries in these objects is not fixed.
3.2.6 EventRecording#
EventRecording records the events that clients send over the WebSocket, under the number of the tick in which they reach the state machines. While it records, an event from a client waits for the start of the next tick. Events that the state machines raise and injected events are not recorded.
| Message | Answer | What happens |
|---|---|---|
start | recording started | Recording starts |
stop | recording stopped | Recording stops. Events that wait for the next tick go to the state machines at once |
get | The recording as JSON | |
clear | cleared recorded events | The recording is emptied |
Any other message gets the answer invalid message: <message>. A recording stays when the environment is stopped and started again, and the ticks go on with the next number, so the recording goes on where it stopped.
The recording is a JSON object. Its keys are tick numbers, and each value is a list of events, each written as a string with a JSON object:
{"5": ["{\"environmentKey\":\"switch\",\"messageType\":\"dim\",\"payload\":\"{\\\"bright\\\": false}\",\"payloadFormat\":\"JSON\"}"]}
environmentKey is the domain of the event, messageType its name, payload its payload as text and payloadFormat one of NONE, JSON and KMODEL. The order of the entries is not fixed.
3.2.7 EventInjection#
EventInjection holds a list of events by tick and hands each event to the state machines at the start of its tick.
| Message | Answer | What happens |
|---|---|---|
upload:<list> | successfully uploaded events | Replaces the list |
start | injection started | Injection starts |
stop | injection stopped | Injection stops |
get | The list as JSON | |
clear | cleared event queue | The list is emptied |
Any other message gets the answer invalid message: <message>. The list has the form of a recording. Each event can be a string with a JSON object, as in a recording, or a JSON object. Each event needs environmentKey, messageType and payload; payloadFormat is optional. A list that cannot be read is refused with an error status and the reason as text.
While injection runs, the runtime hands over at the start of each tick every event of the list whose tick is not later than the current tick, and removes it from the list. When injection starts in tick 10, the events of ticks 1 to 10 come at once.
The time to live of an injected event counts from the upload of the list. An event whose tick comes later than its time to live after the upload has expired when it is handed over, and the state machines never see it. For long lists, set the time to live of the environment to 0. Injected events carry their payload as text only, so paths into event lead nowhere for them.
curl -X POST "http://127.0.0.1:8080/sendMessageToFeature?envKey=env-1763035112345&featureName=EventInjection" \
-d 'upload:{"3": [{"environmentKey": "switch", "messageType": "press", "payload": ""}]}'
curl -X POST "http://127.0.0.1:8080/sendMessageToFeature?envKey=env-1763035112345&featureName=EventInjection" -d "start"
successfully uploaded events
injection started
3.2.8 EventReplayController#
EventReplayController replays a recording. It needs EventRecording and EventInjection and switches them on.
| Message | Answer | What happens |
|---|---|---|
initialize | replay successfully initialized | Stops recording and injection and uploads the recording as the list of EventInjection |
Any other message gets the answer invalid message: <message>. When the upload fails, the answer starts with replay could not be initialized, following error occurred:.
A start after a stop continues the run with the next tick, as 3.1.13.9 Stop and start, forcing and clients describes. In the same environment the ticks of a recording have passed by then, so after initialize and a start all recorded events come in the next tick. A replay in the same ticks as before runs in a new environment:
-
Switch on EventRecording and send it
start. - Start the environment and send events from a client.
-
Send
getto EventRecording and keep the answer. -
Create a new environment with the same uploads, switch on EventInjection, send it
upload:with the recording andstart. - Run and start the new environment. The events come in the same ticks as before, on the model as it was uploaded.
With TrueParallel off, the trace log of the replay is the trace log of the recorded run line by line, apart from the times and the key of the environment, also when state machines are attached, exchanged and detached and when the state machines split and join, since the path numbers count the same way.
3.2.9 TrueParallel#
Without TrueParallel, the branches of a split do their steps one after the other on the one thread of the environment, in the order of the targets of the split, as 3.1.8 Splits and joins describes. Every run of the same model with the same events takes the same course.
With TrueParallel on, each branch gets a thread of its own when the split has fired, and keeps it for as long as the branch lives. In every tick all branches of a state machine do their steps at the same time on the shared model, and the tick ends when every branch has done its step. Ticks keep their numbers, so TickLimit, TickByTick, Breakpoint, EventRecording and EventInjection count them as before, and the active states are reported once per tick after all steps. A join is still tried before the branches step. A branch that waits for Python in an EVAL holds up only itself until the end of the tick, and each branch that calls Python at the same time as another one gets a Python process of its own.
A switch of TrueParallel takes effect at the start of the next tick. The threads of branches end when a join merges the branches, when the environment stops and at the end of the tick in which TrueParallel was switched off. A start after a stop gives the branches new threads at their next step. A stop while a branch waits at a breakpoint keeps the threads of the halted tick until it ends. State machines without a split run as without the feature, and so do the several state machines of an environment, which still do their steps one after the other.
3.2.9.1 What a modeler can rely on#
-
Each single action is atomic: one
SET,APPEND,SETLIST,DROPLIST,SETOBJ,APPENDOBJ,DROPOBJorEVENTchanges the model or the bus in one go, and no other branch sees it half done. -
An action that computes its value first reads and then writes. Between the two, another branch can write. Two branches that increment the same number with
SET("count", EVAL { return $(count) + 1 })can lose an increment. - Two branches that write the same property race. Which value stays is not defined.
- The order of actions across branches is not defined. Within one branch the actions run in their order, as always.
- The changes of one ENTRY or DO block still reach the clients together after the block, as 3.1.5.1 Blocks and errors describes. Blocks of different branches reach them in the order in which they ended. The revisions of the pushes still increase one by one.
- Events that one branch raises can be seen by another branch in the same tick or only in the next one.
- Branches that create, remove or exchange objects with state machines change the instances of the environment only at the end of the tick, all together, as 3.1.13.3 When instances join and leave describes. An instance that a branch ends stops its other branches after the block they are in.
-
With Breakpoint on, branches that reach breakpoints in the same tick halt one after the other.
resumelets the waiting branch go on, and the next one halts. While one branch waits, the others finish their steps.
For a deterministic run, as in tests and in replays with EventInjection, leave TrueParallel off.
The trace log names the path of the branch in every line of a branch, as 3.3.5 Trace log describes. With TrueParallel on, the lines of branches that step at the same time interleave in the order in which they were written, and the path tells them apart. The path numbers are the same as with TrueParallel off, because splits, joins and exchanges are carried out by the thread of the environment in the same order either way.
curl -X POST "http://127.0.0.1:8080/activateFeature?envKey=env-1763035112345&featureName=TrueParallel"