Finitomata :: FSM boilerplate based on callbacks

Your Libraries & OS Mentoring Libraries
1

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

It 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 — mandatory
  • on_failure/3 — optional
  • on_terminate/1 — 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.

Example:

defmodule MyFSM do
  @fsm """
  [*] --> s1 : to_s1
  s1 --> s2 : to_s2
  s1 --> s3 : to_s3
  s2 --> [*] : ok
  s3 --> [*] : ok
  """

  use Finitomata, @fsm

  def on_transition(:s1, :to_s2, event_payload, state_payload),
    do: {:ok, :s2, state_payload}
end
5 Likes
2

@mudasobwa thanks for sharing this library, I’ve used gen_statem a few times in the past and I think your library makes these kinds of use-cases a lot more ergonomic. Have you ever thought making a compile-time dependency, rather than a runtime dependency?

My thought here is that I could use something like finitomata to help me develop a FSM module, but I could generate an elixir/erlang file with all of the expansion done so that I don’t have to specify finitomata as a dependency of my library. This also means that other libraries could use different versions of the tool without need to resolve to a shared version.

Just curious if you’ve considered a use-case like that, or maybe I should give it a try myself to see how it goes?

3

Well, there is no runtime dependency already, besides provided supervision subtree, registry, and helpers to deal with dynamic children.

If you don’t need all the above and are ready to manage the processes yourselves, you don’t depend on Finitomata in runtime. use Finitomata injects the code into your module in compile time. Generating this boilerplate code instead of injecting is not a big deal, a simple call to Macro.to_string/1 would do (e. g. from __before_compile__ callback.)

mix task to generate such a module is also trivial. I personally don’t like generators because the code they produce is hard to support, code injection works better. But I’d love to see a PR with a mix task generating the module.

4

FWIW, this thread contains links to other similar libraries and usage examples.

5

Thanks @mudasobwa your breakdown definitely improved my thinking. I can see how a generator might be a pain to deal with in source control etc. And the distinction between run-time, compile-time and deploy-time is helpful as well. Thanks again for the library, I’ll give it a run

1 Like
6

After some hesitation, two new callbacks have been added.

  • on_enter/2 — optional
  • on_exit/2 — optional
7

Package published to finitomata | Hex
(25ec5990045d025fba2bb1c59a92e08fc8a045fdd347fcdcb885f22c75a1f2d2)

Introduces Infinitomata module as a drop-in replacement of Finitomata.{start_fsm/4,transition/4,state/3}. It transparently runs in a cluster, leveraging process groups :pg to keep track of spawned instances.

Example from tests:

defmodule InfinitomataTest do
  use ExUnit.Case, async: true
  @moduletag :distributed

  setup do
    {_peers, _nodes} = Enfiladex.start_peers(3) # start 3 peers
    Enfiladex.block_call_everywhere(Infinitomata, :start_link, [])
  end

  test "many instances (distributed)" do
    for i <- 1..10 do
      Infinitomata.start_fsm("FSM_#{i}", Finitomata.Test.Log, %{instance: i})
    end

    assert Infinitomata.count(Infinitomata) == 10

    for i <- 1..10 do
      Infinitomata.transition("FSM_#{i}", :accept)
    end

    assert %{"FSM_1" => %{}} = Infinitomata.all(Infinitomata)

    for i <- 1..10 do
      Infinitomata.transition("FSM_#{i}", :__end__)
    end

    Process.sleep(1_000)

    assert Infinitomata.count(Infinitomata) == 0 # all finished ending state
    assert Infinitomata.all(Infinitomata) == %{}
  end
end
2 Likes
8

Finitomata got Throttler, fully obsoleting Siblings.

Last version transparently runs on distributed erlang with the ability to throttle transitions, if necessary.

9

Another blog post about Finitomata.

10

To support my own rant about making our libraries test-friendly (based on finitomata example), I implemented the test scaffold generation, based on the FSM shape, collected during the compile time.

 mix finitomata.generate.test --module MyApp.FSM

The above would generate a scaffold for checking all the possible paths in the FSM declaration. Enjoy.

https://hexdocs.pm/finitomata/Finitomata.ExUnit.html#module-test-scaffold-generation

1 Like