StateMachine
Types
Provides StateMachine specific notifications and also duplicates IState.Listener and Transition.Listener functionality allowing to listen all notifications in one place if necessary.
Properties
Configuration arguments which were used to create the machine
Indicates that machine is started and has clear initial state (has not processed any events but StartEvent yet)
Indicates that machine was destroyed. There is no way to restore machine instance from this state. Once machine became destroyed it is not usable anymore.
If machine catches exception from client code (listeners callbacks) it stores it until event processing completes, and passes it to this handler. That keeps machine in well-defined predictable state and allows to complete all required notifications. Note that generally speaking listeners should not throw.
Functions
Set of states that the state is currently in. Including state itself if selfIncluding is true. Internal states of nested machines are not included.
Helper method for adding final states. This is exactly the same as simply call IState.addState but makes code more self expressive.
A shortcut for IState.addState and IState.setInitialState calls
Creates type safe argument transition to DataState.
Shortcut function for type safe argument transition. Data transition can be target-less (self-targeted), it is useful to update DataState data Note that transition must be TransitionType.EXTERNAL to update data.
Data transition, otherwise same as transitionOn
Destroys machine structure clearing all listeners, states etc. This a terminal operation, means that machine cannot be used anymore.
Blocking analog of destroy
Export StateMachine to Mermaid state diagram
Blocking analog for exportToMermaid
Export StateMachine to PlantUML state diagram
Blocking analog for exportToPlantUml
Find state by type. Search by type is suitable when using own state subclasses that usually do not have a name. Only on state should match the type or exception will be thrown.
Get state by name. This might be used to start listening to state after state machine setup.
For internal use. Workaround that Kotlin does not support recursive inline functions.
Find transition by Event type. This might be used to start listening to transition after state machine setup.
Find transition by name. This might be used to start listening to transition after state machine setup.
A shortcut for state and IState.setInitialState calls
Processes Event. Machine must be started to be able to process events.
Blocking analog of StateMachine.processEvent which can be called from usual (not suspendable) code.
Require transition by Event type
Shortcut for StateMachine.stopBlocking and StateMachine.start sequence calls
Processes RecordedEvents with purpose of restoring a StateMachine to a state configuration as it was before (when the record was made). Starts the StateMachine if necessary and returns RestorationResult allowing to inspect how the restoration was processed. Specified RestorationResultValidator will be called to validate the result so do not have to remember to perform validation of the RestorationResult.
Blocking restoreByRecordedEvents alternative
Initial child state is required if child mode is ChildMode.EXCLUSIVE and a state has children
Allows to target multiple states (they must be parallel state sub-children). Implemented by targetParallelStates
Starts machine from particular state
Vararg overload for targeting multiple states
Suspendable stopBlocking analog. Should be preferred especially if called from machine notifications.
Forces state machine to stop Warning: calling this function from notification callback may cause deadlock if you are using single threaded coroutineContext, so stop should be preferred.
Returns StateMachine.IgnoredEventHandler implementation that throws exception. This might be useful if you want to control that all events are handled (not skipped) by your StateMachine.
Returns StateMachine.PendingEventHandler implementation that throws exception. This is an old default behaviour.
Creates transition. You can specify guard function. Such guarded transition is triggered only when guard function returns true.
Shortcut overload for transition with an optional target state
Creates conditional transition. Caller should specify lambda which calculates TransitionDirection. For example target state may be different depending on some condition.
This is more powerful version of transition function. Here target state is a lambda which returns desired State. This allows to use lateinit state variables for recursively depending states and choose target state depending on application business logic.
Rolls back transition (usually it is navigating machine to previous state). Previous states are stored in a stack, so this method mey be called multiple times if needed. This function has same effect as alternative syntax processEvent(UndoEvent), but throws if undo feature is not enabled.
Blocking analog of undo