FSM (Java with Lambda Support)

The AbstractFSM Class

The AbstractFSM abstract class is the base class used to implement an FSM. It implements Actor since an Actor is created to drive the FSM.

public class Buncher extends AbstractFSM<State, Data> {
  {
    // fsm body ...
  }
}

The AbstractFSM class takes two type parameters:

1. the supertype of all state names, usually an enum,
2. the type of the state data which are tracked by the AbstractFSM module itself.

Defining States

A state is defined by one or more invocations of the method

when(<name>[, stateTimeout = <timeout>])(stateFunction).

The given name must be an object which is type-compatible with the first type parameter given to the AbstractFSM class. This object is used as a hash key, so you must ensure that it properly implements equals and hashCode; in particular it must not be mutable. The easiest fit for these requirements are case objects.

If the stateTimeout parameter is given, then all transitions into this state, including staying, receive this timeout by default. Initiating the transition with an explicit timeout may be used to override this default, see Initiating Transitions for more information. The state timeout of any state may be changed during action processing with setStateTimeout(state, duration). This enables runtime configuration e.g. via external message.

The stateFunction argument is a PartialFunction[Event, State], which is conveniently given using the state function builder syntax as demonstrated below:

when(Idle,
  matchEvent(SetTarget.class, Uninitialized.class,
    (setTarget, uninitialized) ->
      stay().using(new Todo(setTarget.getRef(), new LinkedList<>()))));

It is recommended practice to declare the states as an enum and then verify that there is a when clause for each of the states. If you want to leave the handling of a state “unhandled” (more below), it still needs to be declared like this:

when(SomeState, AbstractFSM.NullFunction());

Defining the Initial State

Each FSM needs a starting point, which is declared using

startWith(state, data[, timeout])

The optionally given timeout argument overrides any specification given for the desired initial state. If you want to cancel a default timeout, use Duration.Inf.

Unhandled Events

If a state doesn't handle a received event a warning is logged. If you want to do something else in this case you can specify that with whenUnhandled(stateFunction):

whenUnhandled(
  matchEvent(X.class, (x, data) -> {
    log().info("Received unhandled event: " + x);
    return stay();
  }).
  anyEvent((event, data) -> {
    log().warning("Received unknown event: " + event);
    return goTo(Error);
  }));
}

Within this handler the state of the FSM may be queried using the stateName method.

IMPORTANT: This handler is not stacked, meaning that each invocation of whenUnhandled replaces the previously installed handler.

Initiating Transitions

The result of any stateFunction must be a definition of the next state unless terminating the FSM, which is described in Termination from Inside. The state definition can either be the current state, as described by the stay directive, or it is a different state as given by goto(state). The resulting object allows further qualification by way of the modifiers described in the following:

• forMax(duration)

  This modifier sets a state timeout on the next state. This means that a timer is started which upon expiry sends a StateTimeout message to the FSM. This timer is canceled upon reception of any other message in the meantime; you can rely on the fact that the StateTimeout message will not be processed after an intervening message.

  This modifier can also be used to override any default timeout which is specified for the target state. If you want to cancel the default timeout, use Duration.Inf.

• using(data)

  This modifier replaces the old state data with the new data given. If you follow the advice above, this is the only place where internal state data are ever modified.

• replying(msg)

  This modifier sends a reply to the currently processed message and otherwise does not modify the state transition.

All modifiers can be chained to achieve a nice and concise description:

when(SomeState, matchAnyEvent((msg, data) -> {
    return goTo(Processing).using(newData).
      forMax(Duration.create(5, SECONDS)).replying(WillDo);
}));

The parentheses are not actually needed in all cases, but they visually distinguish between modifiers and their arguments and therefore make the code even more pleasant to read for foreigners.

Monitoring Transitions

Transitions occur "between states" conceptually, which means after any actions you have put into the event handling block; this is obvious since the next state is only defined by the value returned by the event handling logic. You do not need to worry about the exact order with respect to setting the internal state variable, as everything within the FSM actor is running single-threaded anyway.

onTransition(
  matchState(Active, Idle, () -> setTimer("timeout",
    Tick, Duration.create(1, SECONDS), true)).
  state(Active, null, () -> cancelTimer("timeout")).
  state(null, Idle, (f, t) -> log().info("entering Idle from " + f)));

public void handler(StateType from, StateType to) {
  // handle transition here
}

onTransition(this::handler);

Timers

Besides state timeouts, FSM manages timers identified by String names. You may set a timer using

setTimer(name, msg, interval, repeat)

where msg is the message object which will be sent after the duration interval has elapsed. If repeat is true, then the timer is scheduled at fixed rate given by the interval parameter. Any existing timer with the same name will automatically be canceled before adding the new timer.

Timers may be canceled using

cancelTimer(name)

which is guaranteed to work immediately, meaning that the scheduled message will not be processed after this call even if the timer already fired and queued it. The status of any timer may be inquired with

isTimerActive(name)

These named timers complement state timeouts because they are not affected by intervening reception of other messages.

Termination from Inside

The FSM is stopped by specifying the result state as

stop([reason[, data]])

The reason must be one of Normal (which is the default), Shutdown or Failure(reason), and the second argument may be given to change the state data which is available during termination handling.

when(Error, matchEventEquals("stop", (event, data) -> {
  // do cleanup ...
  return stop();
}));

You can use onTermination(handler) to specify custom code that is executed when the FSM is stopped. The handler is a partial function which takes a StopEvent(reason, stateName, stateData) as argument:

onTermination(
  matchStop(Normal(),
    (state, data) -> {/* Do something here */}).
    stop(Shutdown(),
      (state, data) -> {/* Do something here */}).
    stop(Failure.class,
      (reason, state, data) -> {/* Do something here */}));

As for the whenUnhandled case, this handler is not stacked, so each invocation of onTermination replaces the previously installed handler.

Termination from Outside

When an ActorRef associated to a FSM is stopped using the stop method, its postStop hook will be executed. The default implementation by the AbstractFSM class is to execute the onTermination handler if that is prepared to handle a StopEvent(Shutdown, ...).

Event Tracing

The setting akka.actor.debug.fsm in Configuration enables logging of an event trace by LoggingFSM instances:

public class MyFSM extends AbstractLoggingFSM<StateType, Data> {
  // body elided ...
}

This FSM will log at DEBUG level:

• all processed events, including StateTimeout and scheduled timer messages
• every setting and cancellation of named timers
• all state transitions

Life cycle changes and special messages can be logged as described for Actors.

Rolling Event Log

The AbstractLoggingFSM class adds one more feature to the FSM: a rolling event log which may be used during debugging (for tracing how the FSM entered a certain failure state) or for other creative uses:

public class MyFSM extends AbstractLoggingFSM<StateType, Data> {
  @Override
  public int logDepth() { return 12; }
  {
    onTermination(
      matchStop(Failure.class, (reason, state, data) -> {
        String lastEvents = getLog().mkString("\n\t");
        log().warning("Failure in state " + state + " with data " + data + "\n" +
          "Events leading up to this point:\n\t" + lastEvents);
      })
    );
    //...
  }
}

The logDepth defaults to zero, which turns off the event log.

The contents of the event log are available using method getLog, which returns an IndexedSeq[LogEntry] where the oldest entry is at index zero.