path: root/lib/stdlib/doc/src/gen_statem.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2016</year><year>2023</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    </legalnotice>

    <title>gen_statem</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module since="OTP 19.0">gen_statem</module>
  <modulesummary>Generic state machine behavior.</modulesummary>
  <description>
    <p>
      <c>gen_statem</c> provides a generic state machine behaviour
      that for new code replaces its predecessor
      <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl>
      since Erlang/OTP 20.0. The <c>gen_fsm</c> behaviour remains
      in OTP "as is".
    </p>
    <note>
      <p>
	If you are new to <c>gen_statem</c> and want an overview
	of concepts and operation the section
	<seeguide marker="system/design_principles:statem">
	  <c>gen_statem</c>&nbsp;Behaviour
	</seeguide>
	located in the User's Guide
	<seeguide marker="system/design_principles:index">
	  OTP Design Principles
	</seeguide>
	is recommended to read before this reference manual,
	possibly after the Description section you are reading here.
      </p>
    </note>
    <p>
      This reference manual contains type descriptions generated from
      types in the <c>gen_statem</c> source code, so they are correct.
      However, the generated descriptions also reflect the type hierarchy,
      which sometimes makes it hard to get a good overview.
      If so, see the section
      <seeguide marker="system/design_principles:statem">
	<c>gen_statem</c>&nbsp;Behaviour
      </seeguide>
      in the
      <seeguide marker="system/design_principles:index">
	OTP Design Principles
      </seeguide>
      User's Guide.
    </p>
    <note>
      <list type="bulleted">
	<item>This behavior appeared in Erlang/OTP 19.0.</item>
	<item>
	  In OTP 19.1 a backwards incompatible change of
	  the return tuple from
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  was made and the mandatory callback function
	  <seemfa marker="#Module:callback_mode/0">
	    <c>Module:callback_mode/0</c>
	  </seemfa>
	  was introduced.
	</item>
	<item>
	   In OTP 20.0
           <seetype marker="#generic_timeout">
	     generic time-outs
	   </seetype>
	   were added.
	</item>
	<item>
	  In OTP 22.1 time-out content
          <seetype marker="#timeout_update_action">
	    <c>update</c>
	  </seetype>
	  and explicit time-out
          <seetype marker="#timeout_cancel_action">
	    <c>cancel</c>
	  </seetype>
	  were added.
	</item>
	<item>
	  In OTP 22.3 the possibility to change the callback module
	  with actions
	  <seetype marker="#action"><c>change_callback_module</c></seetype>,
	  <seetype marker="#action"><c>push_callback_module</c></seetype> and
	  <seetype marker="#action"><c>pop_callback_module</c></seetype>,
	  was added.
	</item>
      </list>
    </note>
    <p>
      <c>gen_statem</c> has got the same features that
      <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl>
      had and adds some really useful:
    </p>
    <list type="bulleted">
      <item>Co-located state code</item>
      <item>Arbitrary term state</item>
      <item>Event postponing</item>
      <item>Self-generated events</item>
      <item>State time-out</item>
      <item>Multiple generic named time-outs</item>
      <item>Absolute time-out time</item>
      <item>Automatic state enter calls</item>
      <item>
	Reply from other state than the request, <c>sys</c> traceable
      </item>
      <item>Multiple <c>sys</c> traceable replies</item>
      <item>Changing the callback module</item>
    </list>


    <p>
      Two
      <seetype marker="#callback_mode"><em>callback modes</em></seetype>
      are supported:
    </p>
    <list type="bulleted">
      <item>
        <p>
	  One for finite-state machines
          (<seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl> like),
          which requires the state to be an atom and uses that state as
          the name of the current callback function.
        </p>
      </item>
      <item>
        <p>
	  One that allows the state to be any term and
          that uses one callback function for all states.
        </p>
      </item>
    </list>
    <p>
      The callback model(s) for <c>gen_statem</c> differs from
      the one for <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl>,
      but it is still fairly easy to
      <seeerl marker="gen_fsm#Migration to gen_statem">
	rewrite from
      </seeerl> <c>gen_fsm</c> to <c>gen_statem</c>.
    </p>
    <p>
      A generic state machine server process (<c>gen_statem</c>) implemented
      using this module has a standard set of interface functions
      and includes functionality for tracing and error reporting.
      It also fits into an OTP supervision tree. For more information, see
      <seeguide marker="system/design_principles:statem">OTP Design Principles</seeguide>.
    </p>
    <p>
      A <c>gen_statem</c> assumes all specific parts to be located in a
      callback module exporting a predefined set of functions.
      The relationship between the behavior functions and the callback
      functions is as follows:</p>
    <pre>
gen_statem module            Callback module
-----------------            ---------------
gen_statem:start
gen_statem:start_monitor
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
gen_statem:send_request
erlang:send
erlang:'!'            -----> Module:StateName/3
                             Module:handle_event/4

-                     -----> Module:terminate/3

-                     -----> Module:code_change/4</pre>
    <p>
      Events are of different
      <seetype marker="#event_type">types</seetype>,
      so the callback functions can know the origin of an event
      and how to respond.
    </p>
    <p>
      If a callback function fails or returns a bad value,
      the <c>gen_statem</c> terminates, unless otherwise stated.
      However, an exception of class
      <seemfa marker="erts:erlang#throw/1"><c>throw</c></seemfa>
      is not regarded as an error but as a valid return
      from all callback functions.
    </p>
    <marker id="state callback"/>
    <p>
      The <em>state callback</em> for a specific
      <seetype marker="#state">state</seetype>
      in a <c>gen_statem</c> is the callback function that is called
      for all events in this state. It is selected depending on which
      <seetype marker="#callback_mode"><em>callback mode</em></seetype>
      that the callback module defines with the callback function
      <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>.
    </p>
    <p>
      When the
      <seetype marker="#callback_mode"><em>callback mode</em></seetype>
      is <c>state_functions</c>, the state must be an atom and
      is used as the <em>state callback</em> name; see
      <seemfa marker="#Module:StateName/3"><c>Module:StateName/3</c></seemfa>.
      This co-locates all code for a specific state
      in one function as the <c>gen_statem</c> engine
      branches depending on state name.
      Note the fact that the callback function
      <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa>
      makes the state name <c>terminate</c> unusable in this mode.
    </p>
    <p>
      When the
      <seetype marker="#callback_mode"><em>callback mode</em></seetype>
      is <c>handle_event_function</c>, the state can be any term
      and the <em>state callback</em> name is
      <seemfa marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa>.
      This makes it easy to branch depending on state or event as you desire.
      Be careful about which events you handle in which
      states so that you do not accidentally postpone an event
      forever creating an infinite busy loop.
    </p>
    <p>
      When <c>gen_statem</c> receives a process message it is
      converted into an event and the
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      is called with the event as two arguments: type and content.
      When the
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      has processed the event it returns to <c>gen_statem</c>
      which does a <em>state transition</em>.
      If this <em>state transition</em> is to a different state,
      that is: <c>NextState =/= State</c>, it is a <em>state change</em>.
    </p>
    <p>
      The
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      may return
      <seetype marker="#action"><em>transition actions</em></seetype>
      for <c>gen_statem</c>
      to execute during the <em>state transition</em>,
      for example to reply to a
      <seemfa marker="#call/2"><c>gen_statem:call/2,3</c></seemfa>.
    </p>
    <p>
      One of the possible <em>transition actions</em>
      is to postpone the current event.
      Then it is not retried in the current state.
      The <c>gen_statem</c> engine keeps a queue of events
      divided into the postponed events
      and the events still to process.
      After a <em>state change</em> the queue restarts
      with the postponed events.
    </p>
    <p>
      The <c>gen_statem</c> event queue model is sufficient
      to emulate the normal process message queue with selective receive.
      Postponing an event corresponds to not matching it
      in a receive statement, and changing states corresponds
      to entering a new receive statement.
    </p>
    <p>
      The
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      can insert events using the
      <seetype marker="#action"><em>transition actions</em></seetype>
      <c>next_event</c>
      and such an event is inserted in the event queue
      as the next to call the
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      with.
      That is, as if it is the oldest incoming event.
      A dedicated
      <seetype marker="#event_type"><c>event_type()</c></seetype>
      <c>internal</c> can be used for such events making them impossible
      to mistake for external events.
    </p>
    <p>
      Inserting an event replaces the trick of calling your own
      state handling functions that you often would have to
      resort to in, for example,
      <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl>
      to force processing an inserted event before others.
    </p>
    <p>
      The <c>gen_statem</c> engine can automatically
      make a specialized call to the
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      whenever a new state is entered; see 
      <seetype marker="#state_enter"><c>state_enter()</c></seetype>.
      This is for writing code common to all state entries.
      Another way to do it is to explicitly insert an event
      at the <em>state transition</em>,
      and/or to use a dedicated <em>state transition</em> function,
      but that is something you will have to remember
      at every <em>state transition</em> to the state(s) that need it.
    </p>
    <note>
      <p>If you in <c>gen_statem</c>, for example, postpone
        an event in one state and then call another <em>state callback</em>
        of yours, you have not done a <em>state change</em>
	and hence the postponed event is not retried,
	which is logical but can be confusing.
      </p>
    </note>
    <p>
      For the details of a <em>state transition</em>, see type
      <seetype marker="#transition_option"><c>transition_option()</c></seetype>.
    </p>
    <p>
      A <c>gen_statem</c> handles system messages as described in
      <seeerl marker="sys"><c>sys</c></seeerl>.
      The <c>sys</c> module can be used for debugging a <c>gen_statem</c>.
    </p>
    <p>
      Notice that a <c>gen_statem</c> does not trap exit signals
      automatically, this must be explicitly initiated in
      the callback module (by calling
      <seemfa marker="erts:erlang#process_flag/2"><c>process_flag(trap_exit, true)</c></seemfa>.
    </p>
    <p>
      Unless otherwise stated, all functions in this module fail if
      the specified <c>gen_statem</c> does not exist or
      if bad arguments are specified.
    </p>
    <p>
      The <c>gen_statem</c> process can go into hibernation; see
      <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>.
      It is done when a
      <seeerl marker="#state callback"><em>state callback</em></seeerl>
      or
      <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
      specifies <c>hibernate</c> in the returned
      <seetype marker="#action"><c>Actions</c></seetype>
      list. This feature can be useful to reclaim process heap memory
      while the server is expected to be idle for a long time.
      However, use this feature with care,
      as hibernation can be too costly
      to use after every event; see
      <seemfa marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seemfa>.
    </p>
    <p>
      There is also a server start option
      <seetype marker="#enter_loop_opt">
	<c>{hibernate_after, Timeout}</c>
      </seetype>
      for
      <seemfa marker="#start/3"><c>start/3,4</c></seemfa>,
      <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>,
      <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa> or
      <seemfa marker="#enter_loop/4"><c>enter_loop/4,5,6</c></seemfa>,
      that may be used to automatically hibernate the server.
    </p>
    <p>
      If the <c>gen_statem</c> process terminates, e.g. as a result of a
      function in the callback module returning <c>{stop,Reason}</c>, an exit
      signal with this <c>Reason</c> is sent to linked processes and ports. See
      <seeguide marker="system/reference_manual:processes#errors">
      Processes</seeguide> in the Reference Manual for details regarding error
      handling using exit signals.
    </p>
    <note><p>
      For some important information about distributed signals, see the
      <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
        <i>Blocking Signaling Over Distribution</i></seeguide> section in the
      <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
      Blocking signaling can, for example, cause call timeouts in
      <c>gen_statem</c> to be significantly delayed.
    </p></note>
  </description>

  <section>
    <title>Example</title>
    <p>
      The following example shows a simple pushbutton model
      for a toggling pushbutton implemented with
      <seetype marker="#callback_mode"><em>callback mode</em></seetype>
      <c>state_functions</c>.
      You can push the button and it replies if it went on or off,
      and you can ask for a count of how many times it has been
      pushed to switch on.
    </p>
    <p>The following is the complete callback module file
      <c>pushbutton.erl</c>:</p>
    <code type="erl">
-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}.
    </code>
    <p>The following is a shell session when running it:</p>
    <pre>
1> pushbutton:start().
{ok,&lt;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)
    </pre>
    <p>
      To compare styles, here follows the same example using
      <seetype marker="#callback_mode"><em>callback mode</em></seetype>
      <c>handle_event_function</c>, or rather the code to replace
      after function <c>init/1</c> of the <c>pushbutton.erl</c>
      example file above:
    </p>
    <code type="erl">
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}.
    </code>
  </section>

  <datatypes>
    <datatype>
      <name name="server_name"/>
      <desc>
	<p>
	  Name specification to use when starting
	  a <c>gen_statem</c> server. See
	  <seemfa marker="#start_link/3"><c>start_link/3</c></seemfa>
	  and
	  <seetype marker="#server_ref"><c>server_ref()</c></seetype>
	  below.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="server_ref"/>
      <desc>
	<p>
	  Server specification to use when addressing
	  a <c>gen_statem</c> server.
	  See <seemfa marker="#call/2"><c>call/2</c></seemfa> and
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  above.
	</p>
	<p>It can be:</p>
	<taglist>
	  <tag><c>pid() | LocalName</c></tag>
	  <item>
            <p>
              The <c>gen_statem</c> is locally registered.
            </p>
          </item>
	  <tag><c>{Name,Node}</c></tag>
	  <item>
            <p>
	      The <c>gen_statem</c> is locally registered
	      on another node.
            </p>
	  </item>
	  <tag><c>{global,GlobalName}</c></tag>
	  <item>
            <p>
	      The <c>gen_statem</c> is globally registered in
	      <seeerl marker="kernel:global"><c>global</c></seeerl>.
            </p>
	  </item>
	  <tag><c>{via,RegMod,ViaName}</c></tag>
	  <item>
            <p>
	      The <c>gen_statem</c> is registered in
	      an alternative process registry.
	      The registry callback module <c>RegMod</c>
	      is to export functions
	      <c>register_name/2</c>, <c>unregister_name/1</c>,
	      <c>whereis_name/1</c>, and <c>send/2</c>,
	      which are to behave like the corresponding functions in
	      <seeerl marker="kernel:global"><c>global</c></seeerl>.
	      Thus, <c>{via,global,GlobalName}</c> is the same as
	      <c>{global,GlobalName}</c>.
            </p>
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="start_opt"/>
      <desc>
	<p>
	  Options that can be used when starting
	  a <c>gen_statem</c> server through, for example,
	  <seemfa marker="#start_link/3"><c>start_link/3</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="start_ret"/>
      <desc>
	<p>
	  Return value from the <c>start()</c> and <c>start_link()</c> functions,
	  for example, <seemfa marker="#start_link/3"><c>start_link/3</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="start_mon_ret"/>
      <desc>
	<p>
	  Return value from the
	  <seemfa marker="#start_monitor/3"><c>start_monitor()</c></seemfa>
	  functions.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="enter_loop_opt"/>
      <desc>
	<p>
	  Options that can be used when starting
	  a <c>gen_statem</c> server through,
	  <seemfa marker="#enter_loop/4"><c>enter_loop/4-6</c></seemfa>.
	</p>
	<taglist>
	  <tag><c>hibernate_after</c></tag>
	  <item>
	    <p>
	      <c>HibernateAfterTimeout</c>
	      specifies that the <c>gen_statem</c> process awaits
	      any message for <c>HibernateAfterTimeout</c> milliseconds and
              if no message is received, the process goes into hibernation
	      automatically (by calling
	      <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>).
	    </p>
	  </item>
	  <tag><c>debug</c></tag>
	  <item>
	    <p>
	      For every entry in <c><anno>Dbgs</anno></c>,
	      the corresponding function in
	      <seeerl marker="sys"><c>sys</c></seeerl> is called.
	    </p>
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="from"/>
      <desc>
	<p>
	  Destination to use when replying through, for example, the
	  <seetype marker="#action"><c>action()</c></seetype>
	  <c>{reply,From,Reply}</c>
	  to a process that has called the <c>gen_statem</c> server using
	  <seemfa marker="#call/2"><c>call/2</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="reply_tag"/>
      <desc>
        <p>
          A handle that associates a reply to the corresponding request.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="state"/>
      <desc>
	<p>
	  If the
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  is <c>handle_event_function</c>,
	  the state can be any term.
	  After a <em>state change</em> (<c>NextState =/= State</c>),
	  all postponed events are retried.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="state_name"/>
      <desc>
	<p>
	  If the
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  is <c>state_functions</c>,
	  the state must be an atom.
	  After a <em>state change</em> (<c>NextState =/= State</c>),
	  all postponed events are retried.
	  Note that the state <c>terminate</c> is not possible
	  to use since it would collide with the optional callback function
	  <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="data"/>
      <desc>
	<p>
	  A term in which the state machine implementation
	  is to store any server data it needs. The difference between
	  this and the <seetype marker="#state"><c>state()</c></seetype>
	  itself is that a change in this data does not cause
	  postponed events to be retried. Hence, if a change
	  in this data would change the set of events that
	  are handled, then that data item is to be made
	  a part of the state.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="event_type"/>
      <desc>
	<p>
	  There are 3 categories of events:
	  <seetype marker="#external_event_type">external</seetype>,
	  <seetype marker="#timeout_event_type">timeout</seetype>,
	  and <c>internal</c>.
	</p>
	<p>
	  <c>internal</c> events can only be generated by the
	  state machine itself through the <em>transition action</em>
	  <seetype marker="#action"><c>next_event</c></seetype>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="external_event_type"/>
      <desc>
	<p>
	  External events are of 3 types:
	  <c>{call,<anno>From</anno>}</c>, <c>cast</c>, or <c>info</c>.
	  Type <c>call</c> originates from the API functions
	  <seemfa marker="#call/2"><c>call/2</c></seemfa>
	  and <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>.
	  For calls, the event contains whom to reply to.
	  Type <c>cast</c> originates from the API function
	  <seemfa marker="#cast/2"><c>cast/2</c></seemfa>.
	  Type <c>info</c> originates from regular process messages sent
	  to the <c>gen_statem</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="timeout_event_type"/>
      <desc>
	<p>
	  There are 3 types of time-out events that the state machine
	  can generate for itself with the corresponding
	  <seetype marker="#timeout_action">timeout_action()</seetype>s.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="event_content"/>
      <desc>
	<p>
          Any event's content can be any term.
        </p>
        <p>
          See <seetype marker="#event_type"><c>event_type</c></seetype>
          that describes the origins of the different event types,
          which is also where the event content comes from.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="callback_mode_result"/>
      <desc>
	<p>
	  This is the return type from
	  <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>
	  and selects 
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  and whether to do
	  <seetype marker="#state_enter"><em>state enter calls</em></seetype>,
	  or not.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="callback_mode"/>
      <desc>
	<p>
	  The <em>callback mode</em> is selected
	  with the return value from
	  <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>:
	</p>
	<taglist>
	  <tag><c>state_functions</c></tag>
	  <item>
	    <p>
	      The state must be of type
	      <seetype marker="#state_name"><c>state_name()</c></seetype>
	      and one callback function per state, that is,
	      <seemfa marker="#Module:StateName/3"><c>Module:StateName/3</c></seemfa>,
	      is used.
	    </p>
	  </item>
	  <tag><c>handle_event_function</c></tag>
	  <item>
	    <p>
	      The state can be any term and the callback function
	      <seemfa marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa>
	      is used for all states.
	    </p>
	  </item>
	</taglist>
	<p>
	  The function
	  <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>
	  is called when starting the <c>gen_statem</c>,
	  after code change
	  and after changing the callback module with any of the actions
	  <seetype marker="#action"><c>change_callback_module</c></seetype>,
	  <seetype marker="#action"><c>push_callback_module</c></seetype> or
	  <seetype marker="#action"><c>pop_callback_module</c></seetype>.
	  The result is cached for subsequent calls to
	  <seeerl marker="#state callback">state callbacks</seeerl>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="state_enter"/>
      <desc>
	<p>
	  Whether the state machine should use <em>state enter calls</em>
	  or not is selected when starting the  <c>gen_statem</c>
	  and after code change using the return value from
	  <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>.
	</p>
	<p>
	  If 
	  <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>
	  returns a list containing <c>state_enter</c>,
	  the <c>gen_statem</c> engine will, at every <em>state change</em>,
	  call the
	  <seeerl marker="#state callback">state callback</seeerl>
	  with arguments <c>(enter, OldState, Data)</c> or
	  <c>(enter, OldState, State, Data)</c>, depending on the
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>.
	  This may look like an event but is really a call
	  performed after the previous
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returned and before any event is delivered to the new
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>.
	  See
	  <seemfa marker="#Module:StateName/3"><c>Module:StateName/3</c></seemfa>
	  and
	  <seemfa marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa>.
	  Such a call can be repeated by returning a
	  <seetype marker="#state_callback_result">
	    <c>repeat_state</c>
	  </seetype>
	  or
	  <seetype marker="#state_callback_result">
	    <c>repeat_state_and_data</c>
	  </seetype>
	  tuple from the <em>state callback</em>.
	</p>
	<p>
	  If 
	  <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>
	  does not return such a list, no <em>state enter calls</em> are done.
	</p>
	<p>
	  If 
	  <seemfa marker="#Module:code_change/4"><c>Module:code_change/4</c></seemfa>
	  should transform the state,
	  it is regarded as a state rename and not a <em>state change</em>,
	  which will not cause a <em>state enter call</em>.
	</p>
	<p>
	  Note that a <em>state enter call</em> <em>will</em> be done
	  right before entering the initial state even though this
	  actually is not a <em>state change</em>.
	  In this case <c>OldState =:= State</c>,
	  which cannot happen for a subsequent state change,
	  but will happen when repeating the <em>state enter call</em>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="transition_option"/>
      <desc>
	<p>
	  Transition options can be set by
	  <seetype marker="#action">actions</seetype>
	  and modify the <em>state transition</em>.
	  The <em>state transition</em> takes place when the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  has processed an event and returns.
	  Here are the sequence of steps for a <em>state transition</em>:
	</p>
	<list type="ordered">
	  <item>
	    <p>
	      All returned
              <seetype marker="#action">actions</seetype>
	      are processed in order of appearance.
	      In this step all replies generated by any
	      <seetype marker="#reply_action"><c>reply_action()</c></seetype>
	      are sent.  Other actions set <c>transition_option()</c>s
	      that come into play in subsequent steps.
            </p>
	  </item>
	  <item>
            <p>
	      If
	      <seetype marker="#state_enter">
		<em>state enter calls</em>
	      </seetype>
	      are used, and either
	      it is the initial state or one of the callback results
	      <seetype marker="#state_callback_result">
		<c>repeat_state_and_data</c>
	      </seetype>
	      or
	      <seetype marker="#state_callback_result">
		<c>repeat_state_and_data</c>
	      </seetype>
	      is used the <c>gen_statem</c> engine calls
	      the current state callback with arguments
	      <seetype marker="#state_enter"><c>(enter, State, Data)</c></seetype>
	      or
	      <seetype marker="#state_enter"><c>(enter, State, State, Data)</c></seetype>
	      (depending on <seetype marker="#callback_mode"><em>callback mode</em></seetype>)
	      and when it returns starts again from the top of this sequence.
	    </p>
            <p>
	      If
	      <seetype marker="#state_enter">
		<em>state enter calls</em>
	      </seetype>
	      are used, and the state changes
	      the <c>gen_statem</c> engine calls
	      the new state callback with arguments
	      <seetype marker="#state_enter"><c>(enter, OldState, Data)</c></seetype>
	      or
	      <seetype marker="#state_enter"><c>(enter, OldState, State, Data)</c></seetype>
	      (depending on <seetype marker="#callback_mode"><em>callback mode</em></seetype>)
	      and when it returns starts again from the top of this sequence.
	    </p>
	  </item>
	  <item>
            <p>
	      If
              <seetype marker="#postpone"><c>postpone()</c></seetype>
	      is <c>true</c>,
	      the current event is postponed.
	    </p>
	  </item>
	  <item>
	    <p>
	      If this is a <em>state change</em>,
	      the queue of incoming events
              is reset to start with the oldest postponed.
	    </p>
	  </item>
	  <item>
            <p>
	      All events stored with
	      <seetype marker="#action"><c>action()</c></seetype>
	      <c>next_event</c>
	      are inserted to be processed before previously queued events.
            </p>
	  </item>
	  <item>
	    <p>
	      Time-out timers
              <seetype marker="#event_timeout"><c>event_timeout()</c></seetype>,
              <seetype marker="#generic_timeout"><c>generic_timeout()</c></seetype>
	      and 
              <seetype marker="#state_timeout"><c>state_timeout()</c></seetype>
	      are handled.  Time-outs with zero time are guaranteed to be
	      delivered to the state machine before any external
	      not yet received event so if there is such a time-out requested,
	      the corresponding time-out zero event is enqueued as
	      the newest received event;
	      that is after already queued events
	      such as inserted and postponed events.
	    </p>
	    <p>
	      Any event cancels an
              <seetype marker="#event_timeout"><c>event_timeout()</c></seetype>
	      so a zero time event time-out is only generated
	      if the event queue is empty.
	    </p>
	    <p>
	      A <em>state change</em> cancels a
              <seetype marker="#state_timeout"><c>state_timeout()</c></seetype>
	      and any new transition option of this type
	      belongs to the new state, that is; a
              <seetype marker="#state_timeout"><c>state_timeout()</c></seetype>
	      applies to the state the state machine enters.
	    </p>
	  </item>
	  <item>
	    <p>
	      If there are enqueued events the
	      <seeerl marker="#state callback"><em>state callback</em></seeerl>
	      for the possibly new state
	      is called with the oldest enqueued event,
	      and we start again from the top of this sequence.
	    </p>
	  </item>
	  <item>
	    <p>
	      Otherwise the <c>gen_statem</c> goes into <c>receive</c>
	      or hibernation
	      (if
	      <seetype marker="#hibernate"><c>hibernate()</c></seetype>
	      is <c>true</c>)
	      to wait for the next message. In hibernation the next
	      non-system event awakens the <c>gen_statem</c>, or rather
	      the next incoming message awakens the <c>gen_statem</c>,
	      but if it is a system event it goes right back into hibernation.
	      When a new message arrives the 
	      <seeerl marker="#state callback"><em>state callback</em></seeerl>
	      is called with the corresponding event,
	      and we start again from the top of this sequence.
	    </p>
	  </item>
	</list>
      </desc>
    </datatype>
    <datatype>
      <name name="postpone"/>
      <desc>
	<p>
	  If <c>true</c>, postpones the current event and retries
	  it after a <em>state change</em>
	  (<c>NextState =/= State</c>).
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="hibernate"/>
      <desc>
	<p>
	  If <c>true</c>, hibernates the <c>gen_statem</c>
	  by calling
	  <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>
	  before going into <c>receive</c>
	  to wait for a new external event.
	</p>
	<note>
	  <p>
	    If there are enqueued events to process
	    when hibrnation is requested,
	    this is optimized by not hibernating but instead calling
	    <seemfa marker="erts:erlang#garbage_collect/0">
	      <c>erlang:garbage_collect/0</c>
	    </seemfa>
	    to simulate that the <c>gen_statem</c> entered hibernation
	    and immediately got awakened by an enqueued event.
	  </p>
	</note>
      </desc>
    </datatype>
    <datatype>
      <name name="event_timeout"/>
      <desc>
	<p>
	  Starts a timer set by
	  <seetype marker="#enter_action"><c>enter_action()</c></seetype>
	  <c>timeout</c>.
	  When the timer expires an event of
	  <seetype marker="#event_type"><c>event_type()</c></seetype>
	  <c>timeout</c> will be generated.
	  See
	  <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seemfa>
	  for how <c>Time</c> and
	  <seetype marker="#timeout_option"><c>Options</c></seetype>
	  are interpreted.  Future <c>erlang:start_timer/4</c> <c>Options</c>
	  will not necessarily be supported.
	</p>
	<p>
	  Any event that arrives cancels this time-out.
	  Note that a retried or inserted event counts as arrived.
	  So does a state time-out zero event, if it was generated
	  before this time-out is requested.
	</p>
	<p>
	  If <c>Time</c> is <c>infinity</c>,
	  no timer is started, as it never would expire anyway.
	</p>
	<p>
	  If <c>Time</c> is relative and <c>0</c>
	  no timer is actually started,
	  instead the the time-out event is enqueued to ensure
	  that it gets processed before any not yet
	  received external event, but after already queued events.
	</p>
	<p>
	  Note that it is not possible nor needed to cancel this time-out,
	  as it is cancelled automatically by any other event.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="generic_timeout"/>
      <desc>
	<p>
	  Starts a timer set by
	  <seetype marker="#enter_action"><c>enter_action()</c></seetype>
	  <c>{timeout,Name}</c>.
	  When the timer expires an event of
	  <seetype marker="#event_type"><c>event_type()</c></seetype>
	  <c>{timeout,Name}</c> will be generated.
	  See
	  <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seemfa>
	  for how <c>Time</c> and
	  <seetype marker="#timeout_option"><c>Options</c></seetype>
	  are interpreted.  Future <c>erlang:start_timer/4</c> <c>Options</c>
	  will not necessarily be supported.
	</p>
	<p>
	  If <c>Time</c> is <c>infinity</c>,
	  no timer is started, as it never would expire anyway.
	</p>
	<p>
	  If <c>Time</c> is relative and <c>0</c>
	  no timer is actually started,
	  instead the the time-out event is enqueued to ensure
	  that it gets processed before any not yet
	  received external event.
	</p>
	<p>
	  Setting a timer with the same <c>Name</c> while it is running
	  will restart it with the new time-out value.
	  Therefore it is possible to cancel
	  a specific time-out by setting it to <c>infinity</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="state_timeout"/>
      <desc>
	<p>
	  Starts a timer set by
	  <seetype marker="#enter_action"><c>enter_action()</c></seetype>
	  <c>state_timeout</c>.
	  When the timer expires an event of
	  <seetype marker="#event_type"><c>event_type()</c></seetype>
	  <c>state_timeout</c> will be generated.
	  See
	  <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seemfa>
	  for how <c>Time</c> and
	  <seetype marker="#timeout_option"><c>Options</c></seetype>
	  are interpreted.  Future <c>erlang:start_timer/4</c> <c>Options</c>
	  will not necessarily be supported.
	</p>
	<p>
	  If <c>Time</c> is <c>infinity</c>,
	  no timer is started, as it never would expire anyway.
	</p>
	<p>
	  If <c>Time</c> is relative and <c>0</c>
	  no timer is actually started,
	  instead the the time-out event is enqueued to ensure
	  that it gets processed before any not yet
	  received external event.
	</p>
	<p>
	  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 <c>infinity</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="timeout_option"/>
      <desc>
	<p>
	  If <c>Abs</c> is <c>true</c> an absolute timer is started,
	  and if it is <c>false</c> a relative, which is the default.
	  See
	  <seemfa marker="erts:erlang#start_timer/4">
	    <c>erlang:start_timer/4</c>
	  </seemfa>
	  for details.
	</p>
	<p>
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="action"/>
      <desc>
	<p>
	  These <em>transition actions</em> can be invoked by
	  returning them from the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  when it is called with an
	  <seetype marker="#event_type">event</seetype>,
	  from
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  or by giving them to
	  <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>.
	</p>
	<p>
	  Actions are executed in the containing list order.
	</p>
	<p>
	  Actions that set
	  <seetype marker="#transition_option">
	    transition options
	  </seetype>
	  override any previous of the same type,
	  so the last in the containing list wins.
	  For example, the last
	  <seetype marker="#postpone"><c>postpone()</c></seetype>
	  overrides any previous <c>postpone()</c> in the list.
	</p>
	<taglist>
	  <tag><c>postpone</c></tag>
	  <item>
	    <p>
	      Sets the
	      <seetype marker="#transition_option">
		<c>transition_option()</c>
	      </seetype>
	      <seetype marker="#postpone"><c>postpone()</c></seetype>
	      for this <em>state transition</em>.
	      This action is ignored when returned from
	      <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	      or given to
	      <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>,
	      as there is no event to postpone in those cases.
	    </p>
	  </item>
	  <tag><c>next_event</c></tag>
	  <item>
	    <p>
	      This action does not set any
	      <seetype marker="#transition_option">
		<c>transition_option()</c>
	      </seetype>
	      but instead stores the specified <c><anno>EventType</anno></c>
	      and <c><anno>EventContent</anno></c> for insertion after all
	      actions have been executed.
	    </p>
	    <p>
	      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 <c>next_event</c> in the containing
	      list becomes the first to process.
	    </p>
	    <p>
	      An event of type
	      <seetype marker="#event_type"><c>internal</c></seetype>
	      is to be used when you want to reliably distinguish
	      an event inserted this way from any external event.
	    </p>
	  </item>
	  <tag>
	    <c>change_callback_module</c>
	  </tag>
	  <item>
	    <p>
	      Changes the callback module to
	      <c><anno>NewModule</anno></c>
	      which will be used when calling all subsequent
	      <seeerl marker="#state callback">state callbacks</seeerl>.
	    </p>
	    <p>
	      The <c>gen_statem</c> engine will find out the
	      <seetype marker="#callback_mode">
		<em>callback mode</em>
	      </seetype>
	      of <c><anno>NewModule</anno></c> by calling
	      <seemfa marker="#Module:callback_mode/0">
		<c>NewModule:callback_mode/0</c>
	      </seemfa>
	      before the next
	      <seeerl marker="#state callback">state callback</seeerl>.
	    </p>
	    <p>
	      Changing the callback module does not affect the
	      <em>state transition</em> in any way,
	      it only changes which module that handles the events.
	      Be aware that all relevant callback functions in
	      <c><anno>NewModule</anno></c>
	      such as the
	      <seeerl marker="#state callback">state callback</seeerl>,
	      <seemfa marker="#Module:code_change/4"><c><anno>NewModule</anno>:code_change/4</c></seemfa>,
	      <seemfa marker="#Module:format_status/1">
		<c><anno>NewModule</anno>:format_status/1</c>
	      </seemfa>
	      and
	      <seemfa marker="#Module:terminate/3">
		<c><anno>NewModule</anno>:terminate/3</c>
	      </seemfa>
	      must be able to handle the state and data
	      from the old module.
	    </p>
	  </item>
	  <tag>
	    <c>push_callback_module</c>
	  </tag>
	  <item>
	    <p>
	      Pushes the current callback module
	      to the top of an internal stack of callback modules
	      and changes the callback module to
	      <c><anno>NewModule</anno></c>.
	      Otherwise like
	      <c>{change_callback_module, NewModule}</c>
	      above.
	    </p>
	  </item>
	  <tag>
	    <c>pop_callback_module</c>
	  </tag>
	  <item>
	    Pops the top module from the internal stack of
	    callback modules and changes the callback module
	    to be the popped module.
	    If the stack is empty the server fails.
	    Otherwise like
	    <c>{change_callback_module, NewModule}</c>
	    above.
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="enter_action"/>
      <desc>
	<p>
	  These <em>transition actions</em> can be invoked by
	  returning them from the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>, from
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  or by giving them to
	  <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>.
	</p>
	<p>
	  Actions are executed in the containing list order.
	</p>
	<p>
	  Actions that set
	  <seetype marker="#transition_option">transition options</seetype>
	  override any previous of the same type,
	  so the last in the containing list wins.
	  For example, the last
	  <seetype marker="#event_timeout"><c>event_timeout()</c></seetype>
	  overrides any previous <c>event_timeout()</c> in the list.
	</p>
	<taglist>
	  <tag><c>hibernate</c></tag>
	  <item>
	    <p>
	      Sets the
	      <seetype marker="#transition_option"><c>transition_option()</c></seetype>
	      <seetype marker="#hibernate"><c>hibernate()</c></seetype>
	      for this <em>state transition</em>.
	    </p>
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="timeout_action"/>
      <desc>
	<p>
	  These <em>transition actions</em> can be invoked by
	  returning them from the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>, from
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  or by giving them to
	  <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>.
	</p>
	<p>
	  These time-out actions sets time-out
	  <seetype marker="#transition_option">transition options</seetype>.
	</p>
	<taglist>
	  <tag><c>Time</c></tag>
	  <item>
	    <p>
	      Short for <c>{timeout,Time,Time}</c>, that is,
	      the time-out message is the time-out time.
	      This form exists to make the
	      <seeerl marker="#state callback"><em>state callback</em></seeerl>
	      return value <c>{next_state,NextState,NewData,Time}</c>
	      allowed like for <c>gen_fsm</c>.
	    </p>
	  </item>
	  <tag><c>timeout</c></tag>
	  <item>
	    <p>
	      Sets the
	      <seetype marker="#transition_option"><c>transition_option()</c></seetype>
	      <seetype marker="#event_timeout"><c>event_timeout()</c></seetype>
	      to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>
	      and time-out options
	      <seetype marker="#timeout_option"><c><anno>Options</anno></c></seetype>.
	    </p>
	  </item>
	  <tag><c>{timeout,<anno>Name</anno>}</c></tag>
	  <item>
	    <p>
	      Sets the
	      <seetype marker="#transition_option"><c>transition_option()</c></seetype>
	      <seetype marker="#generic_timeout"><c>generic_timeout()</c></seetype>
	      to <c><anno>Time</anno></c> for <c><anno>Name</anno></c>
	      with <c><anno>EventContent</anno></c>
	      and time-out options
	      <seetype marker="#timeout_option"><c><anno>Options</anno></c></seetype>.
	    </p>
	  </item>
	  <tag><c>state_timeout</c></tag>
	  <item>
	    <p>
	      Sets the
	      <seetype marker="#transition_option"><c>transition_option()</c></seetype>
	      <seetype marker="#state_timeout"><c>state_timeout()</c></seetype>
	      to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>
	      and time-out options
	      <seetype marker="#timeout_option"><c><anno>Options</anno></c></seetype>.
	    </p>
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="timeout_cancel_action" since="OTP 22.1"/>
      <desc>
	<p>
	  This is a shorter and clearer form of
	  <seetype marker="#timeout_action">
	    timeout_action()
	  </seetype>
	  with <c>Time = infinity</c> which cancels a time-out.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="timeout_update_action" since="OTP 22.1"/>
      <desc>
	<p>
	  Updates a time-out with a new <c>EventContent</c>.
	  See
	  <seetype marker="#timeout_action">
	    timeout_action()
	  </seetype>
	  for how to start a time-out.
	</p>
	<p>
	  If no time-out of the same type is active instead
	  insert the time-out event just like when starting
	  a time-out with relative <c>Time = 0</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="reply_action"/>
      <desc>
	<p>
	  This <em>transition action</em> can be invoked by
	  returning it from the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>, from
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  or by giving it to
	  <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>.
	</p>
	<p>
	  It does not set any
	  <seetype marker="#transition_option">
	    <c>transition_option()</c>
	  </seetype>
	  but instead replies to a caller waiting for a reply in
	  <seemfa marker="#call/2"><c>call/2</c></seemfa>.
	  <c><anno>From</anno></c> must be the term from argument
	  <seetype marker="#event_type"><c>{call,<anno>From</anno>}</c></seetype>
	  in a call to a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>.
	</p>
	<p>
	  Note that using this action from 
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  or
	  <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>
	  would be weird on the border of witchcraft
	  since there has been no earlier call to a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  in this server.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="init_result" n_vars="1"/>
      <name name="init_result" n_vars="2"/>
      <desc>
	<p>
	  For a succesful initialization,
	  <c><anno>State</anno></c> is the initial
	  <seetype marker="#state"><c>state()</c></seetype>
	  and <c><anno>Data</anno></c> the initial server
	  <seetype marker="#data"><c>data()</c></seetype>
	  of the <c>gen_statem</c>.
	</p>
	<p>
	  The <seetype marker="#action"><c>Actions</c></seetype>
	  are executed when entering the first
	  <seetype marker="#state">state</seetype> just as for a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>,
	  except that the action <c>postpone</c> is forced to
	  <c>false</c> since there is no event to postpone.
	</p>
	<p>
	  For an unsuccesful initialization,
	  <c>{stop, <anno>Reason</anno>}</c>,
	  <c>{error, <anno>Reason</anno>}</c>
	  or <c>ignore</c> should be used; see
          <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="state_enter_result" n_vars="1"/>
      <name name="state_enter_result" n_vars="2"/>
      <desc>
	<p>
	  <c><anno>State</anno></c> is the current state
	  and it cannot be changed since the state callback
	  was called with a
	  <seetype marker="#state_enter"><em>state enter call</em></seetype>.
	</p>
	<taglist>
	  <tag><c>next_state</c></tag>
	  <item>
	    <p>
	      The <c>gen_statem</c> does a state transition to
	      <c><anno>State</anno></c>, which has to be
	      the current state,
	      sets <c><anno>NewData</anno></c>,
	      and executes all <c><anno>Actions</anno></c>.
	    </p>
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="event_handler_result" n_vars="1"/>
      <name name="event_handler_result" n_vars="2"/>
      <desc>
	<p>
	  <c><anno>StateType</anno></c> is
	  <seetype marker="#state_name"><c>state_name()</c></seetype>
	  if
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  is <c>state_functions</c>, or
	  <seetype marker="#state"><c>state()</c></seetype>
	  if
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  is <c>handle_event_function</c>.
	</p>
	<taglist>
	  <tag><c>next_state</c></tag>
	  <item>
	    <p>
	      The <c>gen_statem</c> does a <em>state transition</em> to
	      <c><anno>NextState</anno></c>
	      (which can be the same as the current state),
	      sets <c><anno>NewData</anno></c>,
	      and executes all <c><anno>Actions</anno></c>.
	      If <c><anno>NextState</anno> =/= CurrentState</c>
	      the <em>state transition</em> is a <em>state change</em>.
	    </p>
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="state_callback_result" n_vars="1"/>
      <name name="state_callback_result" n_vars="2"/>
      <desc>
	<p>
	  <c><anno>ActionType</anno></c> is
	  <seetype marker="#enter_action"><c>enter_action()</c></seetype>
	  if the state callback was called with a
	  <seetype marker="#state_enter"><em>state enter call</em></seetype>
	  and
	  <seetype marker="#action"><c>action()</c></seetype>
	  if the state callback was called with an event.
	</p>
	<taglist>
	  <tag><c>keep_state</c></tag>
	  <item>
	    <p>
	      The same as
	      <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>.
	    </p>
	  </item>
	  <tag><c>keep_state_and_data</c></tag>
	  <item>
	    <p>
	      The same as
	      <c>{keep_state,CurrentData,<anno>Actions</anno>}</c>.
	    </p>
	  </item>
	  <tag><c>repeat_state</c></tag>
	  <item>
	    <p>
	      If the <c>gen_statem</c> runs with
	      <seetype marker="#state_enter"><em>state enter calls</em></seetype>,
	      the <em>state enter call</em> is repeated, see type
	      <seetype marker="#transition_option"><c>transition_option()</c></seetype>,
	      other than that <c>repeat_state</c> is the same as
	      <c>keep_state</c>.
	    </p>
	  </item>
	  <tag><c>repeat_state_and_data</c></tag>
	  <item>
	    <p>
	      The same as
	      <c>{repeat_state,CurrentData,<anno>Actions</anno>}</c>.
	    </p>
	  </item>
	  <tag><c>stop</c></tag>
	  <item>
	    <p>
	      Terminates the <c>gen_statem</c> by calling
	      <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa>
	      with <c>Reason</c> and
	      <c><anno>NewData</anno></c>, if specified.
              An exit signal with this reason is sent to linked processes and
              ports.
              The default <c>Reason</c> is <c>normal</c>.
	    </p>
	  </item>
	  <tag><c>stop_and_reply</c></tag>
	  <item>
	    <p>
	      Sends all <c><anno>Replies</anno></c>,
	      then terminates the <c>gen_statem</c> by calling
	      <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa>
	      with <c>Reason</c> and
	      <c><anno>NewData</anno></c>, if specified.
              An exit signal with this reason is sent to linked processes and
              ports.
	    </p>
	  </item>
	</taglist>
	<p>
	  All these terms are tuples or atoms and this property
	  will hold in any future version of <c>gen_statem</c>.
	</p>
      </desc>
    </datatype>

    <datatype>
      <name name="request_id"/>
      <desc>
	<p>
	  An opaque request identifier. See
          <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
	  for details.
	</p>
      </desc>
    </datatype>

    <datatype>
      <name name="request_id_collection"/>
      <desc>
        <p>
	  An opaque collection of request identifiers
          (<seetype marker="#request_id"><c>request_id()</c></seetype>)
	  where each request identifier can be associated with a label
          chosen by the user. For more information see
          <seemfa marker="#reqids_new/0"><c>reqids_new/0</c></seemfa>.
	</p>
      </desc>
    </datatype>

    <datatype>
      <name name="response_timeout"/>
      <desc>
        <p>
          Used to set a time limit on how long to wait for a response using
          either 
          <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>,
          <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
          <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>,
          or
          <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
          The time unit used is <c>millisecond</c>. Currently valid values:
        </p>
        <taglist>
          <tag><c>0..4294967295</c></tag>
          <item><p>
            Timeout relative to current time in milliseconds.
          </p></item>
          <tag><c>infinity</c></tag>
          <item><p>
            Infinite timeout. That is, the operation will never time out.
          </p></item>
          <tag><c>{abs, Timeout}</c></tag>
          <item><p>
            An absolute
            <seemfa marker="erts:erlang#monotonic_time/1">Erlang monotonic time</seemfa>
            timeout in milliseconds. That is, the operation will time out when
            <seemfa marker="erts:erlang#monotonic_time/1"><c>erlang:monotonic_time(millisecond)</c></seemfa>
            returns a value larger than or equal to <c>Timeout</c>. <c>Timeout</c>
            is not allowed to identify a time further into the future than <c>4294967295</c>
            milliseconds. Identifying the timeout using an absolute timeout value
            is especially handy when you have a deadline for responses corresponding
            to a complete collection of requests
            (<seetype marker="#request_id_collection"><c>request_id_collection()</c></seetype>)
,
            since you do not have to recalculate the relative time until the deadline
            over and over again.
	  </p></item>
        </taglist>
      </desc>
    </datatype>

    <datatype>
      <name name="format_status"/>
      <desc>
        <p>
          A map that describes the <c>gen_statem</c> status.
          The keys are:
	</p>
        <taglist>
          <tag><c>state</c></tag>
          <item>The current state of the <c>gen_statem</c> process.</item>
          <tag><c>data</c></tag>
          <item>The state data of the the <c>gen_statem</c> process.</item>
          <tag><c>reason</c></tag>
          <item>The reason that caused the state machine to terminate.</item>
          <tag><c>queue</c></tag>
          <item>The event queue of the <c>gen_statem</c> process.</item>
          <tag><c>postponed</c></tag>
          <item>
            The <seetype marker="#postpone">postponed</seetype>
            events queue of the <c>gen_statem</c> process.
          </item>
          <tag><c>timeouts</c></tag>
          <item>
            The active
            <seetype marker="#timeout_action">time-outs</seetype>
            of the <c>gen_statem</c> process.
          </item>
          <tag><c>log</c></tag>
          <item>
            The <seemfa marker="sys#log/2">sys log</seemfa> of the server.
          </item>
        </taglist>
        <p>
          New associations may be added to the status map
          without prior notice.
        </p>
      </desc>
    </datatype>
  </datatypes>

  <funcs>
    <func>
      <name name="call" arity="2" since="OTP 19.0"/>
      <name name="call" arity="3" since="OTP 19.0"/>
      <fsummary>Make a synchronous call to a <c>gen_statem</c>.</fsummary>
      <desc>
        <p>
	  Makes a synchronous call to the <c>gen_statem</c>
	  <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype>
	  by sending a request
	  and waiting until its reply arrives.
	  The <c>gen_statem</c> calls the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  with
	  <seetype marker="#event_type"><c>event_type()</c></seetype>
	  <c>{call,From}</c> and event content
	  <c><anno>Request</anno></c>.
	</p>
	<p>
	  A <c><anno>Reply</anno></c> is generated when a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returns with
	  <c>{reply,From,<anno>Reply</anno>}</c> as one
	  <seetype marker="#action"><c>action()</c></seetype>,
	  and that <c><anno>Reply</anno></c> becomes the return value
	  of this function.
	</p>
	<p>
	  <c><anno>Timeout</anno></c> is an integer &gt; 0,
	  which specifies how many milliseconds to wait for a reply,
	  or the atom <c>infinity</c> to wait indefinitely,
	  which is the default. If no reply is received within
	  the specified time, the function call fails.
	</p>
	<p>
          Previous issue with late replies that could occur when having
          network issues or using <c>dirty_timeout</c> is now prevented
          by use of
          <seeguide marker="system/reference_manual:processes#process-aliases"><i>process
          aliases</i></seeguide>. <c>{clean_timeout, <anno>T</anno>}</c>
          and <c>{dirty_timeout, <anno>T</anno>}</c> therefore no longer
          serves any purpose and will work the same as
          <c><anno>Timeout</anno></c> while all of them also being
          equally efficient.
	</p>
	<p>
	  The call can also fail, for example, if the <c>gen_statem</c>
	  dies before or during this function call.
	</p>
        <p>
          When this call fails it
          <seemfa marker="erts:erlang#exit/1">exits</seemfa>
          the calling process.
          The exit term is on the form
          <c>{Reason,&nbsp;Location}</c> where
          <c>Location&nbsp;=&nbsp;{gen_statem,call,ArgList}</c>.
          See
          <seemfa marker="gen_server#call/3">
            <c>gen_server:call/3</c>
          </seemfa>
          that has a description of relevant
          values for the <c>Reason</c> in the exit term.
        </p>
      </desc>
    </func>

    <func>
      <name name="cast" arity="2" since="OTP 19.0"/>
      <fsummary>Send an asynchronous event to a <c>gen_statem</c>.</fsummary>
      <desc>
	<p>
	  Sends an asynchronous event to the <c>gen_statem</c>
	  <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype>
	  and returns <c>ok</c> immediately,
	  ignoring if the destination node or <c>gen_statem</c>
	  does not exist.
	  The <c>gen_statem</c> calls the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  with
	  <seetype marker="#event_type"><c>event_type()</c></seetype>
	  <c>cast</c> and event content
	  <c><anno>Msg</anno></c>.
	</p>
      </desc>
    </func>

    <func>
      <name name="check_response" arity="2" since="OTP 23.0"/>
      <fsummary>Check if a message is a reply from a server.</fsummary>
      <desc>
	<p>
	  Check if <c><anno>Msg</anno></c> is a response corresponding
          to the request identifier <c><anno>ReqId</anno></c>. The request
          must have been made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>.
	  If <c>Msg</c> is a reply to the handle <c>ReqId</c>
	  the result of the request is returned in <c>Reply</c>.
	  Otherwise returns <c>no_reply</c> and no cleanup is done, and
	  thus the function shall be invoked repeatedly until a reply
	  is returned.
	</p>
	<p>
	  The return value <c><anno>Reply</anno></c> is generated when a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returns with
	  <c>{reply,From,<anno>Reply</anno>}</c> as one
	  <seetype marker="#action"><c>action()</c></seetype>,
	  and that <c><anno>Reply</anno></c> becomes the return value
	  of this function.
	</p>
	<p>
	  The function returns an error if the <c>gen_statem</c>
	  dies before or during this request.
	</p>
      </desc>
    </func>

    <func>
      <name name="check_response" arity="3" since="OTP 25.0"/>
      <fsummary>Check if a message is a reply from a server.</fsummary>
      <desc>
	<p>
	  Check if <c><anno>Msg</anno></c> is a response corresponding
          to a request identifier saved in <c><anno>ReqIdCollection</anno></c>.
          All request identifiers of <c><anno>ReqIdCollection</anno></c>
          must correspond to requests that have been made using
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> or
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>,
          and all request must have been made by the process calling this
          function.
	</p>
        <p>
          The <c><anno>Label</anno></c> in the response equals the
          <c><anno>Label</anno></c> associated with the request identifier
          that the response corresponds to. The <c><anno>Label</anno></c>
          of a request identifier is associated when
          <seemfa marker="#reqids_add/3">saving the request id</seemfa>
          in a request identifier collection, or when sending the request using
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
        </p>
        <p>
          Compared to
          <seemfa marker="#check_response/2"><c>check_response/2</c></seemfa>,
          the returned result associated with a specific request identifier
          or an exception associated with a specific request identifier will
          be wrapped in a 3-tuple. The first element of this tuple equals the
          value that would have been produced by <c>check_response/2</c>,
          the second element equals the <c><anno>Label</anno></c> associated
          with the specific request identifier, and the third element
          <c><anno>NewReqIdCollection</anno></c> is a possibly  modified
          request identifier collection.
        </p>
        <p>
          If <c><anno>ReqIdCollection</anno></c> is empty, the atom
          <c>no_request</c> will be returned. If <c><anno>Msg</anno></c>
          does not correspond to any of the request identifiers in
          <c><anno>ReqIdCollection</anno></c>, the atom
          <c>no_reply</c> is returned.
        </p>
        <p>
          If <c><anno>Delete</anno></c> equals <c>true</c>, the association
          with <c><anno>Label</anno></c> will have been deleted from
          <c><anno>ReqIdCollection</anno></c> in the resulting
          <c><anno>NewReqIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewReqIdCollection</anno></c> will equal
          <c><anno>ReqIdCollection</anno></c>. Note that deleting an
          association is not for free and that a collection containing
          already handled requests can still be used by subsequent calls to
          <c>check_response/3</c>,
 	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
          and
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
          However, without deleting handled associations, the above calls will
          not be able to detect when there are no more outstanding requests to
          handle, so you will have to keep track of this some other way than
          relying on a <c>no_request</c> return. Note that if you pass a
          collection only containing associations of already handled or
          abandoned requests to <c>check_response/3</c>, it will always
          return <c>no_reply</c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="enter_loop" arity="4" since="OTP 19.1"/>
      <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary>
      <desc>
	<p>
	  The same as
	  <seemfa marker="#enter_loop/6"><c>enter_loop/6</c></seemfa>
	  with <c>Actions = []</c> except that no
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  must have been registered.  This creates an anonymous server.
	</p>
      </desc>
    </func>

    <func>
      <name name="enter_loop" arity="5" since="OTP 19.0"/>
      <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary>
      <desc>
	<p>
	  If <c><anno>Server_or_Actions</anno></c> is a <c>list()</c>,
	  the same as
	  <seemfa marker="#enter_loop/6"><c>enter_loop/6</c></seemfa>
	  except that no
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  must have been registered and
	  <c>Actions = <anno>Server_or_Actions</anno></c>.
	  This creates an anonymous server.
	</p>
	<p>
	  Otherwise the same as
	  <seemfa marker="#enter_loop/6"><c>enter_loop/6</c></seemfa>
	  with
	  <c>Server = <anno>Server_or_Actions</anno></c> and
	  <c>Actions = []</c>.
	</p>
      </desc>
    </func>

    <func>
      <name name="enter_loop" arity="6" since="OTP 19.0"/>
      <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary>
      <desc>
	<p>
	  Makes the calling process become a <c>gen_statem</c>.
	  Does not return, instead the calling process enters
	  the <c>gen_statem</c> receive loop and becomes
	  a <c>gen_statem</c> server.
	  The process <em>must</em> have been started
	  using one of the start functions in
	  <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>.
	  The user is responsible for any initialization of the process,
	  including registering a name for it.
	</p>
	<p>
	  This function is useful when a more complex initialization
	  procedure is needed than
	  the <c>gen_statem</c> behavior provides.
	</p>
	<p>
	  <c><anno>Module</anno></c>, <c><anno>Opts</anno></c>
	  have the same meaning as when calling
	  <seemfa marker="#start_link/3"><c>start[_link|_monitor]/3,4</c></seemfa>.
	</p>
	<p>
	  If <c><anno>Server</anno></c> is <c>self()</c> an anonymous
	  server is created just as when using 
	  <seemfa marker="#start_link/3"><c>start[_link|_monitor]/3</c></seemfa>.
	  If <c><anno>Server</anno></c> is a
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  a named server is created just as when using
	  <seemfa marker="#start_link/4"><c>start[_link|_monitor]/4</c></seemfa>.
	  However, the
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  name must have been registered accordingly
	  <em>before</em> this function is called.
	</p>
        <p>
	  <c><anno>State</anno></c>, <c><anno>Data</anno></c>,
	  and <c><anno>Actions</anno></c>
	  have the same meanings as in the return value of
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>.
	  Also, the callback module does not need to export a
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  function.
	</p>
        <p>
	  The function fails if the calling process was not started by a
	  <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>
	  start function, or if it is not registered
	  according to
	  <seetype marker="#server_name"><c>server_name()</c></seetype>.
	</p>
      </desc>
    </func>

    <func>
      <name name="receive_response" arity="1" since="OTP 24.0"/>
      <fsummary>Receive for a reply from a server.</fsummary>
      <desc>
	<p>
          The same as calling 
	  <seemfa marker="#receive_response/2"><c>gen_statem:receive_response(ReqId,
          infinity)</c></seemfa>.
        </p>
      </desc>
    </func>
    
    <func>
      <name name="receive_response" arity="2" clause_i="1" since="OTP 24.0"/>
      <fsummary>Receive for a reply from a server.</fsummary>
      <desc>
	<p>
	  Receive a response corresponding to the request identifier
          <c><anno>ReqId</anno></c>- The request must have been made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
	  to the <c>gen_statem</c> process. This function must be called
	  from the same process from which
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
	  was made.
	</p>
	<p>
	  <c><anno>Timeout</anno></c> specifies how long to wait for
          a response. If no response is received within the specified time,
          the function returns <c>timeout</c>. Assuming that the
	  server executes on a node supporting aliases (introduced in
	  OTP 24) the request will also be abandoned. That is, no
          response will be received after a timeout. Otherwise, a
          stray response might be received at a later time.
	</p>
	<p>
	  The return value <c><anno>Reply</anno></c> is generated when a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returns with
	  <c>{reply,From,<anno>Reply</anno>}</c> as one
	  <seetype marker="#action"><c>action()</c></seetype>,
	  and that <c><anno>Reply</anno></c> becomes the return value
	  of this function.
	</p>
	<p>
	  The function returns an error if the <c>gen_statem</c>
	  dies before or during this function call.
	</p>
	<p>
	  The difference between
	  <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>
	  and <c>receive_response/2</c> is that <c>receive_response/2</c>
	  abandons the request at timeout so that a potential future
	  response is ignored, while <c>wait_response/2</c> does not.
	</p>
      </desc>
    </func>
    
    <func>
      <name name="receive_response" arity="3" since="OTP 25.0"/>
      <fsummary>Receive a response from a server.</fsummary>
      <desc>
	<p>
	  Receive a response corresponding to a request identifier saved
          in <c><anno>ReqIdCollection</anno></c>. All request identifiers
          of <c><anno>ReqIdCollection</anno></c> must correspond to requests
          that have been made using
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> or
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>,
          and all request must have been made by the process calling this
          function.
	</p>
        <p>
          The <c><anno>Label</anno></c> in the response equals the
          <c><anno>Label</anno></c> associated with the request identifier
          that the response corresponds to. The <c><anno>Label</anno></c>
          of a request identifier is associated when
          <seemfa marker="#reqids_add/3">adding the request id</seemfa>
          in a request identifier collection, or when sending the request using
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
        </p>
        <p>
          Compared to
          <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>,
          the returned result associated with a specific request identifier
          will be wrapped in a 3-tuple. The first element of this tuple equals
          the value that would have been produced by <c>receive_response/2</c>,
          the second element equals the <c><anno>Label</anno></c> associated
          with the specific request identifier, and the third element
          <c><anno>NewReqIdCollection</anno></c> is a possibly modified
          request identifier collection.
        </p>
        <p>
          If <c><anno>ReqIdCollection</anno></c> is empty, the atom
          <c>no_request</c> will be returned.
        </p>
	<p>
	  <c><anno>Timeout</anno></c> specifies how long to wait for
          a response. If no response is received within the specified time,
          the function returns <c>timeout</c>. Assuming that the
	  server executes on a node supporting aliases (introduced in
	  OTP 24) all requests identified by <c><anno>ReqIdCollection</anno></c>
          will also be abandoned. That is, no responses will be received
          after a timeout. Otherwise, stray responses might be received
          at a later time.
	</p>
	<p>
	  The difference between <c>receive_response/3</c> and
          <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>
          is that <c>receive_response/3</c> abandons the requests at timeout
          so that potential future responses are ignored, while
          <c>wait_response/3</c> does not.
	</p>
        <p>
          If <c><anno>Delete</anno></c> equals <c>true</c>, the association
          with <c><anno>Label</anno></c> will have been deleted from
          <c><anno>ReqIdCollection</anno></c> in the resulting
          <c><anno>NewReqIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewReqIdCollection</anno></c> will equal
          <c><anno>ReqIdCollection</anno></c>. Note that deleting an
          association is not for free and that a collection containing
          already handled requests can still be used by subsequent calls to
          <c>receive_response/3</c>,
 	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>,
          and
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
          However, without deleting handled associations, the above calls will
          not be able to detect when there are no more outstanding requests to
          handle, so you will have to keep track of this some other way than
          relying on a <c>no_request</c> return. Note that if you pass a
          collection only containing associations of already handled or
          abandoned requests to <c>receive_response/3</c>, it will always block
          until a timeout determined by <c><anno>Timeout</anno></c> is
          triggered.
        </p>
      </desc>
    </func>

    <func>
      <name name="reply" arity="1" since="OTP 19.0"/>
      <name name="reply" arity="2" since="OTP 19.0"/>
      <fsummary>Reply to a caller.</fsummary>
      <desc>
        <p>
	  This function can be used by a <c>gen_statem</c>
	  to explicitly send a reply to a process that waits in
	  <seemfa marker="#call/2"><c>call/2</c></seemfa>
	  when the reply cannot be defined in
	  the return value of a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>.
	</p>
	<p>
	  <c><anno>From</anno></c> must be the term from argument
	  <seetype marker="#event_type"><c>{call,<anno>From</anno>}</c></seetype>
	  to the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>.
	  A reply or multiple replies canalso be sent
	  using one or several
	  <seetype marker="#reply_action"><c>reply_action()</c></seetype>s
	  from a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>.
	</p>
	<note>
	  <p>
	    A reply sent with this function is not visible
	    in <seeerl marker="sys"><c>sys</c></seeerl> debug output.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="reqids_add" arity="3" since="OTP 25.0"/>
      <fsummary>Save a request identifier.</fsummary>
      <desc>
	<p>
          Saves <c><anno>ReqId</anno></c> and associates a <c><anno>Label</anno></c>
          with the request identifier by adding this information to
          <c><anno>ReqIdCollection</anno></c> and returning the
          resulting request identifier collection.
        </p>
      </desc>
    </func>

    <func>
      <name name="reqids_new" arity="0" since="OTP 25.0"/>
      <fsummary>Create a new empty request identifier collection.</fsummary>
      <desc>
	<p>
          Returns a new empty request identifier collection. A 
          request identifier collection can be utilized in order
          the handle multiple outstanding requests.
        </p>
        <p>
          Request identifiers of requests made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
          can be saved in a request identifier collection using 
	  <seemfa marker="#reqids_add/3"><c>reqids_add/3</c></seemfa>.
          Such a collection of request identifiers can later be used in
          order to get one response corresponding to a request in the
          collection by passing the collection as argument to
          <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>,
	  or,
	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>.
        </p>
        <p>
          <seemfa marker="#reqids_size/1"><c>reqids_size/1</c></seemfa>
          can be used to determine the amount of request identifiers in a
          request identifier collection.
        </p>
      </desc>
    </func>

    <func>
      <name name="reqids_size" arity="1" since="OTP 25.0"/>
      <fsummary>Get size of a request identifier collection.</fsummary>
      <desc>
	<p>
          Returns the amount of request identifiers saved in
          <c><anno>ReqIdCollection</anno></c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="reqids_to_list" arity="1" since="OTP 25.0"/>
      <fsummary>List a request identifiers.</fsummary>
      <desc>
	<p>
          Returns a list of <c>{<anno>ReqId</anno>, <anno>Label</anno>}</c>
          tuples which corresponds to all request identifiers with their
          associated labels present in the <c><anno>ReqIdCollection</anno></c>
          collection.
        </p>
      </desc>
    </func>

    <func>
      <name name="send_request" arity="2" since="OTP 23.0"/>
      <fsummary>Send a request to a <c>gen_statem</c>.</fsummary>
      <desc>
        <p>
	  Sends an asynchronous <c>call</c> request <c><anno>Request</anno></c>
          to the <c>gen_statem</c> process identified by <c><anno>ServerRef</anno></c>
          and returns a request identifier <c><anno>ReqId</anno></c>. The return
          value <c><anno>ReqId</anno></c> shall later be used with
          <seemfa marker="#receive_response/2"> <c>receive_response/2</c></seemfa>,
          <seemfa marker="#wait_response/2"> <c>wait_response/2</c></seemfa>, or
	  <seemfa marker="#check_response/2"> <c>check_response/2</c></seemfa>
	  to fetch the actual result of the request. Besides passing
          the request identifier directly to these functions, it can also be
          saved in a request identifier collection using 
	  <seemfa marker="#reqids_add/3"><c>reqids_add/3</c></seemfa>.
          Such a collection of request identifiers can later be used in
          order to get one response corresponding to a request in the
          collection by passing the collection as argument to
          <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>, or
	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>.
          If you are about to save the request identifier in a request identifier
          collection, you may want to consider using
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>
          instead.
	</p>
	<p>
	  The call <c>gen_statem:wait_response(gen_statem:send_request(ServerRef,Request), Timeout)</c>
	  can be seen as equivalent to
	  <seemfa marker="#call/3"><c>gen_statem:call(Server,Request,Timeout)</c></seemfa>,
	  ignoring the error handling.
	</p>
	<p>
	  The <c>gen_statem</c> calls the
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  with
	  <seetype marker="#event_type"><c>event_type()</c></seetype>
	  <c>{call,From}</c> and event content
	  <c><anno>Request</anno></c>.
	</p>
	<p>
	  A <c>Reply</c> is generated when a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returns with
	  <c>{reply,From,Reply}</c> as one
	  <seetype marker="#action"><c>action()</c></seetype>,
	  and that <c>Reply</c> becomes the return value
	  of <seemfa marker="#receive_response/2"> <c>receive_response/1,2</c></seemfa>,
	  <seemfa marker="#wait_response/2"> <c>wait_response/1,2</c></seemfa>, or
	  <seemfa marker="#check_response/2"> <c>check_response/2</c></seemfa> function.
	</p>
      </desc>
    </func>

    <func>
      <name name="send_request" arity="4" since="OTP 25.0"/>
      <fsummary>Sends a request to a generic server.</fsummary>
      <desc>
	<p>
          Sends an asynchronous <c>call</c> request <c><anno>Request</anno></c>
          to the <c>gen_statem</c> process identified by <c><anno>ServerRef</anno></c>.
          The <c><anno>Label</anno></c> will be associated with the request
          identifier of the operation and added to the returned request
          identifier collection <c><anno>NewReqIdCollection</anno></c>.
          The collection can later be used in order to get one response
          corresponding to a request in the collection by passing the
          collection as argument to
	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>,
	  or,
	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>.
        </p>

        <p>
          The same as calling
          <seemfa marker="#reqids_add/3"><c>gen_statem:reqids_add</c></seemfa>(<seemfa
          marker="#send_request/2"><c>statem:send_request</c></seemfa><c>(<anno>ServerRef</anno>,
          <anno>Request</anno>), <anno>Label</anno>,
          <anno>ReqIdCollection</anno>)</c>, but calling <c>send_request/4</c>
          is slightly more efficient.
        </p>
      </desc>
    </func>

    <func>
      <name name="start" arity="3" since="OTP 19.0"/>
      <name name="start" arity="4" since="OTP 19.0"/>
      <fsummary>Create a standalone <c>gen_statem</c> process.</fsummary>
      <desc>
        <p>
	  Creates a standalone <c>gen_statem</c> process according to
	  OTP design principles (using
	  <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>
	  primitives).
	  As it does not get linked to the calling process,
	  this start function cannot be used by a supervisor
	  to start a child.
	</p>
	<p>
	  For a description of arguments and return values, see
	  <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
	</p>
      </desc>
    </func>

    <func>
      <name name="start_link" arity="3" since="OTP 19.0"/>
      <name name="start_link" arity="4" since="OTP 19.0"/>
      <fsummary>Create a linked <c>gen_statem</c> process.</fsummary>
      <desc>
        <p>
	  Creates a <c>gen_statem</c> process according
	  to OTP design principles
	  (using
	  <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>
	  primitives)
	  that is linked to the calling process.
	  This is essential when the <c>gen_statem</c> must be part of
	  a supervision tree so it gets linked to its supervisor.
	</p>
	<p>
	  The <c>gen_statem</c> process calls
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  to initialize the server. To ensure a synchronized startup
	  procedure, <c>start_link/3,4</c> does not return until
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  has returned.
	</p>
	<p>
	  <c><anno>ServerName</anno></c> specifies the
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  to register for the <c>gen_statem</c>.
	  If the <c>gen_statem</c> is started with <c>start_link/3</c>,
	  no <c><anno>ServerName</anno></c> is provided and
	  the <c>gen_statem</c> is not registered.
	</p>
        <p><c><anno>Module</anno></c> is the name of the callback module.</p>
        <p>
	  <c><anno>Args</anno></c> is an arbitrary term that is passed as
	  the argument to
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>.
	</p>
        <list type="bulleted">
          <item>
	    <p>
	      If option
	      <seetype marker="#start_opt">
		<c>{timeout,Time}</c>
	      </seetype>
	      is present in
	      <c><anno>Opts</anno></c>, the <c>gen_statem</c>
	      is allowed to spend <c>Time</c> milliseconds initializing
	      or it terminates and the start function returns
	      <seetype marker="#start_ret"><c>{error,timeout}</c></seetype>.
            </p>
          </item>
          <item>
            <p>If option
	    <seetype marker="#enter_loop_opt">
	      <c>{hibernate_after,HibernateAfterTimeout}</c>
	    </seetype>
	    is present, the <c>gen_statem</c>
            process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and
            if no message is received, the process goes into hibernation automatically
            (by calling <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>).
            </p>
          </item>
          <item>
            <p>
              If option
              <seetype marker="#enter_loop_opt">
		<c>{debug,Dbgs}</c>
	      </seetype>
              is present in <c><anno>Opts</anno></c>, debugging through
              <seeerl marker="sys"><c>sys</c></seeerl> is activated.
            </p>
          </item>
          <item>
            <p>
              If option
              <seetype marker="#start_opt">
		<c>{spawn_opt,SpawnOpts}</c>
	      </seetype>
	      is present in
              <c><anno>Opts</anno></c>, <c>SpawnOpts</c> is passed
              as option list to
	      <seemfa marker="erts:erlang#spawn_opt/2"><c>erlang:spawn_opt/2</c></seemfa>,
              which is used to spawn the <c>gen_statem</c> process.
            </p>
          </item>
        </list>
        <note>
	  <p>
	    Using spawn option <c>monitor</c> is not
            allowed, it causes this function to fail with reason
            <c>badarg</c>.
	  </p>
        </note>
	<p>
	  If the <c>gen_statem</c> is successfully created
	  and initialized, this function returns
	  <seetype marker="#start_ret"><c>{ok,Pid}</c></seetype>,
	  where <c>Pid</c> is the <c>pid()</c>
	  of the <c>gen_statem</c>.
	  If a process with the specified <c><anno>ServerName</anno></c>
	  exists already, this function returns
	  <seetype marker="#start_ret"><c>{error,{already_started,Pid}}</c></seetype>,
	  where <c>Pid</c> is the <c>pid()</c> of that process.
	</p>
	<p>
	  If <c>Module:init/1</c> fails with <c>Reason</c>,
	  this function returns
	  <seetype marker="#start_ret"><c>{error, Reason}</c></seetype>.
	  If <c>Module:init/1</c> returns
	  <seetype marker="#start_ret"><c>{stop, Reason}</c></seetype>,
	  <seetype marker="#start_ret"><c>{shutdown, Reason}</c></seetype>
	  or
	  <seetype marker="#start_ret"><c>ignore</c></seetype>,
	  the process is terminated and this function
	  returns
	  <seetype marker="#start_ret"><c>{error,Reason}</c></seetype>
	  or
	  <seetype marker="#start_ret"><c>ignore</c></seetype>,
	  respectively.
          An exit signal with the same <c>Reason</c> (or <c>normal</c> if
          <c>Module:init/1</c> returns <c>ignore</c>) is set to linked processes
          and ports, including the process calling <c>start_link/3,4</c>.
	</p>
	<p>The difference between returning <c>{stop, Reason}</c> and
	<c>{error, Reason}</c> (from <c>Module:init/1</c>) is that
	<c>error</c> results in a graceful ("silent") termination. </p>
      </desc>
    </func>

    <func>
      <name name="start_monitor" arity="3" since="OTP 23.0"/>
      <name name="start_monitor" arity="4" since="OTP 23.0"/>
      <fsummary>Create a standalone <c>gen_statem</c> process.</fsummary>
      <desc>
        <p>
	  Creates a standalone <c>gen_statem</c> process according to
	  OTP design principles (using
	  <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>
	  primitives) and atomically sets up a monitor to
	  the newly created process.
	  As it does not get linked to the calling process,
	  this start function cannot be used by a supervisor
	  to start a child.
	</p>
	<p>
	  For a description of arguments and return values, see
	  <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
	  Note that the return value on successful start differs from
	  <c>start_link/3,4</c>. <c>start_monitor/3,4</c> will return
	  <c>{ok,{Pid,Mon}}</c> where <c>Pid</c> is the process identifier
	  of the process, and <c>Mon</c> is a reference to the monitor
	  set up to monitor the process. If the start is not successful,
	  the caller will be blocked until the <c>DOWN</c> message has
	  been received and removed from the message queue.
	</p>
      </desc>
    </func>

    <func>
      <name name="stop" arity="1" since="OTP 19.0"/>
      <fsummary>Synchronously stop a generic server.</fsummary>
      <desc>
	<p>
	  The same as
	  <seemfa marker="#stop/3"><c>stop(<anno>ServerRef</anno>, normal, infinity)</c></seemfa>.
	</p>
      </desc>
    </func>

    <func>
      <name name="stop" arity="3" since="OTP 19.0"/>
      <fsummary>Synchronously stop a generic server.</fsummary>
      <desc>
	<p>
	  Orders the <c>gen_statem</c>
	  <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype>
	  to exit with the specified <c><anno>Reason</anno></c>
	  and waits for it to terminate.
	  The <c>gen_statem</c> calls
	  <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa>
	  before exiting.
	</p>
	<p>
	  This function returns <c>ok</c> if the server terminates
	  with the expected reason. Any other reason than <c>normal</c>,
	  <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an
	  error report to be issued through
	  <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>.
          An exit signal with the same reason is sent to linked processes
          and ports.
	  The default <c><anno>Reason</anno></c> is <c>normal</c>.
	</p>
	<p>
	  <c><anno>Timeout</anno></c> is an integer &gt; 0,
	  which specifies how many milliseconds to wait for the server to
	  terminate, or the atom <c>infinity</c> to wait indefinitely.
	  Defaults to <c>infinity</c>.
	  If the server does not terminate within the specified time,
          the call exits the calling process
          with reason <c>timeout</c>.
	</p>
        <p>
          If the process does not exist, the call exits
          the calling process with reason <c>noproc</c>,
          and with reason <c>{nodedown,Node}</c>
          if the connection fails to the remote <c>Node</c>
          where the server runs.
        </p>
      </desc>
    </func>

    <func>
      <name name="wait_response" arity="1" clause_i="1" since="OTP 23.0"/>
      <fsummary>Wait for a reply from a server.</fsummary>
      <desc>
	<p>
          The same as calling 
	  <seemfa marker="#receive_response/2"><c>gen_statem:receive_response(ReqId,
          infinity)</c></seemfa>.
        </p>
      </desc>
    </func>
    
    <func>
      <name name="wait_response" arity="2" since="OTP 23.0"/>
      <fsummary>Wait or poll for a reply from a server.</fsummary>
      <desc>
	<p>
	  Wait for a response corresponding to the request identifier
          <c><anno>ReqId</anno></c>. The request must have been made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
	  to the <c>gen_statem</c> process. This function must be called
	  from the same process from which
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
	  was made.
	</p>
	<p>
	  <c><anno>WaitTime</anno></c> specifies how long to wait for
          a reply. If no reply is received within the specified
	  time, the function returns <c>timeout</c> and no cleanup is
	  done, and thus the function can be invoked repeatedly until a
	  reply is returned.
	</p>
	<p>
	  The return value <c><anno>Reply</anno></c> is generated when a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returns with
	  <c>{reply,From,<anno>Reply</anno>}</c> as one
	  <seetype marker="#action"><c>action()</c></seetype>,
	  and that <c><anno>Reply</anno></c> becomes the return value
	  of this function.
	</p>
	<p>
	  The function returns an error if the <c>gen_statem</c>
	  dies before or during this function call.
	</p>
	<p>
	  The difference between
	  <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>
	  and <c>wait_response/2</c> is that <c>receive_response/2</c>
	  abandons the request at timeout so that a potential future
	  response is ignored, while <c>wait_response/2</c> does not.
	</p>
      </desc>
    </func>

    <func>
      <name name="wait_response" arity="3" since="OTP 25.0"/>
      <fsummary>Wait or poll for a response from a server.</fsummary>
      <desc>
	<p>
	  Wait for a response corresponding to a request identifier saved
          in <c><anno>ReqIdCollection</anno></c>. All request identifiers
          of <c><anno>ReqIdCollection</anno></c> must correspond to requests
          that have been made using
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> or
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>,
          and all request must have been made by the process calling this
          function.
	</p>
        <p>
          The <c><anno>Label</anno></c> in the response equals the
          <c><anno>Label</anno></c> associated with the request identifier
          that the response corresponds to. The <c><anno>Label</anno></c>
          of a request identifier is associated when
          <seemfa marker="#reqids_add/3">saving the request id</seemfa> in
          a request identifier collection, or when sending the request using
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
        </p>
        <p>
          Compared to
          <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>,
          the returned result associated with a specific request identifier
          or an exception associated with a specific request identifier will
          be wrapped in a 3-tuple. The first element of this tuple equals the
          value that would have been produced by <c>wait_response/2</c>,
          the second element equals the <c><anno>Label</anno></c> associated
          with the specific request identifier, and the third element
          <c><anno>NewReqIdCollection</anno></c> is a possibly  modified
          request identifier collection.
        </p>
        <p>
          If <c><anno>ReqIdCollection</anno></c> is empty, <c>no_request</c>
          will be returned. If no response is received before the
          <c><anno>WaitTime</anno></c> timeout has triggered, the atom
          <c>timeout</c> is returned. It is valid to continue waiting for a
          response as many times as needed up until a response has been received
          and completed by <c>check_response()</c>, <c>receive_response()</c>,
          or <c>wait_response()</c>.
        </p>
	<p>
	  The difference between
          <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>
	  and <c>wait_response/3</c> is that <c>receive_response/3</c>
	  abandons requests at timeout so that a potential future
	  responses are ignored, while <c>wait_response/3</c> does not.
	</p>
        <p>
          If <c><anno>Delete</anno></c> equals <c>true</c>, the association
          with <c><anno>Label</anno></c> will have been deleted from
          <c><anno>ReqIdCollection</anno></c> in the resulting
          <c><anno>NewReqIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewReqIdCollection</anno></c> will equal
          <c><anno>ReqIdCollection</anno></c>. Note that deleting an
          association is not for free and that a collection containing
          already handled requests can still be used by subsequent calls to
          <c>wait_response/3</c>,
 	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>,
          and
	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>.
          However, without deleting handled associations, the above calls will
          not be able to detect when there are no more outstanding requests to
          handle, so you will have to keep track of this some other way than
          relying on a <c>no_request</c> return. Note that if you pass a
          collection only containing associations of already handled or
          abandoned requests to <c>wait_response/3</c>, it will always block
          until a timeout determined by <c><anno>WaitTime</anno></c> is
          triggered and then return <c>no_reply</c>.
        </p>
      </desc>
    </func>
  </funcs>

 

  <funcs>
    <fsdescription>
      <title>Callback Functions</title>
      <p>
        The following functions are to be exported from a
        <c>gen_statem</c> callback module.
      </p>
    </fsdescription>
    <func>
      <name since="OTP 19.1">Module:callback_mode() -> CallbackMode</name>
      <fsummary>
	Define the callback mode for the callback module.
      </fsummary>
      <type>
	<v>
	  CallbackMode =
	  <seetype marker="#callback_mode">callback_mode()</seetype> |
	  [ <seetype marker="#callback_mode">callback_mode()</seetype>
	  | <seetype marker="#state_enter">state_enter()</seetype> ]
	</v>
      </type>
      <desc>
        <p>
	  This function is called by a <c>gen_statem</c>
	  when it needs to find out the
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  of the callback module.  The value is cached by <c>gen_statem</c>
	  for efficiency reasons, so this function is only called
	  once after server start, after code change,
	  and after changing the callback module,
	  but before the first
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  in the current callback module's code version is called.
	  More occasions may be added in future versions
	  of <c>gen_statem</c>.
	</p>
	<p>
	  Server start happens either when
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  returns or when
	  <seemfa marker="#enter_loop/4"><c>enter_loop/4-6</c></seemfa>
	  is called.
	  Code change happens when
	  <seemfa marker="#Module:code_change/4"><c>Module:code_change/4</c></seemfa>
	  returns.
	  A change of the callback module happens when a
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  returns any of the actions
	  <seetype marker="#action"><c>change_callback_module</c></seetype>,
	  <seetype marker="#action"><c>push_callback_module</c></seetype> or
	  <seetype marker="#action"><c>pop_callback_module</c></seetype>.
	</p>
	<p>
	  The <c>CallbackMode</c> is either just
	  <seetype marker="#callback_mode"><c>callback_mode()</c></seetype>
	  or a list containing
	  <seetype marker="#callback_mode"><c>callback_mode()</c></seetype>
	  and possibly the atom
	  <seetype marker="#state_enter"><c>state_enter</c></seetype>.
	</p>
	<note>
	  <p>
	    If this function's body does not return an inline constant
	    value the callback module is doing something strange.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name since="OTP 19.0">Module:code_change(OldVsn, OldState, OldData, Extra) ->
        Result
      </name>
      <fsummary>
	Update the internal state during upgrade/downgrade.
      </fsummary>
      <type>
        <v>OldVsn = Vsn | {down,Vsn}</v>
        <v>&nbsp;&nbsp;Vsn = term()</v>
        <v>OldState = NewState = term()</v>
        <v>Extra = term()</v>
	<v>Result = {ok,NewState,NewData} | Reason</v>
	<v>
	  OldState = NewState =
	  <seetype marker="#state">state()</seetype>
	</v>
	<v>
	  OldData = NewData =
	  <seetype marker="#data">data()</seetype>
	</v>
	<v>Reason = term()</v>
      </type>
      <desc>
        <note>
          <p>
	    This callback is optional, so callback modules need not export it.
            If a release upgrade/downgrade with
	    <c>Change = {advanced,Extra}</c>
	    specified in the <c>.appup</c> file is made
	    when <c>code_change/4</c> is not implemented
	    the process will crash with exit reason <c>undef</c>.
	  </p>
        </note>
        <p>
	  This function is called by a <c>gen_statem</c> when it is to
	  update its internal state during a release upgrade/downgrade,
	  that is, when the instruction <c>{update,Module,Change,...}</c>,
	  where <c>Change = {advanced,Extra}</c>, is specified in the
	  <seefile marker="sasl:appup"><c>appup</c></seefile>
	  file. For more information, see
	  <seeguide marker="system/design_principles:release_handling#instr">OTP Design Principles</seeguide>.
	</p>
	<p>
	  For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
	  for a downgrade, <c>OldVsn</c> is
	  <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c>
	  attribute(s) of the old version of the callback module
	  <c>Module</c>. If no such attribute is defined, the version
	  is the checksum of the Beam file.
	</p>
        <p>
	  <c>OldState</c> and <c>OldData</c> is the internal state
	  of the <c>gen_statem</c>.
	</p>
	<p>
	  <c>Extra</c> is passed "as is" from the <c>{advanced,Extra}</c>
	  part of the update instruction.
	</p>
	<p>
	  If successful, the function must return the updated
	  internal state in an
	  <c>{ok,NewState,NewData}</c> tuple.
	</p>
	<p>
	  If the function returns a failure <c>Reason</c>, the ongoing
	  upgrade fails and rolls back to the old release.
	  Note that <c>Reason</c> cannot be an <c>{ok,_,_}</c> tuple
	  since that will be regarded as a
	  <c>{ok,NewState,NewData}</c> tuple,
	  and that a tuple matching <c>{ok,_}</c>
	  is an also invalid failure <c>Reason</c>.
	  It is recommended to use an atom as <c>Reason</c> since
	  it will be wrapped in an <c>{error,Reason}</c> tuple.
	</p>
	<p>
	  Also note when upgrading a <c>gen_statem</c>,
	  this function and hence
	  the <c>Change = {advanced,Extra}</c> parameter in the
	  <seefile marker="sasl:appup"><c>appup</c></seefile> file
	  is not only needed to update the internal state
	  or to act on the <c>Extra</c> argument.
	  It is also needed if an upgrade or downgrade should change 
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>,
	  or else the <em>callback mode</em> after the code change
	  will not be honoured,
	  most probably causing a server crash.
	</p>
	<p>
	  If the server changes callback module using any of the actions
	  <seetype marker="#action"><c>change_callback_module</c></seetype>,
	  <seetype marker="#action"><c>push_callback_module</c></seetype> or
	  <seetype marker="#action"><c>pop_callback_module</c></seetype>,
	  be aware that it is always the current callback module that
	  will get this callback call.  That the current callback module
	  handles the current state and data update should be no surprise,
	  but it must be able to handle even parts of
	  the state and data that it is not familiar with,
	  somehow.
	</p>
	<p>
	  In the supervisor
	  <seeguide marker="system/design_principles:sup_princ#child-specification">child specification</seeguide>
	  there is a list of modules which is recommended to contain
	  only the callback module.
	  For a <c>gen_statem</c> with multiple callback modules
	  there is no real need to list all of them,
	  it may not even be possible since the list could change
	  after code upgrade.
	  If this list would contain only the start callback module,
	  as recommended, what is important is to upgrade <em>that</em> module
	  whenever a <em>synchronized code replacement</em> is done.
	  Then the release handler concludes that an upgrade
	  that upgrades <em>that</em> module needs to suspend,
	  code change, and resume any server whose child specification
	  declares that it is using <em>that</em> module.
	  And again; the <em>current</em> callback module will get the
	  <c>Module:code_change/4</c> call.
	</p>
      </desc>
    </func>

    <func>
      <name since="OTP 19.0">Module:init(Args) -> Result(StateType)</name>
      <fsummary>
	Initialize process and internal state.
      </fsummary>
      <type>
        <v>Args = term()</v>
	<v>
	  Result(StateType) =
	  <seetype marker="#init_result">init_result(StateType)</seetype>
	</v>
      </type>
      <desc>
	<marker id="Module:init-1"/>
	<p>
	  Whenever a <c>gen_statem</c> is started using
	  <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>,
	  <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>,
	  or
	  <seemfa marker="#start/3"><c>start/3,4</c></seemfa>,
	  this function is called by the new process to initialize
	  the implementation state and server data.
	</p>
	<p>
	  <c>Args</c> is the <c>Args</c> argument provided to that start
	  function.
	</p>
        <note>
	  <p>
	    Note that if the <c>gen_statem</c> is started through
	    <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>
	    and
	    <seemfa marker="#enter_loop/4"><c>enter_loop/4-6</c></seemfa>,
	    this callback will never be called.
	    Since this callback is not optional it can
	    in that case be implemented as:
	  </p>
	  <pre>
-spec init(_) -> no_return().
init(Args) -> erlang:error(not_implemented, [Args]).</pre>
        </note>
      </desc>
    </func>

    <func>
      <name since="OTP 25.0">Module:format_status(Status) -> NewStatus</name>
      <fsummary>Optional function for providing a term describing the
        current <c>gen_statem</c> status.</fsummary>
      <type>
        <v>Status = <seetype marker="#format_status">format_status()</seetype></v>
        <v>NewStatus = <seetype marker="#format_status">format_status()</seetype></v>
      </type>
      <desc>
        <note>
	  <p>
	    This callback is optional, so a callback module does not need
	    to export it. The <c>gen_statem</c> module provides a default
	    implementation of this function that returns
	    <c>{State,Data}</c>.
	  </p>
	  <p>
	    If this callback is exported but fails,
	    to hide possibly sensitive data,
	    the default function will instead return <c>{State,Info}</c>,
	    where <c>Info</c> says nothing but the fact that
	    <c>format_status/2</c> has crashed.
	  </p>
        </note>
        <p>This function is called by a <c>gen_statem</c> process when
          any of the following apply:</p>
        <list type="bulleted">
          <item>
            <p><seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
              is invoked to get the <c>gen_statem</c> status.</p>
          </item>
          <item>
            <p>The <c>gen_statem</c> process terminates abnormally and logs an error.</p>
          </item>
        </list>
        <p>
	  This function is useful for changing the form and
          appearance of the <c>gen_statem</c> status for these cases. A
          callback module wishing to change the
          <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
	  return value and how
          its status appears in termination error logs exports
          an instance of <c>format_status/1</c>,
          which will get a map <c>Status</c> that describes
          the current states of the <c>gen_statem</c>,
          and shall return a map <c>NewStatus</c>
          containing the same keys as the input map,
          but it may transform some values.
	</p>
        <p>
	  One use case for this function is to return compact alternative
          state representations to avoid having large state terms
          printed in log files. Another is to hide sensitive data from
	  being written to the error log.
	</p>
        <p>Example:</p>
        <code type="erl"><![CDATA[
format_status(Status) ->
  maps:map(
    fun(state,State) ->
            maps:remove(private_key, State);
       (message,{password, _Pass}) ->
            {password, removed};
       (_,Value) ->
            Value
    end, Status).
]]></code>
      </desc>
    </func>
    
    <func>
      <name since="OTP 19.0">Module:format_status(Opt, [PDict,State,Data]) ->
        Status
      </name>
      <fsummary>
	Describe the current <c>gen_statem</c> status (optional).
      </fsummary>
      <type>
        <v>Opt = normal | terminate</v>
        <v>PDict = [{Key, Value}]</v>
	<v>
	  State =
	  <seetype marker="#state">state()</seetype>
	</v>
	<v>
	  Data =
	  <seetype marker="#data">data()</seetype>
	</v>
	<v>Key = term()</v>
	<v>Value = term()</v>
        <v>Status = term()</v>
      </type>
      <desc>
        <warning>
          <p>This callback is deprecated, in new code use <seemfa marker="#Module:format_status/1">
            format_status/1</seemfa>. If a <seemfa marker="#Module:format_status/1">format_status/1</seemfa>
            callback exists, then this function will never be called.</p>
        </warning>
        <note>
	  <p>
	    This callback is optional, so a callback module does not need
	    to export it. The <c>gen_statem</c> module provides a default
	    implementation of this function that returns
	    <c>{State,Data}</c>.
	  </p>
	  <p>
	    If this callback is exported but fails,
	    to hide possibly sensitive data,
	    the default function will instead return <c>{State,Info}</c>,
	    where <c>Info</c> says nothing but the fact that
	    <c>format_status/2</c> has crashed.
	  </p>
        </note>
        <p>This function is called by a <c>gen_statem</c> process when
          any of the following apply:</p>
        <list type="bulleted">
	  <item>
	    One of
	    <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
	    is invoked to get the <c>gen_statem</c> status. <c>Opt</c> is set
	    to the atom <c>normal</c> for this case.
	  </item>
	  <item>
	    The <c>gen_statem</c> terminates abnormally and logs an error.
	    <c>Opt</c> is set to the atom <c>terminate</c> for this case.
	  </item>
	</list>
        <p>
	  This function is useful for changing the form and
          appearance of the <c>gen_statem</c> status for these cases. A
          callback module wishing to change the
          <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
	  return value and how
          its status appears in termination error logs exports an
          instance of <c>format_status/2</c>, which returns a term
          describing the current status of the <c>gen_statem</c>.
	</p>
	<p>
	  <c>PDict</c> is the current value of the process dictionary
          of the <c>gen_statem</c>.
	</p>
	<p>
	  <seetype marker="#state"><c>State</c></seetype>
	  is the internal state of the <c>gen_statem</c>.
	</p>
	<p>
	  <seetype marker="#data"><c>Data</c></seetype>
	  is the internal server data of the <c>gen_statem</c>.
	</p>
	<p>
	  The function is to return <c>Status</c>, a term that
	  contains the appropriate details
          of the current state and status of
          the <c>gen_statem</c>. There are no restrictions on the
          form <c>Status</c> can take, but for the
          <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
	  case (when <c>Opt</c>
          is <c>normal</c>), the recommended form for
          the <c>Status</c> value is <c>[{data, [{"State",
          Term}]}]</c>, where <c>Term</c> provides relevant details of
          the <c>gen_statem</c> state. Following this recommendation is not
          required, but it makes the callback module status
          consistent with the rest of the
          <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
	  return value.
	</p>
	<p>
	  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.
	</p>
      </desc>
    </func>

    <func>
      <name since="OTP 19.0">Module:StateName(enter, OldState, Data) ->
        StateEnterResult(StateName)
      </name>
      <name since="OTP 19.0">Module:StateName(EventType, EventContent, Data) ->
        StateFunctionResult
      </name>
      <name since="OTP 19.0">Module:handle_event(enter, OldState, State, Data) ->
	StateEnterResult(State)
      </name>
      <name since="OTP 19.0">Module:handle_event(EventType, EventContent, State, Data) ->
	HandleEventResult
      </name>
      <fsummary>Handle an event.</fsummary>
      <type>
	<v>
	  EventType =
	  <seetype marker="#event_type">event_type()</seetype>
	</v>
	<v>EventContent = term()</v>
	<v>
	  State =
	  <seetype marker="#state">state()</seetype>
	</v>
	<v>
	  Data = NewData =
	  <seetype marker="#data">data()</seetype>
	</v>
	<v>
	  StateEnterResult(StateName) =
	  <seetype marker="#state_enter_result">state_enter_result(StateName)</seetype>
	</v>
	<v>
	  StateFunctionResult =
	  <seetype marker="#event_handler_result">event_handler_result</seetype>(<seetype marker="#state_name">state_name()</seetype>)
	</v>
	<v>
	  StateEnterResult(State) =
	  <seetype marker="#state_enter_result">state_enter_result(State)</seetype>
	</v>
	<v>
	  HandleEventResult =
	  <seetype marker="#event_handler_result">event_handler_result</seetype>(<seetype marker="#state">state()</seetype>)
	</v>
      </type>
      <desc>
	<p>
	  Whenever a <c>gen_statem</c> receives an event from
	  <seemfa marker="#call/2"><c>call/2</c></seemfa>,
	  <seemfa marker="#cast/2"><c>cast/2</c></seemfa>, or
	  as a normal process message, one of these functions is called. If
	  <seetype marker="#callback_mode"><em>callback mode</em></seetype>
	  is <c>state_functions</c>, <c>Module:StateName/3</c> is called,
	  and if it is <c>handle_event_function</c>,
	  <c>Module:handle_event/4</c> is called.
	</p>
	<p>
	  If <c>EventType</c> is
	  <seetype marker="#event_type"><c>{call,From}</c></seetype>,
	  the caller waits for a reply. The reply can be sent
	  from this or from any other
	  <seeerl marker="#state callback"><em>state callback</em></seeerl>
	  by returning with <c>{reply,From,Reply}</c> in
	  <seetype marker="#action"><c>Actions</c></seetype>, in
	  <seetype marker="#reply_action"><c>Replies</c></seetype>,
	  or by calling
	  <seemfa marker="#reply/2"><c>reply(From, Reply)</c></seemfa>.
	</p>
	<p>
	  If this function returns with a next state that
	  does not match equal (<c>=/=</c>) to the current state,
	  all postponed events are retried in the next state.
	</p>
	<p>
	  The only difference between <c>StateFunctionResult</c> and
	  <c>HandleEventResult</c> is that for <c>StateFunctionResult</c>
	  the next state must be an atom, but for <c>HandleEventResult</c>
	  there is no restriction on the next state.
	</p>
	<p>
	  For options that can be set and actions that can be done
	  by <c>gen_statem</c> after returning from this function,
	  see <seetype marker="#action"><c>action()</c></seetype>.
	</p>
	<p>
	  When the <c>gen_statem</c> runs with
	  <seetype marker="#state_enter"><em>state enter calls</em></seetype>,
	  these functions are also called with arguments
	  <c>(enter, OldState, ...)</c> during every <em>state change</em>.
	  In this case there are some restrictions on the
	  <seetype marker="#enter_action">actions</seetype>
	  that may be returned:
	  <seetype marker="#postpone"><c>postpone()</c></seetype>
	  is not allowed since a <em>state enter call</em> is not
	  an event so there is no event to postpone, and 
	  <seetype marker="#action"><c>{next_event,_,_}</c></seetype>
	  is not allowed since using <em>state enter calls</em>
	  should not affect how events are consumed and produced.
	  You may also not change states from this call.
	  Should you return <c>{next_state,NextState, ...}</c>
	  with <c>NextState =/= State</c> the <c>gen_statem</c> crashes.
	  Note that it is actually allowed to use
	  <c>{repeat_state, NewData, ...}</c> although it makes little
	  sense since you immediately will be called again with a new
	  <em>state enter call</em> making this just a weird way
	  of looping, and there are better ways to loop in Erlang.
	  If you do not update <c>NewData</c> and have some
	  loop termination condition, or if you use
	  <c>{repeat_state_and_data, _}</c> or
	  <c>repeat_state_and_data</c> you have an infinite loop!
	  You are advised to use <c>{keep_state,...}</c>,
	  <c>{keep_state_and_data,_}</c> or
	  <c>keep_state_and_data</c>
	  since changing states from a <em>state enter call</em>
	  is not possible anyway.
	</p>
	<p>
	  Note the fact that you can use
	  <seemfa marker="erts:erlang#throw/1"><c>throw</c></seemfa>
	  to return the result, which can be useful.
	  For example to bail out with <c>throw(keep_state_and_data)</c>
	  from deep within complex code that cannot
	  return <c>{next_state,State,Data}</c> because
	  <c>State</c> or <c>Data</c> is no longer in scope.
	</p>
      </desc>
    </func>

    <func>
      <name since="OTP 19.0">Module:terminate(Reason, State, Data) -> Ignored</name>
      <fsummary>Clean up before termination.</fsummary>
      <type>
        <v>Reason = normal | shutdown | {shutdown,term()} | term()</v>
	<v>State = <seetype marker="#state">state()</seetype></v>
	<v>Data = <seetype marker="#data">data()</seetype></v>
	<v>Ignored = term()</v>
      </type>
      <desc>
        <note>
          <p>This callback is optional, so callback modules need not
          export it. The <c>gen_statem</c> module provides a default
          implementation without cleanup.</p>
        </note>
	<p>
	  This function is called by a <c>gen_statem</c>
	  when it is about to terminate. It is to be the opposite of
	  <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
	  and do any necessary cleaning up. When it returns,
	  the <c>gen_statem</c> terminates with <c>Reason</c>. The return
	  value is ignored.</p>
	<p>
	  <c>Reason</c> is a term denoting the stop reason and
	  <seetype marker="#state"><c>State</c></seetype>
	  is the internal state of the <c>gen_statem</c>.
	</p>
	<p>
	  <c>Reason</c> depends on why the <c>gen_statem</c>
	  is terminating.
	  If it is because another callback function has returned, a
	  stop tuple <c>{stop,Reason}</c> in
	  <seetype marker="#action"><c>Actions</c></seetype>,
	  <c>Reason</c> has the value specified in that tuple.
	  If it is because of a failure, <c>Reason</c> is the error reason.
	</p>
        <p>
	  If the <c>gen_statem</c> is part of a supervision tree and is
          ordered by its supervisor to terminate, this function is
          called with <c>Reason = shutdown</c> if both the following
          conditions apply:</p>
        <list type="bulleted">
          <item>
            <p>
	      The <c>gen_statem</c> has been set
	      to trap exit signals.
            </p>
	  </item>
          <item>
            <p>
	      The shutdown strategy as defined in the supervisor's
              child specification is an integer time-out value, not
              <c>brutal_kill</c>.
            </p>
	  </item>
        </list>
        <p>
	  Even if the <c>gen_statem</c> is <em>not</em>
	  part of a supervision tree, this function is called
	  if it receives an <c>'EXIT'</c> message from its parent.
	  <c>Reason</c> is the same as
	  in the <c>'EXIT'</c> message.
	</p>
        <p>
	  Otherwise, the <c>gen_statem</c> is immediately terminated.
	</p>
        <p>
	  Notice that for any other reason than <c>normal</c>,
          <c>shutdown</c>, or <c>{shutdown,Term}</c>,
	  the <c>gen_statem</c> is assumed to terminate because of an error
	  and an error report is issued using
          <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>.
	</p>
        <p>
          When the <c>gen_statem</c> process exits, an exit signal with the
          same reason is sent to linked processes and ports.
        </p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p>
      <seeerl marker="gen_event"><c>gen_event(3)</c></seeerl>,
      <seeerl marker="gen_fsm"><c>gen_fsm(3)</c></seeerl>,
      <seeerl marker="gen_server"><c>gen_server(3)</c></seeerl>,
      <seeerl marker="proc_lib"><c>proc_lib(3)</c></seeerl>,
      <seeerl marker="supervisor"><c>supervisor(3)</c></seeerl>,
      <seeerl marker="sys"><c>sys(3)</c></seeerl>.
    </p>
  </section>
</erlref>