FSMLang: Better State Machine Design¶
FSMLang is was created to allow design work in the problem space of finite state machines without the encumbrances of any particular implementation language. Thus, FSMLang is implemented as a “pre-processor,” generating code in any desired general programming language to implement the described finite state machine. FSMLang allows effort to be focused on the definition of events, states, and transitions. Indeed, though the action to be taken in any particular event/state intersection is declarable, the actual definition of that action is treated as a detail which falls outside the scope of FSMLang. Moreover, the mechanisms for collecting or determining events are also outside the language scope. FSMLang creates an object or objects in a target programming language which, when inserted into the larger program structure will invoke the correct actions and make the correct transitions for the events handed it.
The created state machine contains a single state variable, which should not be manipulated by any user-written
function. This variable is maintained on the heap, not on the machine’s function call stack. This means that
the machine must not be called recursively; neither from within any action function, nor from separate threads of
execution. The keyword reentrant can be used to designate machines which are called
from different execution threads. Macros will be inserted at the beginning and end of the state machine function
which are to be defined by the user to properly protect the machine from re-entrance.
Supporting the desire to keep FSMLang focused on machine design, provision is made to insert native blocks
into the machine specification files. These blocks are not interpreted by FSMLang, but are copied into the generated
source at different points. The blocks also serve to reduce or eliminate the need to post-process the generated code.
Data can be specified for both machines and events. States may have entry and exit functions. Transitions may be done to a specified state, or through the auspices of a transition function. A machine may have a transition function called when any state transition is made. And, machines may have sub-machines (to any (keep it reasonable!) depth).
FSMLang supports designing with action functions that return events (the default), states, or nothing.
Returning events from action functions is a powerful technique for the machine to immediately feed events to itself,
simplifying, for example, the management of internal errors. Imagine an action function which must allocate some memory to
complete its task; should that memory not be available, the function can simply exit, returning a “memory not available”
event; the state machine processing for this situation can be placed in another action function, and the machine can be
transitioned to an error state, should the situation be unrecoverable. The core FSM function loops, calling appropriate actions,
then making designated transitions, until an action function returns noEvent.
Having said all of that, useful state machines can be designed with actions that return states or nothing.
The language syntax is intended to make the action the state machine will take in response to any input immediately clear. Nevertheless, a UML state chart or a simple HTML event-state action matrix are useful tools for state machine visualization. FSMLang can output both HTML and PlantUML to assist in visualizing and documenting the state machine. For somewhat more formal documentation, ReStructuredText output is available, as well.
Both the language and this documentation are intended to assist in the design of useful state machines. Feedback is welcomed, both for language and for documentation improvements. Use the issue mechanisms in either GitHub repo.
The repos are at Language and Documents.
Revision history is maintained for the curious, and for those who support medical device development tool validation.
This documentation presents language concepts primarily through two examples, The Simple Communicator, and The HSM Communicator. Data for Machines and Events shows how FSMLang handles data for both machines and events, and States and Transitions rounds out the discussion of states.
Download this document as a pdf.