Working With Akka FSM

We can think Akka FSM as a set of relations. This is from Akka FSM documentation.
State(S) x Event(E) -> Actions(A), State(S’)
We can read it as: When an Actor is in a State(S) and an event(E) occurs. Then Actor performs Actions(A) and transitions to state(S’)

Let’s have a look at a simple example to understand how it works.

FSM actors are some sort of combination of their state and data. State are one of the states an FSM actor will be at a given snapshot of time. Data on the other hand represents state machine’s internal state. They will end up being type parameters used when we code FSM actor.

We begin with an example of State which can either be RED or GREEN. Below is the code defining them.

sealed trait State
case object RED extends State
case object GREEN extends State

For this simple example we may not need to work at all on Data. We could have used Int but we can use our definition as well. Let’s use Data class definition defined below.

case class Data

For an FSM actor that alternate to RED and GREEN we need to pass Event’s to it. For our scenario one event is enough to transition. Below is its message definition.

case class AlternateColor

So, we have built class definitions for Akka FSM actor. They are: states actor can be in, events that it will need to handle and the data. Now we can direct our attention to FSM actor.

To create FSM actor we need to mixin FSM trait to an actor. It takes in type parameters for State and Data. Below is the pseudocode of how we can use it.

class ColorFSMActor extends Actor with FSM[State, Data] {
  startWith(<"one of possible states">, <"some initial data like empty List">)

  when(<"one of possible states">) {
    // Some Code
  }

  // Transition elided
  when(<"one of possible states">) {
    // Some Code
  }

  ....

  onTransition {
    case <"one of possible states"> -> <"one of other possible states"> =>
      // Some Code
    .....
  }
  
  initialize
}

In our case we can start with a given state RED. We have two states, so we have two when block for each state. One for RED and one for GREEN.

Whenever FSM actor gets an Event of AlternateColor it changes its state to the other. There is also onTransition block that we can use. There is an arrow operator we can put between pair of states. For our case we can output a message via print line when state transitions from one to other.

Below is the complete implementation of the desired behavior.

class ColorFSMActor extends Actor with FSM[State, Data] {
  startWith(RED, Data())

  when(RED) {
    case Event(AlternateColor, _) => goto(GREEN)
  }

  when(GREEN) {
    case Event(AlternateColor, _) => goto(RED)
  }

  onTransition {
    case RED -> GREEN => println("I am in RED and going to GREEN")
    case GREEN -> RED => println("I am in GREEN and going to RED")
  }

  initialize
}

To see FSM actor in action we can create actor and send messages to it. We will see the print log of transition from RED to GREEN and from GREEN to RED. Below is the code snippet.

  val system = ActorSystem("fsm")
  val colorFSMActor = system.actorOf(Props[ColorFSMActor])
  (1 to 10) foreach { i => colorFSMActor ! AlternateColor }

you should see following in the logs:

I am in RED and going to GREEN
I am in GREEN and going to RED
I am in RED and going to GREEN
I am in GREEN and going to RED
I am in RED and going to GREEN
I am in GREEN and going to RED
I am in RED and going to GREEN
I am in GREEN and going to RED
I am in RED and going to GREEN
I am in GREEN and going to RED

This is a simple example but is useful for general understanding of Akka FSM actors. There are excellent use cases for FSM’s for example throttling messages. For more detailed introduction please also visit awesome Akka FSM documentation.