akka : state machines

In this post we will look at 2 ways you can write state machines with Akka. We will firstly examine the more primitive (but easily understandable) approach, and then look into the more sophisticated approach offered by AkkaFSM.

What Is A State Machine?

For those of you out there that do not know what a state machine is.

This is what Wikipedia says about them

A finite-state machine (FSM) or finite-state automaton (FSA, plural: automata), or simply a state machine, is a mathematical model of computation used to design both computer programs and sequential logic circuits. It is conceived as an abstract machine that can be in one of a finite number of states. The machine is in only one state at a time; the state it is in at any given time is called the current state. It can change from one state to another when initiated by a triggering event or condition; this is called a transition. A particular FSM is defined by a list of its states, and the triggering condition for each transition.

UnBecome

The other way to swap out the message loop relies on having matching pairs of become/unbecome. Where the standard message loop is not replaced as such, but will use the last value on a stack of values as the message loop.

Care must taken to ensure the amount of push (become) and pop (unbecome) operations match, otherwise memory leaks may occur. Which is why this is not the default behavior.

Here is an example actor that uses the become/unbecome matched operations.

AkkaFSM

While become/unbecome will get the job done. Akka comes with a much better alternative called Akka FSM

Using Akka FSM you can not only handle states but also have state data, and add code against the movement from one state to the next, which as most people will know are known as “transitions”.

When using Akka FSM you may see a state machine expressed using this sort of notation

State(S) x Event(E) -> Actions (A), State(S’)

f we are in state S and the event E occurs, we should perform the actions A and make a transition to the state S’.

To use Akka FSM there are a number of things you can do. Some of them are mandatory and some you can opt into depending on your requirements. Lets have a look at some of the moving parts that make Akka FSM shine.

FSM[S,D]

In order to use Akka FSM you need to mixin the FSM trait. The trait itself looks like this

trait FSM[S, D]

Where S is the state type, and D is the data type.

startWith

You can choose what state the FSM starts in by using the startWith method which has the following signature.

startWith(stateName: S, stateData: D, timeout: Timeout = None): Unit

initialize

Calling initialilze()performs the transition into the initial state and sets up timers (if required).

when

when is used to match the state, and is also used to control the movement to a new state using the inbuilt goto method, or possibly stay in the current state.

When uses pattern matching to match the events that a particular state can handle. As stated it is completely valid to stay in the current state or move to a new state

The examples that follow below will show you both stay and goto in action.

whenUnhandled

You should obviously try and make sure you cover all the correct state movements in response to all the events your FSM knows about. But Akka FSM also comes with the whenUnhandled method for catching events that were not handled by YOUR state handling (when) logic.

onTransition

You may also monitor the movement from one state to the next and run some code when this occurs. This is accomplished using the onTransition method.

onTransition has the following signature

nTransition(transitionHandler: TransitionHandler): Unit

Where TransitionHandler is really just a PartialFunction that has the following generic parameters

PartialFunction[(S, S), Unit]

Where the tuple is a tuple of “from state” to “to state”.

Time for an example

Lightswitch Example

This first example is a very simply FSM, that has 2 states, On and Off. It doesn’t really need any state, however the Akka FSM trait, always needs a Data object. So in this case we simple use a base trait for the Data which we don’t really care about.

The idea behind this example is that the lightswitch can move from Off –> On, and On –> Off.

This example also shows a stateTimeout in action, where by the On state will move from On, if left in that state for more than 1 second.

import akka.actor._
import scala.language.postfixOps
import scala.io.StdIn
object Demo extends App {
RunLightSwitchDemo
def RunLightSwitchDemo : Unit = {
//create the actor system
val system = ActorSystem("StateMachineSystem")
val lightSwitchActor =
system.actorOf(Props(classOf[LightSwitchActor]),
"demo-LightSwitch")
println("sending PowerOff, should be off already")
lightSwitchActor ! PowerOff
//akka is async allow it some time to pick up message
//from its mailbox
Thread.sleep(500)
println("sending PowerOn")
lightSwitchActor ! PowerOn
//akka is async allow it some time to pick up message
//from its mailbox
Thread.sleep(500)
println("sending PowerOff")
lightSwitchActor ! PowerOff
//akka is async allow it some time to pick up message
//from its mailbox
Thread.sleep(500)
println("sending PowerOn")
lightSwitchActor ! PowerOn
//akka is async allow it some time to pick up message
//from its mailbox
Thread.sleep(500)
println("sleep for a while to allow 'On' state to timeout")
Thread.sleep(2000)
StdIn.readLine()
//shutdown the actor system
system.terminate()
StdIn.readLine()
}
}

When run we get the following results

sending PowerOff, should be off already[WARN] [09/06/2016 07:21:28.864] [StateMachineSystem-akka.actor.default-dispatcher-4] [akka://StateMachineSystem/user/demo-LightSwitch] received unhandled request PowerOff in state Off/NoDatasending PowerOnMoved from Off to Onsending PowerOffMoved from On to Offsending PowerOnMoved from Off to Onsleep for a while to allow ‘On’ state to timeout‘On’ state timed out, moving to ‘Off’Moved from On to Off

There is something interesting here, which is that we see an Unhandled event. Why is this?

Well this is due to the fact that this demo FSM starts in the Off state, and we send a PowerOff event. This is not handled in the when for the Off state.

So if we apply this amended code, and run the demo again. We would now see this output instead

sending PowerOff, should be off alreadyalready offsending PowerOnMoved from Off to Onsending PowerOffMoved from On to Offsending PowerOnMoved from Off to Onsleep for a while to allow ‘On’ state to timeout‘On’ state timed out, moving to ‘Off’Moved from On to Off

Buncher Example

I have basically taken this one straight from the official Akka FSM docs.

This example shall receive and queue messages while they arrive in a burst and send them on to another target actor after the burst ended or a flush request is received.

Here is the full code for this example. It is a slightly fuller example, so this time we use a proper set of data objects for the states.