View Source Finitomata behaviour (Finitomata v0.7.2)
bird-view
Bird View
Finitomata
provides a boilerplate for FSM implementation, allowing to concentrate on the business logic rather than on the process management and transitions/events consistency tweaking.
It reads a description of the FSM from a string in PlantUML, Mermaid, or even custom format. Basically, it looks more or less like this
plantuml
PlantUML
[*] --> s1 : to_s1
s1 --> s2 : to_s2
s1 --> s3 : to_s3
s2 --> [*] : ok
s3 --> [*] : ok
mermaid
Mermaid
s1 --> |to_s2| s2
s1 --> |to_s3| s3
note
Note
mermaid
does not allow to explicitly specify transitions (and hence event names) from the starting state and to the end state(s), these states names are implicitly set to:*
and events to:__start__
and:__end__
respectively.
Finitomata
validates the FSM is consistent, namely it has a single initial state, one or more final states, and no orphan states. If everything is OK, it generates a GenServer
that could be used both alone, and with provided supervision tree. This GenServer
requires to implement three callbacks
on_transition/4
— mandatoryon_failure/3
— optionalon_enter/2
— optionalon_exit/2
— optionalon_terminate/1
— optionalon_timer/2
— optional
All the callbacks do have a default implementation, that would perfectly handle transitions having a single to state and not requiring any additional business logic attached.
Upon start, it moves to the next to initial state and sits there awaiting for the transition request. Then it would call an on_transition/4
callback and move to the next state, or remain in the current one, according to the response.
Upon reaching a final state, it would terminate itself. The process keeps all the history of states it went through, and might have a payload in its state.
special-events
Special Events
If the event name is ended with a bang (e. g. idle --> |start!| started
) and
this transition is the only one allowed from this state, it’d be considered as
determined and FSM will be transitioned into the new state instantly.
If the event name is ended with a question mark (e. g. idle --> |start?| started
,)
the transition is considered as expected to fail; no on_failure/2
callback would
be called on failure and no log warning will be printed.
fsm-tuning-and-configuration
FSM Tuning and Configuration
recurrent-callback
Recurrent Callback
If timer: non_neg_integer()
option is passed to use Finitomata
,
then Finitomata.on_timer/2
callback will be executed recurrently.
This might be helpful if FSM needs to update its state from the outside
world on regular basis.
automatic-fsm-termination
Automatic FSM Termination
If auto_terminate: true() | state() | [state()]
option is passed to use Finitomata
,
the special __end__
event to transition to the end state will be called automatically
under the hood, if the current state is either listed explicitly, or if the value of
the parameter is true
.
ensuring-state-entry
Ensuring State Entry
If ensure_entry: true() | [state()]
option is passed to use Finitomata
, the transition
attempt will be retried with {:continue, {:transition, {event(), event_payload()}}}
message
until succeeded. Neither on_failure/2
callback is called nor warning message is logged.
The payload would be updated to hold __retries__: pos_integer()
key. If the payload was not a map,
it will be converted to a map %{payload: payload}
.
example
Example
Let’s define the FSM instance
defmodule MyFSM do
@plantuml """
[*] --> s1 : to_s1
s1 --> s2 : to_s2
s1 --> s3 : to_s3
s2 --> [*] : ok
s3 --> [*] : ok
"""
use Finitomata, fsm: @plantuml, syntax: Finitomata.PlantUML
## or uncomment lines below for Mermaid syntax
# @mermaid """
# s1 --> |to_s2| s2
# s1 --> |to_s3| s3
# """
# use Finitomata, fsm: @mermaid, syntax: Finitomata.Mermaid
@impl Finitomata
def on_transition(:s1, :to_s2, event_payload, state_payload),
do: {:ok, :s2, state_payload}
end
Now we can play with it a bit.
children = [Finitomata.child_spec()]
Supervisor.start_link(children, strategy: :one_for_one)
Finitomata.start_fsm MyFSM, "My first FSM", %{foo: :bar}
Finitomata.transition "My first FSM", {:to_s2, nil}
Finitomata.state "My first FSM"
#⇒ %Finitomata.State{current: :s2, history: [:s1], payload: %{foo: :bar}}
Finitomata.allowed? "My first FSM", :* # state
#⇒ true
Finitomata.responds? "My first FSM", :to_s2 # event
#⇒ false
Finitomata.transition "My first FSM", {:ok, nil} # to final state
#⇒ [info] [◉ ⇄] [state: %Finitomata.State{current: :s2, history: [:s1], payload: %{foo: :bar}}]
Finitomata.alive? "My first FSM"
#⇒ false
Typically, one would implement all the on_transition/4
handlers, pattern matching on the state/event.
Link to this section Summary
Types
The payload that can be passed to each call to transition/3
The name of the FSM (might be any term, but it must be unique)
Error types of FSM validation
Callbacks
This callback will be called on entering the state.
This callback will be called on exiting the state.
This callback will be called if the transition failed to complete to allow the consumer to take an action upon failure.
This callback will be called on transition to the final state to allow the consumer to perform some cleanup, or like.
This callback will be called recurrently if timer: pos_integer()
option has been given to use Finitomata
.
This callback will be called from each transition processor.
Functions
Returns true
if the supervision tree is alive, false
otherwise.
Returns true
if the FSM specified is alive, false
otherwise.
Returns true
if the transition to the state state
is possible, false
otherwise.
Returns true
if the transition by the event event
is possible, false
otherwise.
Starts the FSM instance.
The state of the FSM.
Initiates the transition.
Link to this section Types
@type event_payload() :: any()
The payload that can be passed to each call to transition/3
@type fsm_name() :: any()
The name of the FSM (might be any term, but it must be unique)
@type validation_error() ::
:initial_state | :final_state | :orphan_from_state | :orphan_to_state
Error types of FSM validation
Link to this section Callbacks
@callback on_enter(Finitomata.Transition.state(), Finitomata.State.t()) :: :ok
This callback will be called on entering the state.
@callback on_exit(Finitomata.Transition.state(), Finitomata.State.t()) :: :ok
This callback will be called on exiting the state.
@callback on_failure(Finitomata.Transition.event(), event_payload(), Finitomata.State.t()) :: :ok
This callback will be called if the transition failed to complete to allow the consumer to take an action upon failure.
@callback on_terminate(Finitomata.State.t()) :: :ok
This callback will be called on transition to the final state to allow the consumer to perform some cleanup, or like.
@callback on_timer(Finitomata.Transition.state(), Finitomata.State.t()) :: :ok | {:transition, {Finitomata.Transition.event(), event_payload()}, Finitomata.State.payload()} | {:transition, Finitomata.Transition.event(), Finitomata.State.payload()} | {:reschedule, non_neg_integer()}
This callback will be called recurrently if timer: pos_integer()
option has been given to use Finitomata
.
@callback on_transition( Finitomata.Transition.state(), Finitomata.Transition.event(), event_payload(), Finitomata.State.payload() ) :: {:ok, Finitomata.Transition.state(), Finitomata.State.payload()} | {:error, any()}
This callback will be called from each transition processor.
Link to this section Functions
@spec alive?() :: boolean()
Returns true
if the supervision tree is alive, false
otherwise.
Returns true
if the FSM specified is alive, false
otherwise.
@spec allowed?(fsm_name(), Finitomata.Transition.state()) :: boolean()
Returns true
if the transition to the state state
is possible, false
otherwise.
@spec responds?(fsm_name(), Finitomata.Transition.event()) :: boolean()
Returns true
if the transition by the event event
is possible, false
otherwise.
@spec start_fsm(module(), any(), any()) :: DynamicSupervisor.on_start_child()
Starts the FSM instance.
The arguments are
- the implementation of FSM (the module, having
use Finitomata
) - the name of the FSM (might be any term, but it must be unique)
- the payload to be carried in the FSM state during the lifecycle
The FSM is started supervised.
@spec state(fsm_name()) :: Finitomata.State.t()
The state of the FSM.
@spec transition( fsm_name(), {Finitomata.Transition.event(), Finitomata.State.payload()}, non_neg_integer() ) :: :ok
Initiates the transition.
The arguments are
- the name of the FSM
{event, event_payload}
tuple; the payload will be passed to the respectiveon_transition/4
calldelay
(optional) the interval in milliseconds to apply transition after