A behaviour module for implementing a state machine.

The advantage of using this module is that it will have a standard set of interface functions and include functionality for tracing and error reporting. It will also fit into a supervision tree.

Example

The GenStateMachine behaviour abstracts the state machine. Developers are only required to implement the callbacks and functionality they are interested in.

Let's start with a code example and then explore the available callbacks. Imagine we want a GenStateMachine that works like a switch, allowing us to turn it on and off, as well as see how many times the switch has been turned on:

defmodule Switch do
  use GenStateMachine

  # Callbacks

  def handle_event(:cast, :flip, :off, data) do
    {:next_state, :on, data + 1}
  end

  def handle_event(:cast, :flip, :on, data) do
    {:next_state, :off, data}
  end

  def handle_event({:call, from}, :get_count, state, data) do
    {:next_state, state, data, [{:reply, from, data}]}
  end
end

# Start the server
{:ok, pid} = GenStateMachine.start_link(Switch, {:off, 0})

# This is the client
GenStateMachine.cast(pid, :flip)
#=> :ok

GenStateMachine.call(pid, :get_count)
#=> 1

We start our Switch by calling start_link/3, passing the module with the server implementation and its initial argument, a tuple where the first element is the initial state and the second is the initial data. We can primarily interact with the state machine by sending two types of messages. call messages expect a reply from the server (and are therefore synchronous) while cast messages do not.

Every time you do a call/3 or a cast/2, the message will be handled by handle_event/4.

We can also use the :state_functions callback mode instead of the default, which is :handle_event_function:

defmodule Switch do
  use GenStateMachine, callback_mode: :state_functions

  def off(:cast, :flip, data) do
    {:next_state, :on, data + 1}
  end
  def off({:call, from}, :get_count, data) do
    {:keep_state_and_data, [{:reply, from, data}]}
  end

  def on(:cast, :flip, data) do
    {:next_state, :off, data}
  end
  def on({:call, from}, :get_count, data) do
    {:keep_state_and_data, [{:reply, from, data}]}
  end
end

# Start the server
{:ok, pid} = GenStateMachine.start_link(Switch, {:off, 0})

# This is the client
GenStateMachine.cast(pid, :flip)
#=> :ok

GenStateMachine.call(pid, :get_count)
#=> 1

Again, we start our Switch by calling start_link/3, passing the module with the server implementation and its initial argument, and interacting with it via call and cast.

However, in :state_functions callback mode, every time you do a call/3 or a cast/2, the message will be handled by the state_name/3 function which is named the same as the current state.

Callbacks

In the default :handle_event_function callback mode, there are 4 callbacks required to be implemented. By adding use GenStateMachine to your module, Elixir will automatically define all 4 callbacks for you, leaving it up to you to implement the ones you want to customize.

In the :state_functions callback mode, there are 3 callbacks required to be implemented. By adding use GenStateMachine, callback_mode: :state_functions to your module, Elixir will automatically define all 3 callbacks for you, leaving it up to you to implement the ones you want to customize, as well as state_name/3 functions named the same as the states you wish to support.

It is important to note that the default implementation of the code_change/4 callback results in an :undefined error. This is because code_change/4 is related to the quite difficult topic of hot upgrades, and if you need it, you should really be implementing it yourself. In normal use this callback will not be invoked.

State Enter Callbacks

If you wish, you can register to receive callbacks when you enter a state by adding :state_enter to your callback_mode:

defmodule Switch do
  use GenStateMachine, callback_mode: [:handle_event_function, :state_enter]

  def handle_event(:enter, _event, state, data) do
    {:next_state, state, %{data | enters: data.enters + 1}}
  end

  def handle_event(:cast, :flip, :off, data) do
    {:next_state, :on, %{data | flips: data.flips + 1}}
  end

  def handle_event(:cast, :flip, :on, data) do
    {:next_state, :off, data}
  end

  def handle_event({:call, from}, :get_count, _state, data) do
    {:keep_state_and_data, [{:reply, from, data}]}
  end
end

# Start the server
{:ok, pid} = GenStateMachine.start_link(Switch, {:off, %{enters: 0, flips: 0}})

# This is the client
GenStateMachine.cast(pid, :flip)
GenStateMachine.cast(pid, :flip)
#=> :ok

GenStateMachine.call(pid, :get_count)
#=> %{enters: 3, flips: 1}

See the Erlang documentation for more details.

Name Registration

Both start_link/3 and start/3 support registering the GenStateMachine under a given name on start via the :name option. Registered names are also automatically cleaned up on termination. The supported values are:

• an atom - the GenStateMachine is registered locally with the given name using Process.register/2.

• {:global, term}- the GenStateMachine is registered globally with the given term using the functions in the :global module.

• {:via, module, term} - the GenStateMachine is registered with the given mechanism and name. The :via option expects a module that exports register_name/2, unregister_name/1, whereis_name/1 and send/2. One such example is the :global module which uses these functions for keeping the list of names of processes and their associated pid's that are available globally for a network of Erlang nodes.

For example, we could start and register our Switch server locally as follows:

# Start the server and register it locally with name MySwitch
{:ok, _} = GenStateMachine.start_link(Switch, {:off, 0}, name: MySwitch)

# Now messages can be sent directly to MySwitch
GenStateMachine.call(MySwitch, :get_count) #=> 0

Once the server is started, the remaining functions in this module (call/3, cast/2, and friends) will also accept an atom, or any :global or :via tuples. In general, the following formats are supported:

• a pid
• an atom if the server is locally registered
• {atom, node} if the server is locally registered at another node
• {:global, term} if the server is globally registered
• {:via, module, name} if the server is registered through an alternative registry

Client / Server APIs

Although in the example above we have used GenStateMachine.start_link/3 and friends to directly start and communicate with the server, most of the time we don't call the GenStateMachine functions directly. Instead, we wrap the calls in new functions representing the public API of the server.

Here is a better implementation of our Switch module:

defmodule Switch do
  use GenStateMachine

  # Client

  def start_link() do
    GenStateMachine.start_link(Switch, {:off, 0})
  end

  def flip(pid) do
    GenStateMachine.cast(pid, :flip)
  end

  def get_count(pid) do
    GenStateMachine.call(pid, :get_count)
  end

  # Server (callbacks)

  def handle_event(:cast, :flip, :off, data) do
    {:next_state, :on, data + 1}
  end

  def handle_event(:cast, :flip, :on, data) do
    {:next_state, :off, data}
  end

  def handle_event({:call, from}, :get_count, state, data) do
    {:next_state, state, data, [{:reply, from, data}]}
  end

  def handle_event(event_type, event_content, state, data) do
    # Call the default implementation from GenStateMachine
    super(event_type, event_content, state, data)
  end
end

In practice, it is common to have both server and client functions in the same module. If the server and/or client implementations are growing complex, you may want to have them in different modules.

Receiving custom messages

The goal of a GenStateMachine is to abstract the "receive" loop for developers, automatically handling system messages, support code change, synchronous calls and more. Therefore, you should never call your own "receive" inside the GenStateMachine callbacks as doing so will cause the GenStateMachine to misbehave. If you want to receive custom messages, they will be delivered to the usual handler for your callback mode with event_type :info.

Learn more

If you wish to find out more about gen_statem, the documentation and links in Erlang can provide extra insight.

• :gen_statem module documentation
• gen_statem Behaviour – OTP Design Principles