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 / :state_diagram

[*] --> s1 : to_s1
s1 --> s2 : to_s2
s1 --> s3 : to_s3
s2 --> [*] : ok
s3 --> [*] : ok

Mermaid / :flowchart

s1 --> |to_s2| s2
s1 --> |to_s3| s3

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 six callbacks

• on_transition/4 — mandatory
• on_failure/3 — optional
• on_enter/2 — optional
• on_exit/2 — optional
• on_terminate/1 — optional
• on_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

If the event name is ended with a bang (e. g. idle --> |start!| started) and this event is the only one allowed from this state (there might be several transitions though,) 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

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

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

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}.

Examples

See examples directory for real-life examples of Finitomata usage.

Example

Let’s define the FSM instance

defmodule MyFSM do
  @fsm """
  s1 --> |to_s2| s2
  s1 --> |to_s3| s3
  """
  use Finitomata, fsm: @fsm, syntax: :flowchart

  ## or uncomment lines below for `:state_diagram` syntax
  # @fsm """
  # [*] --> s1 : to_s1
  # s1 --> s2 : to_s2
  # s1 --> s3 : to_s3
  # s2 --> [*] : __end__
  # s3 --> [*] : __end__
  # """
  # use Finitomata, fsm: @fsm, syntax: :state_diagram

  @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.

# or embed into supervision tree using `Finitomata.child_spec()`
{:ok, _pid} = Finitomata.start_link()

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", {:__end__, 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.

Use with Telemetría

telemetria library can be used to send all the state changes to the backend, configured by this library. To enable metrics sending, one should do the following.

Add telemetria dependency

telemetria dependency should be added alongside its backend dependency. For :telemetry backend, that would be

defp deps do
  [
    ...
    {:telemetry, "~> 1.0"},
    {:telemetry_poller, "~> 1.0"},
    {:telemetria, "~> 0.22"}
  ]

Configure telemetria library in a compile-time config

config :telemetria,
  backend: Telemetria.Backend.Telemetry,
  purge_level: :debug,
  level: :info,

Add :telemetria compiler

:telemetria compiler should be added to the list of mix compilers, alongside :finitomata compiler.

def project do
  [
    ...
    compilers: [:finitomata, :telemetria | Mix.compilers()],
    ...
  ]
end

Configure :finitomata to use :telemetria

The configuration parameter [:finitomata, :telemetria] accepts the following values:

• false — :telemetria metrics won’t be sent
• true — :telemetria metrics will be send for all the callbacks
• [callback, ...] — :telemetria metrics will be send for the specified callbacks

Available callbacks may be seen below in this module documentation. Please note, that the events names would be event: [__MODULE__, :safe_on_transition] and like.

config :finitomata, :telemetria, true

See telemetria docs for further config details.

Options to use Finitomata

• :fsm (String.t/0) - Required. The FSM declaration with the syntax defined by syntax option.

• :forks (list of tuple of atom/0, values) - The keyword list of states and modules where the FSM forks and awaits for another process to finish The default value is [].

• :syntax - The FSM dialect parser to convert the declaration to internal FSM representation. The default value is :flowchart.

• :impl_for - The list of transitions to inject default implementation for. The default value is :all.

• :timer - The interval to call on_timer/2 recurrent event. The default value is false.

• :auto_terminate - When true, the transition to the end state is initiated automatically. The default value is false.

• :cache_state (boolean/0) - When true, the FSM state is cached in :persistent_term The default value is true.

• :hibernate - When true, the FSM process is hibernated between transitions The default value is false.

• :ensure_entry - The list of states to retry transition to until succeeded. The default value is [].

• :shutdown (pos_integer/0) - The shutdown interval for the GenServer behind the FSM. The default value is 5000.

• :persistency - The implementation of Finitomata.Persistency behaviour to backup FSM with a persistent storage. The default value is nil.

• :listener - The implementation of Finitomata.Listener behaviour or a GenServer.name() to receive notification after transitions. The default value is nil.

• :mox_envs - The list of environments to implement mox listener for The default value is [:test, :finitomata].