The hsmcpp system SHALL provide type-safe state, event, and timer identifiers that allow users to define domain-specific identifier sets distinguishable at compile time.
The hsmcpp system SHALL support exit points that determine which outgoing transition from a parent state is taken based on the exit path selected by a child state.
The hsmcpp system SHALL execute state lifecycle callbacks according to the hierarchical relationships of the active state configuration when entering or exiting hierarchical states.
The hsmcpp system SHALL support configurations in which multiple states are simultaneously active, arising from executing all satisfied transitions for an event and from activating multiple entry points.
The hsmcpp system SHALL evaluate an event against all concurrently active states, allowing each to independently process or ignore the event according to its own transitions.
When a transition targets a state that is already part of the active state configuration, the hsmcpp system SHALL keep that state, together with its entire active substate configuration, active and unchanged, and SHALL NOT treat the target as newly activated.
The hsmcpp system SHALL support shallow history states that remember and restore all active direct child states of the parent when re-entering via the history state.
The hsmcpp system SHALL support deep history states that remember and restore the entire substate hierarchy that was active when the parent was last deactivated, including all concurrently active substates across parallel regions.
The hsmcpp system SHALL allow a default target state to be specified for a history state. When no history has been recorded, the system SHALL transition to the default target.
When multiple transitions match the same event from the same state, the hsmcpp system SHALL evaluate them in a deterministic order and execute all transitions whose guard condition is satisfied.
The hsmcpp system SHALL allow arbitrary application data to be associated with a transition request and delivered to all application-defined callbacks triggered by that transition.
The hsmcpp system SHALL maintain a valid active state configuration after every transition request, including transition requests that do not complete successfully.
The hsmcpp system SHALL support declarative actions associated with state lifecycle events and transitions. Supported actions include timer control, event generation.
The hsmcpp system SHALL provide event processing without requiring applications to integrate a specific external event-processing framework or runtime.
The hsmcpp system SHALL support asynchronous event processing where the caller submitting an event returns immediately and the event is processed independently.
The hsmcpp system SHALL support synchronous event processing where the caller submitting an event blocks until the transition completes or fails and receives the result.
The hsmcpp system SHALL process queued events in FIFO order unless pending events are explicitly discarded or a higher-priority internal processing rule applies.
The hsmcpp system SHALL prevent re-entrant event processing, ensuring that events generated during an active processing cycle are deferred for later processing.
The hsmcpp system SHALL provide defined error handling for operations that cannot be completed due to invalid parameters, invalid state-machine configuration, or the current state-machine lifecycle state.
The hsmcpp system SHALL provide the ability to determine whether a specified event can trigger a successful transition from the current state without changing state machine state.
The hsmcpp system's timer expiration precision SHALL be bounded by the timing facilities of the underlying platform. Guaranteed timer precision SHALL be defined as that provided by the platform's timing facilities.
The hsmcpp system SHALL support multiple timers running concurrently, each identified by a distinct timer identifier and controlled independently of the others.
The hsmcpp system SHALL accept SCXML models as an input format for defining state-machine structure. The system SHALL support the subset of W3C SCXML constructs required to express state-machine structure: state, parallel, initial, final, transition (with event, cond, target, type), onentry, onexit, and history (with type).
The hsmcpp system SHALL ignore SCXML constructs that describe executable content, data model, and external communication (including raise, if, foreach, log, datamodel, data, assign, send, cancel, invoke, and finalize) without failing model processing.
The hsmcpp system SHALL support hsmcpp-specific interpretation of the following SCXML constructs: the script element to name application callbacks for state entry, exit, and transition; the invoke element (via srcexpr) to name a state-changed callback; and the state src attribute to compose a model from an external file.
The hsmcpp system SHALL provide validation of state-machine models and SHALL report structural or configuration errors that prevent valid state-machine execution or generation.
The hsmcpp system SHALL support emitting human-readable diagnostic trace messages describing state machine activity. Trace output SHALL be deliverable to an application-provided output, and a default platform-specific output SHALL be provided.
The hsmcpp system SHALL produce structured execution logs in a format that supports replay and analysis of state-machine execution by compatible diagnostic tools.
The hsmcpp system SHALL provide build-time configuration options to enable or disable optional capabilities, including diagnostic trace logging, structured execution logging, structure validation, and thread-safety mechanisms.
The library SHALL provide a type-safe state identifier type that the compiler can distinguish from unrelated integer or enumeration types. The library SHALL allow users to define domain-specific state identifier sets.
The library SHALL provide a type-safe event identifier type that the compiler can distinguish from unrelated integer or enumeration types. The library SHALL allow users to define domain-specific event identifier sets.
The library SHALL provide a type-safe timer identifier type that the compiler can distinguish from unrelated integer or enumeration types. The library SHALL allow users to define domain-specific timer identifier sets.
The library SHALL provide a software interface allowing an application-provided event-processing implementation. Adding a custom event-processing implementation SHALL be possible without modifying library source code.
The event-processing implementation SHALL provide an operation to start event delivery, after which it processes queued events and delivers them to the state machines bound to it. A custom application-provided event-processing implementation SHALL be able to supply this operation without modifying library source code.
The event-processing implementation SHALL provide an operation to stop event delivery, after which no further queued events are delivered until it is started again. Stopping SHALL leave the implementation in a state from which it can be started again. A custom application-provided event-processing implementation SHALL be able to supply this operation without modifying library source code.
The library SHALL provide an explicit initialization operation that transitions a configured state machine into an executing state. The operation SHALL require a working event-processing implementation to be provided, and SHALL fail if none is provided. After successful initialization, the state machine SHALL be in its designated initial state.
The library SHALL require that the complete state machine structure (states, transitions, and actions) is fully configured before initialization. The library SHALL reject structural modifications attempted after initialization with a defined error indication.
The library SHALL serialize execution of application-defined callbacks for a given state machine instance, ensuring at most one callback executes at any time.
The library SHALL support multiple state machine instances sharing a single event-processing context. Each state machine instance SHALL process events independently while sharing the underlying event-processing infrastructure.
The library SHALL provide a release operation that terminates execution of a state machine and returns it to a state in which re-initialization is possible. After release, event processing SHALL resume only after successful re-initialization.
The library SHALL allow a state machine instance to be destroyed while it is running, without producing undefined behavior. Destruction SHALL release the instance's resources and SHALL ensure that no queued events or callbacks continue to act on the destroyed instance.
The library SHALL allow the user to designate one state as the initial state during configuration. The designated initial state SHALL become active upon successful initialization of the state machine.
The library SHALL support designating one or multiple states as a final state. When a final state becomes active, the library SHALL stop processing further events and transition the state machine to a terminated lifecycle state.
The library SHALL provide the ability to query which states are currently active. The library SHALL provide the ability to query whether a specified state identifier is currently active.
The library SHALL support registration of hierarchical parent-child relationships between states. A child state SHALL be active only when its parent state is active.
The library SHALL, when structure validation is enabled, detect and reject invalid parent-child configurations. Validated conditions SHALL include: circular parent-child dependencies, assignment of a child state to multiple parents, and definition of a state as its own parent.
The library SHALL, when structure validation is enabled, reject transitions whose source and target states do not share a common parent scope, transitions whose target is a substate nested within a composite state, and transitions that name an entry point as the target. A history state MAY be named as a transition target.
The library SHALL support registration of entry point substates. When an entry point is defined for a parent state, the library SHALL activate the designated child state upon entry to the parent.
The library SHALL support conditional entry points where the entry point is activated based on a runtime condition callback evaluated at the time of parent state entry. The condition callback SHALL take no event argument; it evaluates only application-defined state.
The library SHALL support entry points filtered by event, where an entry point is eligible for activation only when the event that triggered the transition into the parent state matches the entry point's configured event.
The library SHALL support entry points that define both an event filter and a condition callback. Such an entry point SHALL be eligible for activation only when both the event matches and the condition callback returns its expected value.
When a parent state defines multiple entry points, the library SHALL resolve activation as follows: (1) evaluate entry points that define an event filter and/or a condition, and activate all whose filters are satisfied, without activating entry points that define neither; (2) if no filtered entry point is satisfied, activate all entry points that define neither an event filter nor a condition; (3) if no entry point defines an event filter or condition, activate all entry points. Within each case, eligible entry points SHALL be activated in registration order.
When a transition enters a parent state that defines entry points but none of them is eligible for activation, the library SHALL cancel the transition and leave the active state configuration unchanged.
When no applicable transition for an event can be executed in the active substate, the library SHALL evaluate applicable transitions in successive ancestor states until a transition can be executed or the topmost state is reached.
When entering a hierarchical state configuration, the library SHALL execute entry callbacks in top-down order (ancestor before descendant). When exiting, the library SHALL execute exit callbacks in bottom-up order (descendant before ancestor).
The library SHALL allow multiple states to be simultaneously active as a result of executing all satisfied transitions for a single event and of activating multiple eligible entry points. The library SHALL maintain the active state of each concurrently active branch independently.
The library SHALL evaluate each event against all concurrently active states in a deterministic order (registration order). Each active state SHALL evaluate the event according to its own transition definitions independently of the others. A transition executed by one active state SHALL leave the other active states free to evaluate the same event.
When a transition targets a state that is already part of the active state configuration, the library SHALL execute that transition's guard condition, source-state exit callback, and transition callback, but SHALL NOT execute the target state's entry callback or its state-changed callback. The target state SHALL remain active and its active substate configuration SHALL be left unchanged.
When a transition targets an already-active composite state, the library SHALL leave the composite state and its entire active substate configuration active and unchanged, and SHALL NOT re-enter, re-initialize, or reset any state within that subtree. This requirement does not govern an external self-transition, which resets the target by performing a full exit and re-entry.
When re-entering a composite state via a shallow history state, the library SHALL restore all direct child states of that composite that were active immediately before its most recent deactivation.
The recorded shallow history of a parent state SHALL always reflect all direct child states that were active immediately before the most recent deactivation of those children, independently of whether the parent itself was exited. The recorded children SHALL be used for subsequent shallow history restoration.
When re-entering a composite state via a deep history state, the library SHALL restore the entire substate hierarchy that was active when the composite was last deactivated, including all concurrently active substates across parallel regions.
The recorded deep history of a parent state SHALL always reflect the complete active substate hierarchy that was active immediately before the most recent deactivation of that hierarchy, independently of whether the parent itself was exited. The recorded hierarchy SHALL be used for subsequent deep history restoration.
The library SHALL allow a default target state to be specified for a history state. When a transition targets a history state and no history has been recorded, the library SHALL activate the default target state instead.
When a transition targets a history state for which no history has been recorded and no default target state has been defined, the library SHALL enter the history state's parent and resolve its active child through the parent's entry point.
The library SHALL support an optional application-defined callback associated with a history state. The callback SHALL execute whenever the history state is activated, regardless of whether it activates a recorded target or its default target. The callback SHALL execute before the normal entry callback for the activated state.
The library SHALL support registration of transitions between states triggered by type-safe event identifiers. Each transition SHALL specify a source state, a target state, and a triggering event.
The library SHALL support associating a guard condition callback with a transition. The guard callback SHALL return a boolean result. The transition SHALL execute only when the guard result matches the configured expected value.
The library SHALL support registration of otherwise transitions that execute when no guarded transition for the same event from the same source state is satisfied. Otherwise transitions SHALL be evaluated after all guarded transitions have been evaluated and rejected.
When multiple transitions from the same state match the same event, the library SHALL evaluate guard conditions in registration order and SHALL execute the first transition whose guard condition is satisfied. Registration order SHALL be the defined priority mechanism.
When a state has multiple transitions that match the same event, including a combination of self-transitions and a regular (non-self) transition, the library SHALL execute them in the following priority order: internal self-transitions first, then external self-transitions, then regular transitions.
The library SHALL provide a synchronous transition operation that blocks the caller until the transition completes or fails. If the transition does not complete within a configurable timeout period, the operation SHALL return a timeout indication. A timeout indication SHALL indicate that the transition outcome is not available to the caller at the time the operation returns.
The library SHALL provide the ability to discard all pending events (both externally submitted and internally generated) before processing a newly requested transition.
The library SHALL provide an operation to determine whether a specified event can cause a successful transition from the current active state configuration without changing state machine state. The operation SHALL evaluate guard conditions only and SHALL be side-effect-free with respect to callbacks, active state configuration, and conditional entry points.
The library SHALL invoke an application-defined callback when a transition request does not result in a successful state change. The callback SHALL distinguish between transition rejection (no transition matched the event from the current state after guard evaluation) and transition cancellation (a matching transition was selected but cancelled by application-defined callback behavior).
The library SHALL support associating application-defined data with a transition request. The associated data SHALL be delivered to every callback executed as part of that transition - including the guard condition, exit, transition, entry, and state-changed callbacks - and SHALL retain the value provided at submission time.
The library SHALL support associating transition data of the following types: signed integers of 1, 2, 4 and 8 bytes; unsigned integers of 1, 2, 4 and 8 bytes; double-precision floating-point values; boolean values; character strings; byte arrays; and the composite types list, vector, map and pair whose elements are themselves supported data values. The library SHALL additionally support an opaque application-defined (custom) type that is carried through the transition without interpretation.
The library SHALL provide its own type-erased value container (the Variant type) for storing transition-associated data, and SHALL use this container to carry that data through transitions. The container SHALL store a single value together with its data type, allow the stored type to be queried at run time, and provide retrieval of the stored value.
When a transition is cancelled by application-defined behavior after the source state has been exited, the library SHALL restore the source state as active by re-entering it, executing its entry callback and state-changed callback as if it had been entered by a normal transition. When cancellation occurs before the source state is exited, the source state SHALL remain active with no additional callbacks. When the source state is still active because a concurrent branch shares it, restoration SHALL NOT re-enter it. Externally visible side effects performed by callbacks that executed before the cancellation SHALL remain in effect (the library does not undo them).
The library SHALL return an error indication when an asynchronous event submission cannot be accepted because the event queue has reached its capacity limit.
For a non-hierarchical transition from source state S to target state T, the library SHALL execute applicable steps in the following order: (1) evaluate the transition guard condition, (2) source state exit callback, (3) transition callback, (4) target state entry callback, (5) target state state-changed callback. Guard evaluation SHALL complete before the source state exit callback executes; when the guard is not satisfied, no exit, transition, entry, or state-changed callback SHALL execute for that transition.
The library SHALL allow a state exit callback to cancel the in-progress transition by returning a cancellation indication. When an exit callback cancels, no further callbacks in the transition sequence SHALL execute, the source state SHALL remain active, and no compensating callbacks SHALL be invoked for the cancellation.
The library SHALL allow a state entry callback to cancel the in-progress transition by returning a cancellation indication. When an entry callback cancels, the library SHALL stop the remaining callback sequence and restore the source state as active by re-entering it. Side effects of callbacks already executed before the cancellation are not undone.
When a single event triggers execution of multiple transitions, cancellation of one transition by application-defined callback behavior SHALL affect only that transition. The remaining transitions SHALL continue to be executed independently.
When a transition that restores a history state is cancelled before completion, the library SHALL apply the same cancellation strategy as for a regular transition and restore the source state as active.
The library SHALL execute an application-defined entry callback when a state is entered as part of a transition. The entry callback SHALL receive any data associated with the triggering transition.
The library SHALL execute an application-defined state-changed callback after a state has become fully active. The state-changed callback SHALL receive any data associated with the triggering transition.
The library SHALL support an application-defined callback associated with a transition. The transition callback SHALL receive any data associated with the triggering transition. The transition callback is non-cancellable.
The library SHALL treat application-defined behavior as actions. An application-defined callback SHALL be one action type; declarative timer control and declarative event generation SHALL be additional action types. The library SHALL support binding callback actions using at least: class member function pointers, free function pointers, and lambda/functor objects.
The library SHALL support timer control actions (start, stop, restart of a specified timer) that can be attached to state entry, state exit, and transitions.
The library SHALL support attaching multiple actions to a single state entry, state exit, or transition. Multiple actions attached to the same point SHALL be executed in their defined order.
The library SHALL provide at least one event-processing implementation sufficient to execute a state machine without requiring integration with an external event-processing framework.
The library SHALL provide an asynchronous event submission operation where the caller returns immediately without waiting for the event to be processed. The submitted event SHALL be queued for later processing by the event-processing context.
The library SHALL process externally submitted events in first-in-first-out order within the external event queue. The library SHALL maintain FIFO ordering unless pending events are explicitly discarded by the application.
The library SHALL process internally generated events before the next externally submitted event. Internally generated events include events produced by declarative actions, timer expirations processed during a transition, and events generated as a result of entering a final state. All pending internally generated events, including those generated recursively, SHALL be processed before the next externally submitted event. Internally generated events SHALL be processed in generation order.
When application-defined behavior triggered by an event submits additional events, the library SHALL defer those events for later processing rather than executing them immediately within the current processing cycle.
When a synchronous transition is requested from within the state machine's own execution context, such as from inside a state or transition callback, the library SHALL NOT block waiting for that transition to complete; it SHALL cancel the synchronous request and report failure to the caller.
The library SHALL provide a uniform mechanism for reporting operation failures to the caller. All operations capable of failing SHALL use this common mechanism to communicate failure to the caller.
The library SHALL guarantee that timer control operations (start, stop, restart, and status query) preserve timer state consistency when invoked concurrently from multiple threads. Each operation SHALL produce a valid timer state upon completion.
The library SHALL guarantee that externally submitted transition requests and event submissions operate correctly when invoked concurrently from multiple execution contexts. The library SHALL preserve data integrity and state configuration consistency throughout concurrent access.
The library SHALL provide a transition mechanism suitable for execution from restricted contexts in which dynamic memory allocation is not permitted. The mechanism SHALL use only pre-allocated resources at invocation time.
The library SHALL support a compile-time configuration option to enable or disable thread-safety mechanisms. When thread safety is disabled, the library SHALL omit synchronization operations from event submission, timer operations, and transition operations. When disabled, the application is responsible for ensuring single-threaded access.
Structural configuration operations (registration of states, transitions, and actions) SHALL be performed from a single execution context. This constraint applies only during the configuration phase preceding initialization and does not restrict runtime operation.
The library SHALL support registration of timers identified by type-safe timer identifiers. Each timer SHALL be associated with a specified event identifier. When a timer expires, the library SHALL deliver the associated event to the state machine for processing.
The library SHALL support single-shot timers that fire once after the specified interval elapses and then stop automatically without further intervention.
The library SHALL support repeating timers that fire periodically at the specified interval until explicitly stopped. Each firing SHALL deliver the associated event to the state machine.
The library SHALL provide an operation to stop a currently running timer. Stopping a timer that is not running SHALL have no adverse effect. After a timer stop operation completes, the timer SHALL generate no further expiration events. Any expiration event already queued but not yet processed at the time of stop SHALL be discarded.
The library SHALL provide an operation to restart a timer with its original parameters, resetting the countdown from zero. Restart SHALL be equivalent to stop followed by start: any previously queued expiration event SHALL be discarded before the new countdown begins.
The library SHALL provide an operation to determine whether a specific timer is currently running. The query SHALL return a definitive running or not-running indication.
The library SHALL support multiple timers running concurrently. Each timer SHALL be identified by a distinct type-safe timer identifier, and start, stop, restart, and status-query operations on one timer SHALL affect only the timer named by that identifier and SHALL NOT disturb any other running timer.
The code generation tool SHALL parse W3C SCXML format files as input for defining state machine structure. The tool SHALL support the hsmcpp-relevant subset of SCXML elements including states, transitions, parallel regions, and history states.
The code generation tool SHALL produce C++ source and header files that implement the state machine defined by the input SCXML model. The generated artifacts SHALL include all state, event, and timer identifier definitions and the complete structural configuration (state registration, transition registration, timer bindings).
The generated code SHALL use a base class pattern where the generated class provides structure registration and declares virtual callback methods. Applications SHALL derive from the generated class to implement callback behavior. Regeneration of the base class SHALL preserve application-derived code without requiring changes to it.
The code generation tool SHALL validate the input SCXML model before generating code. The tool SHALL report errors for structural and semantic violations that would prevent valid state machine execution. Minimum validated conditions SHALL include: undefined state references in transitions, circular hierarchies, and missing initial states in composite states.
The code generation tool SHALL produce PlantUML state diagram files from SCXML input. The generated diagrams SHALL represent states, transitions, guards, hierarchical relationships, and parallel regions.
The project SHALL provide CMake integration that automatically invokes the code generation tool when source SCXML files change, ensuring generated artifacts are regenerated during the build.
When trace logging is enabled, the library SHALL emit human-readable trace messages describing state machine activity, including state transitions, event processing, and timer operations.
The library SHALL allow the application to provide a callback that is invoked for each trace message with the message text as a string argument. When no callback is provided, the library SHALL use a default platform-specific trace output.
When structured execution logging is enabled, the library SHALL record state machine execution information in a defined structured format. The log SHALL capture state transitions (source, target, event), event submissions, and timer operations (start, stop, expire), with sufficient ordering information to reconstruct the execution sequence.
The structured execution log format SHALL be documented and parseable, enabling compatible diagnostic tools to replay and inspect state machine execution sequences.
The library SHALL provide independent CMake configuration options that enable or disable trace logging and structured execution logging at build time. When a logging type is disabled, its implementation SHALL be excluded from the built binary.
The library SHALL provide an API to enable and disable recording of the structured execution log at runtime without rebuilding. When enabled, the library SHALL begin recording to the configured log destination; when disabled, it SHALL stop recording and close the log. Changes SHALL take effect for the next logged event.
The library SHALL support registering human-readable string names for state and event identifiers. When logging is active, the library SHALL include registered names in log output.
The Arduino configuration SHALL support the restricted-context transition mechanism. The Arduino configuration SHALL operate without thread-safety overhead.
The library SHALL support independently enabling or disabling the following capabilities via CMake configuration: trace logging, structured execution logging, structure validation, and thread safety.
The library SHALL support exit point pseudo-states within a composite state. Activation of a specific exit point by a child state SHALL select the corresponding outgoing transition from the parent state.
When an exit point is activated and no event was registered for it, the library SHALL exit the parent state using the same event that activated the exit point.
When an exit point is activated and an event was registered for it, the library SHALL exit the parent state using the registered event instead of the event that activated the exit point.
The code generation tool SHALL parse and interpret the following SCXML constructs: scxml (initial, xmlns), state (id, initial), parallel (id), transition (event, cond, target, type), initial, final (id), onentry, onexit, and history (id, type).
The code generation tool SHALL interpret the following constructs with hsmcpp-specific meaning: the script element (within onentry, onexit, and transition) as a named application callback; the invoke element srcexpr attribute as a named state-changed callback; and the state src attribute (and xi:include) as external-file composition.
Timer expiration precision SHALL be bounded by the timing facilities of the platform dispatcher in use. The delivered precision SHALL be that provided by the underlying platform timing facility.
The library SHALL provide an operation to query the current execution status of the state machine, distinguishing at least the uninitialized, running, and terminated conditions.