This behavior module provides a state machine. Two
One for finite-state machines
(
One without restriction on the state data type that uses one callback function for all states
This is a new behavior in Erlang/OTP 19.0. It has been thoroughly reviewed, is stable enough to be used by at least two heavy OTP applications, and is here to stay. Depending on user feedback, we do not expect but can find it necessary to make minor not backward compatible changes into Erlang/OTP 20.0.
The
The callback model(s) for
A generic state machine process (
A
gen_statem module Callback module ----------------- --------------- gen_statem:start gen_statem:start_link -----> Module:init/1 Server start or code change -----> Module:callback_mode/0 gen_statem:stop -----> Module:terminate/3 gen_statem:call gen_statem:cast erlang:send erlang:'!' -----> Module:StateName/3 Module:handle_event/4 - -----> Module:terminate/3 - -----> Module:code_change/4
Events are of different
If a callback function fails or returns a bad value,
the
The "state callback" for a specific
When the
When the
The
The
The
Inserting an event replaces the trick of calling your own
state handling functions that you often would have to
resort to in, for example,
The
If you in
For the details of a state transition, see type
A
Notice that a
Unless otherwise stated, all functions in this module fail if
the specified
The
The following example shows a simple pushbutton model
for a toggling pushbutton implemented with
The following is the complete callback module file
-module(pushbutton).
-behaviour(gen_statem).
-export([start/0,push/0,get_count/0,stop/0]).
-export([terminate/3,code_change/4,init/1,callback_mode/0]).
-export([on/3,off/3]).
name() -> pushbutton_statem. % The registered server name
%% API. This example uses a registered name name()
%% and does not link to the caller.
start() ->
gen_statem:start({local,name()}, ?MODULE, [], []).
push() ->
gen_statem:call(name(), push).
get_count() ->
gen_statem:call(name(), get_count).
stop() ->
gen_statem:stop(name()).
%% Mandatory callback functions
terminate(_Reason, _State, _Data) ->
void.
code_change(_Vsn, State, Data, _Extra) ->
{ok,State,Data}.
init([]) ->
%% Set the initial state + data. Data is used only as a counter.
State = off, Data = 0,
{ok,State,Data}.
callback_mode() -> state_functions.
%%% state callback(s)
off({call,From}, push, Data) ->
%% Go to 'on', increment count and reply
%% that the resulting status is 'on'
{next_state,on,Data+1,[{reply,From,on}]};
off(EventType, EventContent, Data) ->
handle_event(EventType, EventContent, Data).
on({call,From}, push, Data) ->
%% Go to 'off' and reply that the resulting status is 'off'
{next_state,off,Data,[{reply,From,off}]};
on(EventType, EventContent, Data) ->
handle_event(EventType, EventContent, Data).
%% Handle events common to all states
handle_event({call,From}, get_count, Data) ->
%% Reply with the current count
{keep_state,Data,[{reply,From,Data}]};
handle_event(_, _, Data) ->
%% Ignore all other events
{keep_state,Data}.
The following is a shell session when running it:
1> pushbutton:start(). {ok,<0.36.0>} 2> pushbutton:get_count(). 0 3> pushbutton:push(). on 4> pushbutton:get_count(). 1 5> pushbutton:push(). off 6> pushbutton:get_count(). 1 7> pushbutton:stop(). ok 8> pushbutton:push(). ** exception exit: {noproc,{gen_statem,call,[pushbutton_statem,push,infinity]}} in function gen:do_for_proc/2 (gen.erl, line 261) in call from gen_statem:call/3 (gen_statem.erl, line 386)
To compare styles, here follows the same example using
callback_mode() -> handle_event_function.
%%% state callback(s)
handle_event({call,From}, push, off, Data) ->
%% Go to 'on', increment count and reply
%% that the resulting status is 'on'
{next_state,on,Data+1,[{reply,From,on}]};
handle_event({call,From}, push, on, Data) ->
%% Go to 'off' and reply that the resulting status is 'off'
{next_state,off,Data,[{reply,From,off}]};
%%
%% Event handling common to all states
handle_event({call,From}, get_count, State, Data) ->
%% Reply with the current count
{next_state,State,Data,[{reply,From,Data}]};
handle_event(_, _, State, Data) ->
%% Ignore all other events
{next_state,State,Data}.
Name specification to use when starting
a
Server specification to use when addressing
a
It can be:
The
The
The
The
Debug option that can be used when starting
a
For every entry in
Options that can be used when starting
a
Return value from the start functions, for example,
Destination to use when replying through, for example, the
If the
If the
A term in which the state machine implementation
is to store any server data it needs. The difference between
this and the
External events are of three types:
This is the return type from
The callback mode is selected when starting the
The state must be of type
The state can be any term and the callback function
Whether the state machine should use state enter calls
or not is selected when starting the
If
If
If
Note that a state enter call will be done
right before entering the initial state even though this
formally is not a state change.
In this case
Transition options can be set by
If the state changes, is the initial state,
All
If
If the state changes, the queue of incoming events is reset to start with the oldest postponed.
All events stored with
Timeout timers
Any event cancels an
A state change cancels a
If there are enqueued events the
Otherwise the
If
If
Generates an event of
If the value is
If the value is
Note that it is not possible or needed to cancel this time-out, as it is cancelled automatically by any other event.
Generates an event of
If the value is
If the value is
Setting this timer while it is running will restart it with
the new time-out value. Therefore it is possible to cancel
this time-out by setting it to
These state transition actions can be invoked by
returning them from the
Actions are executed in the containing list order.
Actions that set
Sets the
Stores the specified
The stored events are inserted in the queue as the next to process
before any already queued events. The order of these stored events
is preserved, so the first
An event of type
These state transition actions can be invoked by
returning them from the
Actions are executed in the containing list order.
Actions that set
Sets the
Short for
Sets the
Sets the
This state transition action can be invoked by
returning it from the
It replies to a caller waiting for a reply in
Note that using this action from
For a succesful initialization,
The
For an unsuccesful initialization,
The
The
The
The
The
The
Terminates the
Sends all
All these terms are tuples or atoms and this property
will hold in any future version of
Makes a synchronous call to the
A
For
If you combine catching exceptions from this function
with
The call can also fail, for example, if the
Sends an asynchronous event to the
The same as
If
Otherwise the same as
Makes the calling process become a
This function is useful when a more complex initialization
procedure is needed than
the
If
The function fails if the calling process was not started by a
This function can be used by a
A reply sent with this function is not visible
in
Creates a standalone
For a description of arguments and return values, see
Creates a
The
If option
If option
If option
Using spawn option
If the
If
The same as
Orders the
This function returns
If the process does not exist, a
The following functions are to be exported from a
This function is called by a
Server start happens either when
The
If this function's body does not return an inline constant value the callback module is doing something strange.
This function is called by a
For an upgrade,
If successful, the function must return the updated
internal state in an
If the function returns a failure
Also note when upgrading a
Whenever a
Note that if the
init(Args) -> erlang:error(not_implemented, [Args]).
This callback is optional, so a callback module does not need
to export it. The
If this callback is exported but fails,
to hide possibly sensitive data,
the default function will instead return
This function is called by a
This function is useful for changing the form and
appearance of the
The function is to return
One use for this function is to return compact alternative state representations to avoid having large state terms printed in log files. Another use is to hide sensitive data from being written to the error log.
Whenever a
If
If this function returns with a next state that
does not match equal (
The only difference between
For options that can be set and actions that can be done
by
When the
Note the fact that you can use
This callback is optional, so callback modules need not
export it. The
This function is called by a
If the
The
The shutdown strategy as defined in the supervisor's
child specification is an integer time-out value, not
Even if the
Otherwise, the
Notice that for any other reason than