From adcc726c36555434204dd0fccd13ed984741a7fb Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 26 Oct 2015 11:50:43 +0100
Subject: Factor out common code to gen.erl

---
 lib/stdlib/src/gen.erl        | 121 ++++++++++++++++++++++++++++++++++--------
 lib/stdlib/src/gen_event.erl  |  11 ++--
 lib/stdlib/src/gen_fsm.erl    |  85 ++++-------------------------
 lib/stdlib/src/gen_server.erl | 112 ++++----------------------------------
 4 files changed, 119 insertions(+), 210 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen.erl b/lib/stdlib/src/gen.erl
index a05c2ce6fd..7dd02b84e7 100644
--- a/lib/stdlib/src/gen.erl
+++ b/lib/stdlib/src/gen.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2015. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -26,7 +26,8 @@
 %%%
 %%% The standard behaviour should export init_it/6.
 %%%-----------------------------------------------------------------
--export([start/5, start/6, debug_options/1,
+-export([start/5, start/6, debug_options/2,
+	 name/1, unregister_name/1, get_proc_name/1, get_parent/0,
 	 call/3, call/4, reply/2, stop/1, stop/3]).
 
 -export([init_it/6, init_it/7]).
@@ -124,7 +125,7 @@ init_it(GenMod, Starter, Parent, Mod, Args, Options) ->
     init_it2(GenMod, Starter, Parent, self(), Mod, Args, Options).
 
 init_it(GenMod, Starter, Parent, Name, Mod, Args, Options) ->
-    case name_register(Name) of
+    case register_name(Name) of
 	true ->
 	    init_it2(GenMod, Starter, Parent, Name, Mod, Args, Options);
 	{false, Pid} ->
@@ -297,19 +298,19 @@ where({global, Name}) -> global:whereis_name(Name);
 where({via, Module, Name}) -> Module:whereis_name(Name);
 where({local, Name})  -> whereis(Name).
 
-name_register({local, Name} = LN) ->
+register_name({local, Name} = LN) ->
     try register(Name, self()) of
 	true -> true
     catch
 	error:_ ->
 	    {false, where(LN)}
     end;
-name_register({global, Name} = GN) ->
+register_name({global, Name} = GN) ->
     case global:register_name(Name, self()) of
 	yes -> true;
 	no -> {false, where(GN)}
     end;
-name_register({via, Module, Name} = GN) ->
+register_name({via, Module, Name} = GN) ->
     case Module:register_name(Name, self()) of
 	yes ->
 	    true;
@@ -317,34 +318,108 @@ name_register({via, Module, Name} = GN) ->
 	    {false, where(GN)}
     end.
 
+name({local,Name}) -> Name;
+name({global,Name}) -> Name;
+name({via,_, Name}) -> Name;
+name(Pid) when is_pid(Pid) -> Pid.
+
+unregister_name({local,Name}) ->
+    try unregister(Name) of
+	_ -> ok
+    catch
+	_:_ -> ok
+    end;
+unregister_name({global,Name}) ->
+    _ = global:unregister_name(Name),
+    ok;
+unregister_name({via, Mod, Name}) ->
+    _ = Mod:unregister_name(Name),
+    ok;
+unregister_name(Pid) when is_pid(Pid) ->
+    ok.
+
+get_proc_name(Pid) when is_pid(Pid) ->
+    Pid;
+get_proc_name({local, Name}) ->
+    case process_info(self(), registered_name) of
+	{registered_name, Name} ->
+	    Name;
+	{registered_name, _Name} ->
+	    exit(process_not_registered);
+	[] ->
+	    exit(process_not_registered)
+    end;
+get_proc_name({global, Name}) ->
+    case global:whereis_name(Name) of
+	undefined ->
+	    exit(process_not_registered_globally);
+	Pid when Pid =:= self() ->
+	    Name;
+	_Pid ->
+	    exit(process_not_registered_globally)
+    end;
+get_proc_name({via, Mod, Name}) ->
+    case Mod:whereis_name(Name) of
+	undefined ->
+	    exit({process_not_registered_via, Mod});
+	Pid when Pid =:= self() ->
+	    Name;
+	_Pid ->
+	    exit({process_not_registered_via, Mod})
+    end.
+
+get_parent() ->
+    case get('$ancestors') of
+	[Parent | _] when is_pid(Parent) ->
+	    Parent;
+	[Parent | _] when is_atom(Parent) ->
+	    name_to_pid(Parent);
+	_ ->
+	    exit(process_was_not_started_by_proc_lib)
+    end.
+
+name_to_pid(Name) ->
+    case whereis(Name) of
+	undefined ->
+	    case global:whereis_name(Name) of
+		undefined ->
+		    exit(could_not_find_registered_name);
+		Pid ->
+		    Pid
+	    end;
+	Pid ->
+	    Pid
+    end.
+
 
 timeout(Options) ->
-    case opt(timeout, Options) of
-	{ok, Time} ->
+    case lists:keyfind(timeout, 1, Options) of
+	{_,Time} ->
 	    Time;
-	_ ->
+	false ->
 	    infinity
     end.
 
 spawn_opts(Options) ->
-    case opt(spawn_opt, Options) of
-	{ok, Opts} ->
+    case lists:keyfind(spawn_opt, 1, Options) of
+	{_,Opts} ->
 	    Opts;
-	_ ->
+	false ->
 	    []
     end.
 
-opt(Op, [{Op, Value}|_]) ->
-    {ok, Value};
-opt(Op, [_|Options]) ->
-    opt(Op, Options);
-opt(_, []) ->
-    false.
-
-debug_options(Opts) ->
-    case opt(debug, Opts) of
-	{ok, Options} -> sys:debug_options(Options);
-	_ -> []
+debug_options(Name, Opts) ->
+    case lists:keyfind(debug, 1, Opts) of
+	{_,Options} ->
+	    try sys:debug_options(Options)
+	    catch _:_ ->
+		    error_logger:format(
+		      "~p: ignoring erroneous debug options - ~p~n",
+		      [Name,Options]),
+		    []
+	    end;
+	false ->
+	    []
     end.
 
 format_status_header(TagLine, Pid) when is_pid(Pid) ->
diff --git a/lib/stdlib/src/gen_event.erl b/lib/stdlib/src/gen_event.erl
index 3d63c19de7..aedc0e7c59 100644
--- a/lib/stdlib/src/gen_event.erl
+++ b/lib/stdlib/src/gen_event.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2015. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -147,16 +147,11 @@ init_it(Starter, self, Name, Mod, Args, Options) ->
     init_it(Starter, self(), Name, Mod, Args, Options);
 init_it(Starter, Parent, Name0, _, _, Options) ->
     process_flag(trap_exit, true),
-    Debug = gen:debug_options(Options),
+    Name = gen:name(Name0),
+    Debug = gen:debug_options(Name, Options),
     proc_lib:init_ack(Starter, {ok, self()}),
-    Name = name(Name0),
     loop(Parent, Name, [], Debug, false).
 
-name({local,Name}) -> Name;
-name({global,Name}) -> Name;
-name({via,_, Name}) -> Name;
-name(Pid) when is_pid(Pid) -> Pid.
-
 -spec add_handler(emgr_ref(), handler(), term()) -> term().
 add_handler(M, Handler, Args) -> rpc(M, {add_handler, Handler, Args}).
 
diff --git a/lib/stdlib/src/gen_fsm.erl b/lib/stdlib/src/gen_fsm.erl
index 7eabb95548..77d41c0652 100644
--- a/lib/stdlib/src/gen_fsm.erl
+++ b/lib/stdlib/src/gen_fsm.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2015. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -305,64 +305,11 @@ enter_loop(Mod, Options, StateName, StateData, Timeout) ->
     enter_loop(Mod, Options, StateName, StateData, self(), Timeout).
 
 enter_loop(Mod, Options, StateName, StateData, ServerName, Timeout) ->
-    Name = get_proc_name(ServerName),
-    Parent = get_parent(),
-    Debug = gen:debug_options(Options),
+    Name = gen:get_proc_name(ServerName),
+    Parent = gen:get_parent(),
+    Debug = gen:debug_options(Name, Options),
     loop(Parent, Name, StateName, StateData, Mod, Timeout, Debug).
 
-get_proc_name(Pid) when is_pid(Pid) ->
-    Pid;
-get_proc_name({local, Name}) ->
-    case process_info(self(), registered_name) of
-	{registered_name, Name} ->
-	    Name;
-	{registered_name, _Name} ->
-	    exit(process_not_registered);
-	[] ->
-	    exit(process_not_registered)
-    end;
-get_proc_name({global, Name}) ->
-    case global:whereis_name(Name) of
-	undefined ->
-	    exit(process_not_registered_globally);
-	Pid when Pid =:= self() ->
-	    Name;
-	_Pid ->
-	    exit(process_not_registered_globally)
-    end;
-get_proc_name({via, Mod, Name}) ->
-    case Mod:whereis_name(Name) of
-	undefined ->
-	    exit({process_not_registered_via, Mod});
-	Pid when Pid =:= self() ->
-	    Name;
-	_Pid ->
-	    exit({process_not_registered_via, Mod})
-    end.
-
-get_parent() ->
-    case get('$ancestors') of
-	[Parent | _] when is_pid(Parent) ->
-	    Parent;
-	[Parent | _] when is_atom(Parent) ->
-	    name_to_pid(Parent);
-	_ ->
-	    exit(process_was_not_started_by_proc_lib)
-    end.
-
-name_to_pid(Name) ->
-    case whereis(Name) of
-	undefined ->
-	    case global:whereis_name(Name) of
-		undefined ->
-		    exit(could_not_find_registered_name);
-		Pid ->
-		    Pid
-	    end;
-	Pid ->
-	    Pid
-    end.
-
 %%% ---------------------------------------------------
 %%% Initiate the new process.
 %%% Register the name using the Rfunc function
@@ -373,8 +320,8 @@ name_to_pid(Name) ->
 init_it(Starter, self, Name, Mod, Args, Options) ->
     init_it(Starter, self(), Name, Mod, Args, Options);
 init_it(Starter, Parent, Name0, Mod, Args, Options) ->
-    Name = name(Name0),
-    Debug = gen:debug_options(Options),
+    Name = gen:name(Name0),
+    Debug = gen:debug_options(Name, Options),
     case catch Mod:init(Args) of
 	{ok, StateName, StateData} ->
 	    proc_lib:init_ack(Starter, {ok, self()}), 	    
@@ -383,15 +330,15 @@ init_it(Starter, Parent, Name0, Mod, Args, Options) ->
 	    proc_lib:init_ack(Starter, {ok, self()}), 	    
 	    loop(Parent, Name, StateName, StateData, Mod, Timeout, Debug);
 	{stop, Reason} ->
-	    unregister_name(Name0),
+	    gen:unregister_name(Name0),
 	    proc_lib:init_ack(Starter, {error, Reason}),
 	    exit(Reason);
 	ignore ->
-	    unregister_name(Name0),
+	    gen:unregister_name(Name0),
 	    proc_lib:init_ack(Starter, ignore),
 	    exit(normal);
 	{'EXIT', Reason} ->
-	    unregister_name(Name0),
+	    gen:unregister_name(Name0),
 	    proc_lib:init_ack(Starter, {error, Reason}),
 	    exit(Reason);
 	Else ->
@@ -400,20 +347,6 @@ init_it(Starter, Parent, Name0, Mod, Args, Options) ->
 	    exit(Error)
     end.
 
-name({local,Name}) -> Name;
-name({global,Name}) -> Name;
-name({via,_, Name}) -> Name;
-name(Pid) when is_pid(Pid) -> Pid.
-
-unregister_name({local,Name}) ->
-    _ = (catch unregister(Name));
-unregister_name({global,Name}) ->
-    _ = global:unregister_name(Name);
-unregister_name({via, Mod, Name}) ->
-    _ = Mod:unregister_name(Name);
-unregister_name(Pid) when is_pid(Pid) ->
-    Pid.
-
 %%-----------------------------------------------------------------
 %% The MAIN loop
 %%-----------------------------------------------------------------
diff --git a/lib/stdlib/src/gen_server.erl b/lib/stdlib/src/gen_server.erl
index c58b1de609..6aaefbbbfe 100644
--- a/lib/stdlib/src/gen_server.erl
+++ b/lib/stdlib/src/gen_server.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2015. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -304,9 +304,9 @@ enter_loop(Mod, Options, State, Timeout) ->
     enter_loop(Mod, Options, State, self(), Timeout).
 
 enter_loop(Mod, Options, State, ServerName, Timeout) ->
-    Name = get_proc_name(ServerName),
-    Parent = get_parent(),
-    Debug = debug_options(Name, Options),
+    Name = gen:get_proc_name(ServerName),
+    Parent = gen:get_parent(),
+    Debug = gen:debug_options(Name, Options),
     loop(Parent, Name, State, Mod, Timeout, Debug).
 
 %%%========================================================================
@@ -323,8 +323,8 @@ enter_loop(Mod, Options, State, ServerName, Timeout) ->
 init_it(Starter, self, Name, Mod, Args, Options) ->
     init_it(Starter, self(), Name, Mod, Args, Options);
 init_it(Starter, Parent, Name0, Mod, Args, Options) ->
-    Name = name(Name0),
-    Debug = debug_options(Name, Options),
+    Name = gen:name(Name0),
+    Debug = gen:debug_options(Name, Options),
     case catch Mod:init(Args) of
 	{ok, State} ->
 	    proc_lib:init_ack(Starter, {ok, self()}), 	    
@@ -339,15 +339,15 @@ init_it(Starter, Parent, Name0, Mod, Args, Options) ->
 	    %% (Otherwise, the parent process could get
 	    %% an 'already_started' error if it immediately
 	    %% tried starting the process again.)
-	    unregister_name(Name0),
+	    gen:unregister_name(Name0),
 	    proc_lib:init_ack(Starter, {error, Reason}),
 	    exit(Reason);
 	ignore ->
-	    unregister_name(Name0),
+	    gen:unregister_name(Name0),
 	    proc_lib:init_ack(Starter, ignore),
 	    exit(normal);
 	{'EXIT', Reason} ->
-	    unregister_name(Name0),
+	    gen:unregister_name(Name0),
 	    proc_lib:init_ack(Starter, {error, Reason}),
 	    exit(Reason);
 	Else ->
@@ -356,20 +356,6 @@ init_it(Starter, Parent, Name0, Mod, Args, Options) ->
 	    exit(Error)
     end.
 
-name({local,Name}) -> Name;
-name({global,Name}) -> Name;
-name({via,_, Name}) -> Name;
-name(Pid) when is_pid(Pid) -> Pid.
-
-unregister_name({local,Name}) ->
-    _ = (catch unregister(Name));
-unregister_name({global,Name}) ->
-    _ = global:unregister_name(Name);
-unregister_name({via, Mod, Name}) ->
-    _ = Mod:unregister_name(Name);
-unregister_name(Pid) when is_pid(Pid) ->
-    Pid.
-    
 %%%========================================================================
 %%% Internal functions
 %%%========================================================================
@@ -858,86 +844,6 @@ error_info(Reason, Name, Msg, State, Debug) ->
     sys:print_log(Debug),
     ok.
 
-%%% ---------------------------------------------------
-%%% Misc. functions.
-%%% ---------------------------------------------------
-
-opt(Op, [{Op, Value}|_]) ->
-    {ok, Value};
-opt(Op, [_|Options]) ->
-    opt(Op, Options);
-opt(_, []) ->
-    false.
-
-debug_options(Name, Opts) ->
-    case opt(debug, Opts) of
-	{ok, Options} -> dbg_opts(Name, Options);
-	_ -> []
-    end.
-
-dbg_opts(Name, Opts) ->
-    case catch sys:debug_options(Opts) of
-	{'EXIT',_} ->
-	    format("~p: ignoring erroneous debug options - ~p~n",
-		   [Name, Opts]),
-	    [];
-	Dbg ->
-	    Dbg
-    end.
-
-get_proc_name(Pid) when is_pid(Pid) ->
-    Pid;
-get_proc_name({local, Name}) ->
-    case process_info(self(), registered_name) of
-	{registered_name, Name} ->
-	    Name;
-	{registered_name, _Name} ->
-	    exit(process_not_registered);
-	[] ->
-	    exit(process_not_registered)
-    end;    
-get_proc_name({global, Name}) ->
-    case global:whereis_name(Name) of
-	undefined ->
-	    exit(process_not_registered_globally);
-	Pid when Pid =:= self() ->
-	    Name;
-	_Pid ->
-	    exit(process_not_registered_globally)
-    end;
-get_proc_name({via, Mod, Name}) ->
-    case Mod:whereis_name(Name) of
-	undefined ->
-	    exit({process_not_registered_via, Mod});
-	Pid when Pid =:= self() ->
-	    Name;
-	_Pid ->
-	    exit({process_not_registered_via, Mod})
-    end.
-
-get_parent() ->
-    case get('$ancestors') of
-	[Parent | _] when is_pid(Parent)->
-            Parent;
-        [Parent | _] when is_atom(Parent)->
-            name_to_pid(Parent);
-	_ ->
-	    exit(process_was_not_started_by_proc_lib)
-    end.
-
-name_to_pid(Name) ->
-    case whereis(Name) of
-	undefined ->
-	    case global:whereis_name(Name) of
-		undefined ->
-		    exit(could_not_find_registered_name);
-		Pid ->
-		    Pid
-	    end;
-	Pid ->
-	    Pid
-    end.
-
 %%-----------------------------------------------------------------
 %% Status information
 %%-----------------------------------------------------------------
-- 
cgit v1.2.3


From 6ace96d3e5c9ac8ace3d8967bcafb3e6a081d9be Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 26 Oct 2015 11:52:17 +0100
Subject: New state machine

---
 lib/stdlib/doc/src/Makefile                |    3 +-
 lib/stdlib/doc/src/gen_statem.xml          | 1131 +++++++++++++++++++++++++
 lib/stdlib/doc/src/ref_man.xml             |    3 +-
 lib/stdlib/doc/src/specs.xml               |    1 +
 lib/stdlib/src/Makefile                    |    3 +-
 lib/stdlib/src/gen_statem.erl              | 1095 ++++++++++++++++++++++++
 lib/stdlib/src/proc_lib.erl                |   16 +-
 lib/stdlib/src/stdlib.app.src              |    3 +-
 lib/stdlib/test/Makefile                   |    1 +
 lib/stdlib/test/error_logger_forwarder.erl |    8 +-
 lib/stdlib/test/gen_statem_SUITE.erl       | 1250 ++++++++++++++++++++++++++++
 11 files changed, 3501 insertions(+), 13 deletions(-)
 create mode 100644 lib/stdlib/doc/src/gen_statem.xml
 create mode 100644 lib/stdlib/src/gen_statem.erl
 create mode 100644 lib/stdlib/test/gen_statem_SUITE.erl

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile
index 196c86748f..26602764a6 100644
--- a/lib/stdlib/doc/src/Makefile
+++ b/lib/stdlib/doc/src/Makefile
@@ -1,7 +1,7 @@
 #
 # %CopyrightBegin%
 #
-# Copyright Ericsson AB 1997-2015. All Rights Reserved.
+# Copyright Ericsson AB 1997-2016. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -68,6 +68,7 @@ XML_REF3_FILES = \
 	gen_event.xml \
 	gen_fsm.xml \
 	gen_server.xml \
+	gen_statem.xml \
 	io.xml \
 	io_lib.xml \
 	lib.xml \
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
new file mode 100644
index 0000000000..885021f61c
--- /dev/null
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -0,0 +1,1131 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2016</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>gen_statem</module>
+  <modulesummary>Generic State Machine Behaviour</modulesummary>
+  <description>
+    <p>A behaviour module for implementing a state machine, primarily
+      a finite state machine, but an infinite state space is possible.
+      A generic state machine process (gen_statem) implemented using
+      this module will have a standard set of interface functions
+      and include functionality for tracing and error reporting.
+      It will also fit into an OTP supervision tree. Refer to
+      <seealso marker="doc/design_principles:gen_server_concepts">
+        OTP Design Principles</seealso> for more information.
+    </p>
+    <p>A gen_statem assumes all specific parts to be located in a
+      callback module exporting a pre-defined set of functions.
+      The relationship between the behaviour functions and the callback
+      functions can be illustrated as follows:</p>
+    <pre>
+gen_statem module            Callback module
+-----------------            ---------------
+gen_statem:start
+gen_statem:start_link -----> Module:init/1
+
+gen_statem:stop       -----> Module:terminate/2
+
+gen_statem:call
+gen_statem:cast
+erlang:send
+erlang:'!'            -----> Module:State/5
+                             Module:handle_event/5
+
+-                     -----> Module:terminate/3
+
+-                     -----> Module:code_change/3</pre>
+    <p>Events are of different
+      <seealso marker="#type-event_type">types</seealso>
+      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 gen_statem will terminate.  An exception of class
+      <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+      however, is not regarded as an error but as a valid return.
+    </p>
+    <marker id="state_function" />
+    <p>The "<em>state function</em>" for a specific
+      <seealso marker="#type-state">state</seealso>
+      in a gen_statem is the callback function that is called
+      for all events in this state.
+      An event can can be postponed causing it to be retried
+      after the state has changed, or more precisely;
+      after a state change all postponed events are retried
+      in the new state.
+    </p>
+    <p>The state machine
+      <seealso marker="#type-state"><c>State</c></seealso>
+      is normally an atom in which case the
+      <seealso marker="#state_function">state function</seealso>
+      that will be called is
+      <seealso marker="#Module:State/5"><c>Module:State/5</c></seealso>.
+      For a
+      <seealso marker="#type-state"><c>State</c></seealso>
+      that is <em>not</em> an atom the
+      <seealso marker="#state_function">state function</seealso>
+      <seealso marker="#Module:handle_event/5">
+	<c>Module:handle_event/5</c>
+      </seealso> will be called.
+      If you use <c>handle_event</c> as a
+      <seealso marker="#type-state">state</seealso> and later
+      decides to use non-atom states you will then have to
+      rewrite your code to stop using that state.
+    </p>
+    <p>When the using an atom-only
+      <seealso marker="#type-state">State</seealso>
+      it becomes fairly obvious in the implementation code
+      which events are handled in which state
+      since there are different callback functions for different states.
+    </p>
+    <p>
+      When using a non-atom <seealso marker="#type-state">State</seealso>
+      all events are handled in the callback function
+      <seealso marker="#Module:handle_event/5">
+	<c>Module:handle_event/5</c>
+      </seealso>
+      so it may require more coding discipline to ensure what events
+      are handled in which state.  Therefore it might be a wee bit
+      easier to accidentally postpone an event in two or more states
+      and not handling it in any of them causing a tight infinite
+      loop when the event bounces to be retried between the states.
+    </p>
+    <p>A gen_statem handles system messages as documented in
+       <seealso marker="sys">sys</seealso>.
+       The <seealso marker="sys">sys</seealso> module
+       can be used for debugging a gen_statem.
+    </p>
+    <p>Note that a gen_statem does not trap exit signals automatically,
+      this must be explicitly initiated by the callback module.
+    </p>
+    <p>Unless otherwise stated, all functions in this module fail if
+      the specified gen_statem does not exist or if bad arguments are given.
+    </p>
+    <p>The gen_statem process can go into hibernation (see
+      <seealso marker="erts:erlang#hibernate/3">
+	<c>erlang:hibernate/3</c>
+      </seealso>) if a
+      <seealso marker="#state_function">state function</seealso> or
+      <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+      specifies <c>'hibernate'</c> in the returned
+      <seealso marker="#type-state_op"><c>StateOps</c></seealso> list.
+      This might be useful if the server is expected to be idle
+      for a long time. However use this feature with care
+      since hibernation implies at least two garbage collections
+      (when hibernating and shortly after waking up) and that is not
+      something you'd want to do between each event on a busy server.
+    </p>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name name="server_name" />
+      <desc>
+	<p>Name specification to use when starting a gen_statem server.
+	  See <seealso marker="#start_link/3">
+	    <c>start_link/3</c>
+	  </seealso> and
+	  <seealso marker="#type-server_ref">
+	    <c>server_ref()</c>
+	  </seealso> below.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="server_ref" />
+      <desc>
+	<p>Server specification to use when addressing a gen_statem server.
+	  See <seealso marker="#call/2">call/2</seealso> and
+	  <seealso marker="#type-server_name">
+	    <c>server_name()</c>
+	  </seealso> above.
+	</p>
+	<p>It can be:</p>
+	<list type="bulleted">
+          <item>the <c>pid()</c>,</item>
+          <item><c><anno>Name</anno></c>,
+	    if the gen_statem is locally registered,
+	  </item>
+          <item><c>{<anno>Name</anno>,<anno>Node</anno>}</c>,
+	    if the gen_statem is locally registered at another node, or
+	  </item>
+          <item><c>{global,<anno>GlobalName</anno>}</c>,
+	    if the gen_statem is globally registered.
+	  </item>
+          <item><c>{via,<anno>RegMod</anno>,<anno>ViaName</anno>}</c>,
+	    if the gen_statem is registered through
+	    an alternative process registry.
+	    The registry callback module <c>RegMod</c>
+	    should export the functions
+	    <c>register_name/2</c>, <c>unregister_name/1</c>,
+	    <c>whereis_name/1</c> and <c>send/2</c>,
+	    which should behave like the corresponding functions
+	    in <seealso marker="kernel:global"><c>global</c></seealso>.
+	    Thus, <c>{via,global,GlobalName}</c> is the same as
+	    <c>{global,GlobalName}</c>.
+	  </item>
+        </list>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="debug_opt" />
+      <desc>
+	<p>Debug option that can be used when starting
+	  a gen_statem server through for example
+	  <seealso marker="#enter_loop/4">enter_loop/4</seealso>.
+	</p>
+	<p>For every entry in <c><anno>Dbgs</anno></c>
+	  the corresponding function in
+	  <seealso marker="sys"><c>sys</c></seealso> will be called.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="start_opt" />
+      <desc>
+	<p>Options that can be used when starting
+	  a gen_statem server through for example
+	  <seealso marker="#start_link/3">start_link/3</seealso>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="start_ret" />
+      <desc>
+	<p>Return value from the start functions for_example
+	  <seealso marker="#start_link/3">start_link/3</seealso>.
+	</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="client" />
+      <desc>
+	<p>Client address to use when replying through for example the
+	  <seealso marker="#type-state_op">state_op()</seealso>
+	  <c>{reply,Client,Reply}</c> to a client
+	  that has called the gen_statem server using
+	  <seealso marker="#call/2">call/2</seealso>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="state" />
+      <desc>
+	<p>If the gen_statem <c>State</c> is an <c>atom()</c>, the
+	  <seealso marker="#state_function">state function</seealso> is
+	  <seealso marker="#Module:State/5">Module:State/5</seealso>.
+	  If it is any other <c>term()</c> the
+	  <seealso marker="#state_function">state function</seealso> is
+	  <seealso marker="#Module:handle_event/5">
+	    Module:handle_event/5
+	  </seealso>.  After a state change (<c>NewState =/= State</c>)
+	  all postponed events are retried.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="state_data" />
+      <desc>
+	<p>A <c>term()</c> in which the state machine implementation
+	  should store any state data it needs.  The difference between
+	  this data and the
+	  <seealso marker="#type-state">state()</seealso>
+	  itself is that a change in this data does not cause
+	  postponed events to be retried.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="event_type" />
+      <desc>
+	<p>External events are of 3 different type:
+	  <c>{call,<anno>Client</anno>}</c>, <c>cast</c> or <c>info</c>.
+	  Calls (synchronous) and casts (asynchronous)
+	  originate from the corresponding API functions.
+	  For calls the event contain whom to reply to.
+	  Type <c>info</c> originates from normal messages sent
+	  to the gen_statem process.
+	  It is also possible for the state machine
+	  implementation to insert events to itself,
+	  in particular of types
+	  <c>timeout</c> and <c>internal</c>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="event_predicate" />
+      <desc>
+	<p>A <c>fun()</c> of arity 2 that takes an event
+	  and returns a boolean.
+	  When used in <c>{remove_event,RemoveEventPredicate}</c>
+	  from <seealso marker="#type-state_op">state_op()</seealso>.
+	  The event for which the predicate returns <c>true</c> will
+	  be removed.
+	</p>
+	<p>
+	  The predicate may <em>not</em> use a throw exception
+	  to return its result.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="state_op" />
+      <desc>
+	<p>Either a
+	  <seealso marker="#type-state_option">
+	    <c>state_option()</c>
+	  </seealso> of which the first occurence
+	  in the containing list takes precedence, or a
+	  <seealso marker="#type-state_operation">
+	    <c>state_operation()</c>
+	  </seealso> that are performed in order of
+	  the containing list.
+	</p>
+	<p>These may be returned from the
+	  <seealso marker="#state_function">state function</seealso>
+	  or from <seealso marker="#Module:init/1">Module:init/1</seealso>.
+	</p>
+	<p>The gen_statem enqueues postponed events and
+	  not yet processed events in order of arrival, except for
+	  an event that a callback function inserts with
+	  <c>{insert_event,EventType,EventContent}</c> that is inserted
+	  as the next event to process.
+	</p>
+	<p>When the state machine changes states all enqueued events
+	  becomes not yet processed to be processed before the old
+	  not yet processed events.  In other words; the order of arrival
+	  is retained.
+	</p>
+	<p>The processing order is:</p>
+	<list type="ordered">
+	  <item>If the option <c>retry</c> is <c>true</c>
+	    the current event is enqueued as postponed to be retried.
+	  </item>
+	  <item>If the state changes all postponed events
+	    are transferred to not yet processed to be processed
+	    before other not yet processed events.
+	  </item>
+	  <item>All operations are processed in order of appearance.
+	  </item>
+	  <item>The <c>timeout</c> option is processed if present.
+	    So a state timer may be started or a timeout zero event
+	    may be inserted as if just received.
+	  </item>
+	  <item>The (possibly new)
+	    <seealso marker="#state_function">state function</seealso>
+	    is called with the next not yet processed event
+	    if there is any, otherwise the gen_statem goes into <c>receive</c>
+	    or hibernation (if the option <c>hibernate</c> is <c>true</c>)
+	    to wait for the next message.  In hibernation the next
+	    non-system event awakens the gen_statem.
+	  </item>
+	</list>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="state_option" />
+      <desc>
+	<taglist>
+	  <tag><c>retry</c></tag>
+	  <tag><c>{retry,<anno>Retry</anno>}</c></tag>
+	  <item>If <c><anno>Retry</anno> =:= true</c>
+	    or plain <c>retry</c> postpone the current event
+	    to be retried after a state change.
+	  </item>
+	  <tag><c>hibernate</c></tag>
+	  <tag><c>{hibernate,<anno>Hibernate</anno>}</c></tag>
+	  <item>If <c><anno>Hibernate</anno> =:= true</c>
+	    or plain <c>hibernate</c> hibernate the gen_statem by calling
+	    <seealso marker="proc_lib#hibernate/3">
+	      <c>proc_lib:hibernate/3</c>
+	    </seealso> before <c>receive</c> to wait for a new event.
+	    If there are not yet processed events the
+	    <c>hibernate</c> operation is ignored as if an event
+	    just arrived and awakened the gen_statem.
+	  </item>
+	  <tag>
+	    <c>{timeout,<anno>Time</anno>,<anno>Msg</anno>}</c>
+	  </tag>
+	  <item>Generate an event of
+	    <seealso marker="#type-event_type">type <c>timeout</c></seealso>
+	    after <c><anno>Time</anno></c> milliseconds unless some other
+	    event is received before that time.  Note that a retried
+	    event counts just like a new in this respect.
+	    If <c>Time =:= infinity</c> or <c>Time =:= 0</c>
+	    no timer is started but for zero time the timeout
+	    event is enqued as just received after all
+	    other already received events.
+	    Also note that it is not possible
+	    to cancel this timeout using the
+	    <seealso marker="#type-state_operation">
+	      <c>state_operation()</c>
+	    </seealso> <c>cancel_timer</c>.
+	    This timeout is cancelled automatically by any event.
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="state_operation" />
+      <desc>
+	<taglist>
+	  <tag>
+	   <c>{reply,<anno>Client</anno>,<anno>Reply</anno>}</c>
+	  </tag>
+	  <item>Reply to a client that called
+	    <seealso marker="#call/2"><c>call/2</c></seealso>.
+            <c><anno>Client</anno></c> must be the term from the
+	    <seealso marker="#type-event_type">
+	      <c>{call,<anno>Client</anno>}</c>
+	    </seealso> argument to the
+	    <seealso marker="#state_function">state function</seealso>.
+	  </item>
+	  <tag><c>{stop,<anno>Reason</anno>}</c></tag>
+	  <item>The gen_statem will call
+	    <seealso marker="#Module:terminate/3">
+	      <c>Module:terminate/3</c>
+	    </seealso> with <c><anno>Reason</anno></c> and terminate.
+	  </item>
+	  <tag>
+	    <c>
+	      {insert_event,<anno>EventType</anno>,<anno>EventContent</anno>}
+	    </c>
+	  </tag>
+	  <item>Insert the given event as the next to process
+	    before any other not yet processed events.
+	    An event of type
+	    <seealso marker="#type-event_type">
+	      <c>internal</c>
+	    </seealso> should be used when you want to reliably distinguish
+	    an event inserted this way from any external event.
+	  </item>
+	  <tag>
+	    <c>
+	      {remove_event,<anno>EventType</anno>,<anno>EventContent</anno>}
+	    </c>
+	  </tag>
+	  <item>Remove the oldest queued event
+	    that matches equal to the given event.
+	  </item>
+	  <tag>
+	    <c>
+	      {remove_event,<anno>EventPredicate</anno>}
+	    </c>
+	  </tag>
+	  <item>Remove the oldest queued event for which
+	  the <c><anno>EventPredicate</anno></c> returns <c>true</c>.
+	  </item>
+	  <tag><c>{cancel_timer,<anno>TimerRef</anno>}</c></tag>
+	  <item>Uses <c><anno>TimerRef</anno></c> when calling
+	    <seealso marker="erts:erlang#cancel_timer/2">
+	      <c>erlang:cancel_timer/2</c>
+	    </seealso> to cancel a timer, cleans the gen_statem's
+	    message queue from any late timeout message from
+	    the timer, and removes any late timeout message
+	    from the queued events using
+	    <c>{remove_event,<anno>EventPredicate</anno>}</c> above.
+	    This is a convenience function that saves quite some
+	    lines of code and testing time over doing it from
+	    the primitives mentioned above.
+	  </item>
+	  <tag><c>{demonitor,<anno>MonitorRef</anno>}</c></tag>
+	  <item>Like <c>{cancel_timer,_}</c> above but for
+	    <seealso marker="erts:erlang#demonitor/2">
+	      <c>demonitor/2</c>
+	    </seealso>.
+	  </item>
+	  <tag><c>{unlink,<anno>Id</anno>}</c></tag>
+	  <item>Like <c>{cancel_timer,_}</c> above but for
+	    <seealso marker="erts:erlang#unlink/1">
+	      <c>unlink/1</c>
+	    </seealso>.
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
+  </datatypes>
+
+  <funcs>
+
+    <func>
+      <name name="start_link" arity="3" />
+      <name name="start_link" arity="4" />
+      <fsummary>Create a linked gen_statem process</fsummary>
+      <desc>
+        <p>Creates a gen_statem process according to OTP design principles
+	  (using
+          <seealso marker="proc_lib"><c>proc_lib</c></seealso>
+	  primitives)
+	  that is linked to the calling process.
+	  This is essential when the gen_statem shall be part of
+	  a supervision tree so it gets linked to its supervisor.
+	</p>
+        <p>The gen_statem process calls
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+	  to initialize the server. To ensure a synchronized start-up
+	  procedure, <c>start_link/3,4</c> does not return until
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+          has returned.
+	</p>
+	<p><c><anno>ServerName</anno></c> specifies the
+	  <seealso marker="#type-server_name">
+	    <c>server_name()</c>
+	  </seealso> to register for the gen_statem.
+	  If the gen_statem is started with  <c>start_link/3</c>
+	  no <c><anno>ServerName</anno></c> is provided and
+	  the gen_statem 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 which is passed as
+          the argument to
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c>
+	  </seealso>.
+	</p>
+        <p>If the option <c>{timeout,Time}</c> is present in
+	  <c><anno>Options</anno></c>, the gen_statem is allowed to spend
+	  <c>Time</c> milliseconds initializing or it will be
+	  terminated and the start function will return
+	  <seealso marker="#type-start_ret">
+	    <c>{error,timeout}</c>
+	  </seealso>.
+	</p>
+        <p>If the option
+	  <seealso marker="#type-debug_opt"><c>{debug,Dbgs}</c></seealso>
+	  is present in <c><anno>Options</anno></c>, debugging through
+	  <seealso marker="sys"><c>sys</c></seealso> is activated.
+	</p>
+        <p>If the option <c>{spawn_opt,SOpts}</c> is present in
+	  <c><anno>Options</anno></c>, <c>SOpts</c> will be passed
+	  as option list to the <c>spawn_opt</c> BIF
+	  which is used to
+          <seealso marker="erts:erlang#spawn_opt/2">spawn</seealso>
+	  the gen_statem.
+	</p>
+        <note>
+          <p>Using the spawn option <c>monitor</c> is currently not
+            allowed, but will cause this function to fail with reason
+            <c>badarg</c>.</p>
+        </note>
+        <p>If the gen_statem is successfully created and initialized
+          this function returns
+	  <seealso marker="#type-start_ret">
+	    <c>{ok,Pid}</c>,
+	  </seealso> where <c>Pid</c> is the <c>pid()</c> of the gen_statem.
+	  If there already exists a process with the specified
+	  <c><anno>ServerName</anno></c> this function returns
+	  <seealso marker="#type-start_ret">
+            <c>{error,{already_started,Pid}}</c>
+	  </seealso>, 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
+	  <seealso marker="#type-start_ret">
+	    <c>{error,Reason}</c>
+	  </seealso>. If <c>Module:init/1</c> returns
+	  <seealso marker="#type-start_ret">
+	    <c>{stop,Reason}</c>
+	  </seealso>
+	  or
+	  <seealso marker="#type-start_ret">
+            <c>ignore</c>
+	  </seealso>, the process is terminated and this function
+          returns
+	  <seealso marker="#type-start_ret">
+	    <c>{error,Reason}</c>
+	  </seealso> or
+	  <seealso marker="#type-start_ret">
+	  <c>ignore</c>
+	  </seealso>, respectively.
+	</p>
+      </desc>
+    </func>
+
+
+    <func>
+      <name name="start" arity="3" />
+      <name name="start" arity="4" />
+      <fsummary>Create a stand-alone gen_statem process</fsummary>
+      <desc>
+        <p>Creates a stand-alone gen_statem process according to
+	  OTP design principles (using
+          <seealso marker="proc_lib"><c>proc_lib</c></seealso>
+	  primitives).
+	  Since it does not get linked to the calling process
+	  this start function can not be used by a supervisor
+	  to start a child.
+	</p>
+        <p>See <seealso marker="#start_link/3">start_link/3,4</seealso>
+          for a description of arguments and return values.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="stop" arity="1" />
+      <fsummary>Synchronously stop a generic server</fsummary>
+      <desc>
+	<p>The same as
+	  <seealso marker="#stop/3">
+	    <c>stop(<anno>ServerRef</anno>, normal, infinity)</c>
+	  </seealso>.
+	</p>
+      </desc>
+    </func>
+    <func>
+      <name name="stop" arity="3" />
+      <fsummary>Synchronously stop a generic server</fsummary>
+      <desc>
+	<p>Orders the gen_statem
+	  <seealso marker="#type-server_ref">
+	    <c><anno>ServerRef</anno></c>
+	  </seealso> to exit with the given <c><anno>Reason</anno></c>
+	  and waits for it to terminate.
+	  The gen_statem will call
+          <seealso marker="#Module:terminate/3">
+	    Module:terminate/3
+	  </seealso> 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> will cause an
+          error report to be issued through
+          <seealso marker="kernel:error_logger#format/2">
+	    error_logger:format/2
+	  </seealso>.
+	  The default <c><anno>Reason</anno></c> is <c>normal</c>.
+	</p>
+	<p><c><anno>Timeout</anno></c> is an integer greater than zero
+	  which specifies how many milliseconds to wait for the server to
+          terminate, or the atom <c>infinity</c> to wait indefinitely.
+	  The default value is <c>infinity</c>.
+	  If the server has not terminated within the specified time,
+	  a <c>timeout</c> exception is raised.
+	</p>
+	<p>If the process does not exist, a <c>noproc</c> exception
+	  is raised.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="call" arity="2" />
+      <name name="call" arity="3" />
+      <fsummary>Make a synchronous call to a gen_statem</fsummary>
+      <desc>
+        <p>Makes a synchronous call to the gen_statem
+	  <seealso marker="#type-server_ref">
+	    <c><anno>ServerRef</anno></c>
+	  </seealso> by sending a request
+	  and waiting until its reply arrives.
+	  The gen_statem will call the
+	  <seealso marker="#state_function">state function</seealso> with
+	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
+	  <c>{call,Client}</c> and event content
+	  <c><anno>Request</anno></c>.
+	</p>
+	<p>A <c><anno>Reply</anno></c> is generated when a
+	  <seealso marker="#state_function">state function</seealso>
+	  returns with
+	  <c>{reply,Client,<anno>Reply</anno>}</c> as one
+	  <seealso marker="#type-state_op"><c>state_op()</c></seealso>,
+	  and that <c><anno>Reply</anno></c> becomes the return value
+	  of this function.
+	</p>
+        <p><c><anno>Timeout</anno></c> is an integer greater than zero
+	  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.
+	  <note>
+	    <p>To avoid getting a late reply in the caller's
+	      inbox this function spawns a proxy process that
+	      does the call.  A late reply gets delivered to the
+	      dead proxy process hence gets discarded.  This is
+	      less efficient than using
+	      <c><anno>Timeout</anno> =:= infinity</c>.
+	    </p>
+	  </note>
+	</p>
+        <p>The call may fail for example if the gen_statem dies
+	  before or during this function call.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="cast" arity="2" />
+      <fsummary>Send an asynchronous event to a gen_statem</fsummary>
+      <desc>
+	<p>Sends an asynchronous event to the gen_statem
+	  <seealso marker="#type-server_ref">
+	    <c><anno>ServerRef</anno></c>
+	  </seealso> and returns <c>ok</c> immediately,
+	  ignoring if the destination node or gen_statem does not exist.
+	  The gen_statem will call the
+	  <seealso marker="#state_function">state function</seealso> with
+	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
+	  <c>cast</c> and event content
+	  <c><anno>Msg</anno></c>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="reply" arity="2" />
+      <fsummary>Send a reply to a client</fsummary>
+      <desc>
+        <p>This function can be used by a gen_statem to explicitly send
+          a reply to a client that called
+	  <seealso marker="#call/2"><c>call/2</c></seealso>
+          when the reply cannot be defined in
+          the return value of the
+	  <seealso marker="#state_function">state function</seealso>.
+	</p>
+        <p><c><anno>Client</anno></c> must be the term from the
+	  <seealso marker="#type-event_type">
+	    <c>{call,<anno>Client</anno>}</c>
+	  </seealso> argument to the
+	  <seealso marker="#state_function">state function</seealso>.
+	</p>
+	<note>
+	  <p>A reply sent with this function will not be visible
+	    in <seealso marker="sys">sys</seealso> debug output.
+	  </p>
+	</note>
+      </desc>
+    </func>
+
+    <func>
+      <name name="enter_loop" arity="4" />
+      <fsummary>Enter the gen_statem receive loop</fsummary>
+      <desc>
+	<p>The same as
+	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
+	  except that no
+	  <seealso marker="#type-server_name">
+	    <c>server_name()</c>
+	  </seealso> must have been registered.
+	</p>
+      </desc>
+    </func>
+    <func>
+      <name name="enter_loop" arity="5" />
+      <fsummary>Enter the gen_statem receive loop</fsummary>
+      <desc>
+	<p>If <c><anno>Server_or_StateOps</anno></c> is a <c>list()</c>
+	  the same as
+	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
+	  except that no
+	  <seealso marker="#type-server_name">
+	    <c>server_name()</c>
+	  </seealso> must have been registered and
+	  <c>StateOps = <anno>Server_or_StateOps</anno></c>.
+	</p>
+	<p>Otherwise the same as
+	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
+	  with
+	  <c>Server = <anno>Server_or_StateOps</anno></c> and
+	  <c>StateOps = []</c>.
+	</p>
+      </desc>
+    </func>
+    <func>
+      <name name="enter_loop" arity="6" />
+      <fsummary>Enter the gen_statem receive loop</fsummary>
+      <desc>
+        <p>Makes an the calling process become a gen_statem. Does not return,
+          instead the calling process will enter the gen_statem receive
+          loop and become a gen_statem server. The process
+          <em>must</em> have been started using one of the start
+          functions in
+          <seealso marker="proc_lib"><c>proc_lib</c></seealso>.
+	  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 gen_statem behaviour provides.
+	</p>
+        <p><c><anno>Module</anno></c>, <c><anno>Options</anno></c> and
+	  <c><anno>Server</anno></c> have the same meanings
+	  as when calling
+          <seealso marker="#start_link/3">gen_statem:start[_link]/3,4</seealso>.
+          However, the
+	  <seealso marker="#type-server_name">
+	    <c>server_name()</c>
+	  </seealso> name must have been registered accordingly
+	  <em>before</em> this function is called.</p>
+        <p><c><anno>State</anno></c> and <c><anno>StateData</anno></c>
+	  have the same meanings as in the return value of
+          <seealso marker="#Module:init/1">Module:init/1</seealso>.
+          Also, the callback module <c><anno>Module</anno></c>
+	  does not need to export an <c>init/1</c> function.
+	</p>
+        <p>Failure: If the calling process was not started by a
+          <seealso marker="proc_lib"><c>proc_lib</c></seealso>
+	  start function, or if it is not registered
+          according to
+	  <seealso marker="#type-server_name">
+	    <c>server_name()</c>
+	  </seealso>.
+	</p>
+      </desc>
+    </func>
+
+  </funcs>
+
+
+
+  <section>
+    <title>CALLBACK FUNCTIONS</title>
+    <p>The following functions should be exported from a
+      <c>gen_statem</c> callback module.
+    </p>
+  </section>
+  <funcs>
+
+    <func>
+      <name>Module:init(Args) -> Result</name>
+      <fsummary>Initialize process and internal state</fsummary>
+      <type>
+        <v>Args = term()</v>
+        <v>Result = {ok,State,StateData}</v>
+	<v>&nbsp;| {ok,State,StateData,StateOps}</v>
+        <v>&nbsp;| {stop,Reason} | ignore</v>
+	<v>State = <seealso marker="#type-state">state()</seealso></v>
+	<v>StateData = <seealso marker="#type-state_data">state_data()</seealso></v>
+	<v>StateOps = [<seealso marker="#type-state_op">state_op()</seealso>]</v>
+	<v>Reason = term()</v>
+      </type>
+      <desc>
+	<marker id="Module:init-1" />
+        <p>Whenever a gen_statem is started using
+          <seealso marker="#start_link/3">gen_statem:start_link/3,4</seealso>
+	  or
+          <seealso marker="#start/3">gen_statem:start/3,4</seealso>,
+          this function is called by the new process to initialize
+	  the implementation loop data.
+	</p>
+        <p><c>Args</c> is the <c>Args</c> argument provided to the start
+          function.</p>
+        <p>If the initialization is successful, the function should
+          return <c>{ok,State,StateData}</c> or
+	  <c>{ok,State,StateData,StateOps}</c>.
+	  <c>State</c> is the <seealso marker="#type-state">state</seealso>
+	  of the gen_statem.
+	</p>
+	<p>The <seealso marker="#type-state_op"><c>StateOps</c></seealso>
+	  are executed before entering the first
+	  <seealso marker="#type-state">state</seealso> just as for a
+	  <seealso marker="#state_function">state function</seealso>.
+	</p>
+        <p>If something goes wrong during the initialization
+          the function should return <c>{stop,Reason}</c>
+	  or <c>ignore</c>. See
+          <seealso marker="#start_link/3">gen_statem:start_link/3,4</seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:handle_event(EventType, EventContent,
+        PrevState, State, StateData) -> Result
+      </name>
+      <name>Module:State(EventType, EventContent,
+        PrevState, State, StateData) -> Result
+      </name>
+      <fsummary>Handle an event</fsummary>
+      <type>
+	<v>EventType =
+	  <seealso marker="#type-event_type">event_type()</seealso>
+	</v>
+	<v>EventContent = term()</v>
+	<v>Result = {NewState,NewStateData,StateOps}</v>
+	<v>&nbsp;&nbsp;| {NewState,NewStateData}</v>
+	<d>&nbsp;&nbsp;The same as <c>{NewState,NewStateData,[]}</c></d>
+	<v>&nbsp;&nbsp;| {NewStateData}</v>
+	<d>&nbsp;&nbsp;The same as <c>{State,NewStateData,[retry]}</c></d>
+	<v>&nbsp;&nbsp;| {}</v>
+	<d>&nbsp;&nbsp;The same as <c>{State,StateData,[]}</c></d>
+	<v>&nbsp;&nbsp;| StateOps</v>
+	<d>&nbsp;&nbsp;The same as <c>{State,StateData,StateOps}</c></d>
+
+	<v>PrevState = State = NewState =
+	  <seealso marker="#type-state">state()</seealso>
+	</v>
+	<v>StateData = NewStateData =
+	  <seealso marker="#type-state_data">state_data()</seealso>
+	</v>
+	<v>StateOps =
+	  [<seealso marker="#type-state_op">state_op()</seealso>]
+	</v>
+      </type>
+      <desc>
+        <p>Whenever a gen_statem receives an event from
+          <seealso marker="#call/2">gen_statem:call/2</seealso>,
+          <seealso marker="#cast/2">gen_statem:cast/2</seealso> or
+	  as a normal process message this function is called.
+	  If the <c>EventType</c> is
+	  <seealso marker="#type-event_type"><c>{call,Client}</c></seealso>
+	  the client is waiting for a reply.  The reply can be sent
+	  from this or from any other
+	  <seealso marker="#state_function">state function</seealso>
+	  by returning with <c>{reply,Client,Reply}</c> in
+	  <seealso marker="#type-state_op">StateOps</seealso>
+	  or by calling
+	  <seealso marker="#reply/2">
+	    <c>gen_statem:reply(Client, Reply)</c>
+	  </seealso>.
+	</p>
+        <p><seealso marker="#type-state"><c>State</c></seealso>
+	  is the internal state of the gen_statem which
+	  when <c>State</c> is an <c>atom()</c>
+	  is the same as this function's name, so it is seldom useful,
+	  except for example when comparing with <c>PrevState</c>
+	  that is the gen_statem's previous state, or in
+	  <seealso marker="#Module:handle_event/5">
+	    Module:handle_event/5
+	  </seealso> since that function is common for all states
+	  that are not an <c>atom()</c>.
+	</p>
+	<p>If this function returns with
+	  <seealso marker="#type-state"><c>NewState =/= State</c></seealso>
+	  all postponed events will be retried in the new state.
+	</p>
+	<p>See <seealso marker="#type-state_op">state_op()</seealso>
+	  for the operations that can be done by gen_statem
+	  after returning from this function.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:terminate(Reason, State, StateData)</name>
+      <fsummary>Clean up before termination</fsummary>
+      <type>
+        <v>Reason = normal | shutdown | {shutdown,term()} | term()</v>
+	<v>State = <seealso marker="#type-state">state()</seealso></v>
+	<v>StateData =
+	  <seealso marker="#type-state_data">
+	    state_data()
+	  </seealso>
+	</v>
+      </type>
+      <desc>
+        <p>This function is called by a gen_statem when it is about to
+          terminate. It should be the opposite of
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+          and do any necessary cleaning up. When it returns,
+          the gen_statem terminates with <c>Reason</c>. The return
+          value is ignored.</p>
+        <p><c>Reason</c> is a term denoting the stop reason and
+          <seealso marker="#type-state">State</seealso>
+	  is the internal state of the gen_statem.
+	</p>
+        <p><c>Reason</c> depends on why the gen_statem is terminating.
+          If it is because another callback function has returned a
+          stop tuple <c>{stop,Reason}</c> in
+	  <seealso marker="#type-state_op">StateOps</seealso>,
+	  <c>Reason</c> will have the value specified in that tuple.
+	  If it is due to a failure, <c>Reason</c> is the error reason.
+	</p>
+        <p>If the gen_statem is part of a supervision tree and is
+          ordered by its supervisor to terminate, this function will be
+          called with <c>Reason = shutdown</c> if the following
+          conditions apply:</p>
+        <list type="bulleted">
+          <item>the gen_statem has been set to trap exit signals, and</item>
+          <item>the shutdown strategy as defined in the supervisor's
+            child specification is an integer timeout value, not
+            <c>brutal_kill</c>.
+	  </item>
+        </list>
+        <p>Even if the gen_statem is <em>not</em> part of a supervision tree,
+	   this function will be called if it receives an <c>'EXIT'</c>
+	   message from its parent. <c>Reason</c> will be the same as in
+	   the <c>'EXIT'</c> message.
+	</p>
+        <p>Otherwise, the gen_statem will be immediately terminated.
+	</p>
+        <p>Note that for any other reason than <c>normal</c>,
+          <c>shutdown</c>, or <c>{shutdown,Term}</c> the gen_statem is
+	  assumed to terminate due to an error and
+	  an error report is issued using
+          <seealso marker="kernel:error_logger#format/2">
+	    error_logger:format/2
+	  </seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:code_change(OldVsn, OldState, OldStateData, 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,NewStateData}} | Reason</v>
+	<v>OldState = NewState =
+	  <seealso marker="#type-state">state()</seealso>
+	</v>
+	<v>OldStateData = NewStateData =
+	  <seealso marker="#type-state_data">state_data()</seealso>
+	</v>
+	<v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>This function is called by a gen_statem when it should
+          update its internal state during a release upgrade/downgrade,
+          i.e. when the instruction <c>{update,Module,Change,...}</c>
+          where <c>Change={advanced,Extra}</c> is given in
+          the <c>appup</c> file. See
+          <seealso marker="doc/design_principles:release_handling#instr">
+	    OTP Design Principles
+	  </seealso>
+          for more information.
+	</p>
+        <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
+          in the case of 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>OldStateData</c> is the internal state
+	  of the gen_statem.
+	</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 shall return the updated
+          internal state in an
+	  <c>{ok,{NewState,NewStateData}}</c> tuple.
+	</p>
+	<p>If the function returns <c>Reason</c>, the ongoing
+	  upgrade will fail and roll back to the old release.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:format_status(Opt, [PDict,State,StateData]) ->
+        Status
+      </name>
+      <fsummary>Optional function for providing a term describing the
+        current gen_statem status</fsummary>
+      <type>
+        <v>Opt = normal | terminate</v>
+        <v>PDict = [{Key, Value}]</v>
+	<v>State =
+	  <seealso marker="#type-state">state()</seealso>
+	</v>
+	<v>StateData =
+	  <seealso marker="#type-state_data">state_data()</seealso>
+	</v>
+	<v>Key = term()</v>
+	<v>Value = term()</v>
+        <v>Status = term()</v>
+      </type>
+      <desc>
+        <note>
+          <p>This callback is optional, so callback modules need not
+            export it. The gen_statem module provides a default
+            implementation of this function that returns the callback
+            module state.
+	  </p>
+        </note>
+        <p>This function is called by a gen_statem process when:</p>
+        <list type="bulleted">
+          <item>One of
+            <seealso marker="sys#get_status/1">
+	      <c>sys:get_status/1,2</c>
+	    </seealso>
+            is invoked to get the gen_statem status. <c>Opt</c> is set
+            to the atom <c>normal</c> for this case.
+	  </item>
+          <item>The gen_statem 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 customising the form and
+          appearance of the gen_statem status for these cases. A
+          callback module wishing to customise the
+          <seealso marker="sys#get_status/1">
+	    <c>sys:get_status/1,2</c>
+	  </seealso> return value as well as how
+          its status appears in termination error logs exports an
+          instance of <c>format_status/2</c> that returns a term
+          describing the current status of the gen_statem.
+	</p>
+        <p><c>PDict</c> is the current value of the gen_statem's
+          process dictionary.
+	</p>
+        <p><seealso marker="#type-state"><c>State</c></seealso>
+	  is the internal state of the gen_statem.
+	</p>
+        <p>The function should return <c>Status</c>, a term that
+          customises the details of the current state and status of
+          the gen_statem. There are no restrictions on the
+          form <c>Status</c> can take, but for the
+          <seealso marker="sys#get_status/1">
+	    <c>sys:get_status/1,2</c>
+	    </seealso> 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 gen_statem state. Following this recommendation isn't
+          required, but doing so will make the callback module status
+          consistent with the rest of the
+          <seealso marker="sys#get_status/1">
+	    <c>sys:get_status/1,2</c>
+	  </seealso> return value.
+	</p>
+        <p>One use for this function is to return compact alternative
+          state representations to avoid having large state terms
+          printed in logfiles.
+	</p>
+      </desc>
+    </func>
+
+  </funcs>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p><seealso marker="gen_event">gen_event</seealso>,
+      <seealso marker="gen_fsm">gen_fsm</seealso>,
+      <seealso marker="gen_server">gen_server</seealso>,
+      <seealso marker="supervisor">supervisor</seealso>,
+      <seealso marker="proc_lib">proc_lib</seealso>,
+      <seealso marker="sys">sys</seealso></p>
+  </section>
+</erlref>
diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml
index 82ad78e675..404873ea32 100644
--- a/lib/stdlib/doc/src/ref_man.xml
+++ b/lib/stdlib/doc/src/ref_man.xml
@@ -4,7 +4,7 @@
 <application xmlns:xi="http://www.w3.org/2001/XInclude">
   <header>
     <copyright>
-      <year>1996</year><year>2015</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -66,6 +66,7 @@
   <xi:include href="gen_event.xml"/>
   <xi:include href="gen_fsm.xml"/>
   <xi:include href="gen_server.xml"/>
+  <xi:include href="gen_statem.xml"/>
   <xi:include href="io.xml"/>
   <xi:include href="io_lib.xml"/>
   <xi:include href="lib.xml"/>
diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml
index 0418bf7b22..45b207b13d 100644
--- a/lib/stdlib/doc/src/specs.xml
+++ b/lib/stdlib/doc/src/specs.xml
@@ -30,6 +30,7 @@
   <xi:include href="../specs/specs_gen_event.xml"/>
   <xi:include href="../specs/specs_gen_fsm.xml"/>
   <xi:include href="../specs/specs_gen_server.xml"/>
+  <xi:include href="../specs/specs_gen_statem.xml"/>
   <xi:include href="../specs/specs_io.xml"/>
   <xi:include href="../specs/specs_io_lib.xml"/>
   <xi:include href="../specs/specs_lib.xml"/>
diff --git a/lib/stdlib/src/Makefile b/lib/stdlib/src/Makefile
index 9f4a446ea0..302834f9d0 100644
--- a/lib/stdlib/src/Makefile
+++ b/lib/stdlib/src/Makefile
@@ -1,7 +1,7 @@
 #
 # %CopyrightBegin%
 #
-# Copyright Ericsson AB 1996-2015. All Rights Reserved.
+# Copyright Ericsson AB 1996-2016. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -85,6 +85,7 @@ MODULES= \
 	gen_event \
 	gen_fsm \
 	gen_server \
+	gen_statem \
 	io \
 	io_lib \
 	io_lib_format \
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
new file mode 100644
index 0000000000..9bb5ed013b
--- /dev/null
+++ b/lib/stdlib/src/gen_statem.erl
@@ -0,0 +1,1095 @@
+%%
+%% %CopyrightBegin%
+%%
+%% Copyright Ericsson AB 2016. All Rights Reserved.
+%%
+%% 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.
+%%
+%% %CopyrightEnd%
+%%
+-module(gen_statem).
+
+%% API
+-export(
+   [start/3,start/4,start_link/3,start_link/4,
+    stop/1,stop/3,
+    cast/2,call/2,call/3,
+    enter_loop/4,enter_loop/5,enter_loop/6,
+    reply/2]).
+
+%% gen callbacks
+-export(
+   [init_it/6]).
+
+%% sys callbacks
+-export(
+   [system_continue/3,
+    system_terminate/4,
+    system_code_change/4,
+    system_get_state/1,
+    system_replace_state/2,
+    format_status/2]).
+
+%% Internal callbacks
+-export(
+   [wakeup_from_hibernate/3]).
+
+%%%==========================================================================
+%%% Interface functions.
+%%%==========================================================================
+
+-type client() ::
+	{To :: pid(), Tag :: term()}. % Reply-to specifier for call
+-type state() ::
+	atom() | % Calls state callback function State/5
+	term(). % Calls state callback function handle_event/5
+-type state_data() :: term().
+-type event_type() ::
+	{'call',Client :: client()} | 'cast' |
+	'info' | 'timeout' | 'internal'.
+-type event_predicate() :: % Return true for the event in question
+	fun((event_type(), term()) -> boolean()).
+-type state_op() ::
+	%% First NewState and NewStateData are set,
+	%% then all state_operations() are executed in order of
+	%% apperance. Postponing the current event is performed
+	%% (iff state_option() 'retry' is 'true').
+	%% Lastly pending events are processed or if there are
+	%% no pending events the server goes into receive
+	%% or hibernate (iff state_option() 'hibernate' is 'true')
+	state_option() | state_operation().
+-type state_option() ::
+	%% The first of each kind in the state_op() list takes precedence
+	'retry' |  % Postpone the current event to a different (=/=) state
+	{'retry', Retry :: boolean()} |
+	'hibernate' | % Hibernate the server instead of going into receive
+	{'hibernate', Hibernate :: boolean()} |
+	{'timeout', % Generate a ('timeout', Msg, ...) event after Time
+	 Time :: timeout(), Msg :: term()}.
+-type state_operation() ::
+	%% These can occur multiple times and are executed in order
+	%% of appearence in the state_op() list
+	{'reply', % Reply to a client
+	 Client :: client(), Reply :: term()} |
+	{'stop', Reason :: term()} | % Stop the server
+	{'insert_event', % Insert event as the next to handle
+	 EventType :: event_type(),
+	 EventContent :: term()} |
+	{'remove_event', % Remove the oldest matching (=:=) event
+	 EventType :: event_type(), EventContent :: term()} |
+	{'remove_event', % Remove the oldest event satisfying predicate
+	 EventPredicate :: event_predicate()} |
+	{'cancel_timer', % Cancel timer and clean up mess(ages)
+	 TimerRef :: reference()} |
+	{'demonitor', % Demonitor and clean up mess(ages)
+	 MonitorRef :: reference()} |
+	{'unlink', % Unlink and clean up mess(ages)
+	 Id :: pid() | port()}.
+
+%% The state machine init function.  It is called only once and
+%% the server is not running until this function has returned
+%% an {ok, ...} tuple.  Thereafter the state callbacks are called
+%% for all events to this server.
+-callback init(Args :: term()) ->
+    {'ok', state(), state_data()} |
+    {'ok', state(), state_data(), [state_op()]} |
+    'ignore' |
+    {'stop', Reason :: term()}.
+
+%% An example callback for a fictive state 'handle_event'
+%% that you should avoid having. See below.
+%%
+%% Note that state callbacks and only state callbacks have arity 5
+%% and that is intended.
+%%
+%% You should not actually use 'handle_event' as a state name,
+%% since it is the callback function that is used if you would use
+%% a State that is not an atom().  This is because since there is
+%% no obvious way to decide on a state function name from any term().
+-callback handle_event(
+	    event_type(),
+	    EventContent :: term(),
+	    PrevState :: state(),
+	    State :: state(), % Current state
+	    StateData :: state_data()) ->
+    [state_op()] | % {State,StateData,[state_op()]}
+    {} | % {State,StateData,[]}
+    {NewStateData :: state_data()} | % {State,NewStateData,[retry]}
+    {NewState :: state(),
+     NewStateData :: state_data()} | % {NewState,NewStateData,[]}
+    {NewState :: state(), NewStateData :: state_data(), [state_op()]}.
+
+%% Clean up before the server terminates.
+-callback terminate(
+	    Reason :: 'normal' | 'shutdown' | {'shutdown', term()}
+		    | term(),
+	    State :: state(),
+	    StateData :: state_data()) ->
+    any().
+
+%% Note that the new code can expect to get an OldState from
+%% the old code version not only in code_change/4 but in the first
+%% state callback function called thereafter
+-callback code_change(
+	    OldVsn :: term() | {'down', term()},
+	    OldState :: state(),
+	    OldStateData :: state_data(),
+	    Extra :: term()) ->
+    {ok, {NewState :: state(), NewStateData :: state_data()}}.
+
+%% Format the callback module state in some sensible that is
+%% often condensed way.  For StatusOption =:= 'normal' the perferred
+%% return term is [{data,[{"State",FormattedState}]}], and for
+%% StatusOption =:= 'terminate' it is just FormattedState.
+-callback format_status(
+	    StatusOption,
+	    [ [{Key :: term(), Value :: term()}] |
+	      state() |
+	      state_data()]) ->
+    Status :: term() when
+      StatusOption :: 'normal' | 'terminate'.
+
+-optional_callbacks(
+   [format_status/2, % Has got a default implementation
+    handle_event/5]). % Only needed for State not an atom()
+%%  For every atom() State there has to be a State/5 callback function
+
+%% Type validation functions
+client({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
+    true;
+client(_) ->
+    false.
+%%
+event_type({call,Client}) ->
+    client(Client);
+event_type(Type) ->
+    case Type of
+	cast ->
+	    true;
+	info ->
+	    true;
+	timeout ->
+	    true;
+	internal ->
+	    true;
+	_ ->
+	    false
+    end.
+
+%%%==========================================================================
+%%% API
+
+-type server_name() ::
+      {'global', GlobalName :: term()}
+      | {'via', RegMod :: module(), Name :: term()}
+      | {'local', atom()}.
+-type server_ref() ::
+      {'global', GlobalName :: term()}
+      | {'via', RegMod :: module(), ViaName :: term()}
+      | (LocalName :: atom())
+      | {Name :: atom(), Node :: atom()}
+      | pid().
+-type debug_opt() ::
+	{'debug',
+	 Dbgs ::
+	   ['trace' | 'log' | 'statistics' | 'debug'
+	    | {'logfile', string()}]}.
+-type start_opt() ::
+	debug_opt()
+      | {'timeout', Time :: timeout()}
+      | {'spawn_opt', SOpts :: [proc_lib:spawn_option()]}.
+-type start_ret() ::  {'ok', pid()} | 'ignore' | {'error', term()}.
+
+
+
+%% Start a state machine
+-spec start(
+	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+		   start_ret().
+start(Module, Args, Options) ->
+    gen:start(?MODULE, nolink, Module, Args, Options).
+%%
+-spec start(
+	ServerName :: server_name(),
+	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+		   start_ret().
+start(ServerName, Module, Args, Options) ->
+    gen:start(?MODULE, nolink, ServerName, Module, Args, Options).
+
+%% Start and link to a state machine
+-spec start_link(
+	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+		   start_ret().
+start_link(Module, Args, Options) ->
+    gen:start(?MODULE, link, Module, Args, Options).
+%%
+-spec start_link(
+	ServerName :: server_name(),
+	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+		   start_ret().
+start_link(ServerName, Module, Args, Options) ->
+    gen:start(?MODULE, link, ServerName, Module, Args, Options).
+
+%% Stop a state machine
+-spec stop(ServerRef :: server_ref()) -> ok.
+stop(ServerRef) ->
+    gen:stop(ServerRef).
+%%
+-spec stop(
+	ServerRef :: server_ref(),
+	Reason :: term(),
+	Timeout :: timeout()) -> ok.
+stop(ServerRef, Reason, Timeout) ->
+    gen:stop(ServerRef, Reason, Timeout).
+
+%% Send an event to a state machine that arrives with type 'event'
+-spec cast(ServerRef :: server_ref(), Msg :: term()) -> ok.
+cast({global,Name}, Msg) ->
+    try	global:send(Name, cast(Msg)) of
+	_ -> ok
+    catch
+	_:_ -> ok
+    end;
+cast({via,RegMod,Name}, Msg) ->
+    try	RegMod:send(Name, cast(Msg)) of
+	_ -> ok
+    catch
+	_:_ -> ok
+    end;
+cast({Name,Node} = ServerRef, Msg) when is_atom(Name), is_atom(Node) ->
+    do_send(ServerRef, cast(Msg));
+cast(ServerRef, Msg) when is_atom(ServerRef) ->
+    do_send(ServerRef, cast(Msg));
+cast(ServerRef, Msg) when is_pid(ServerRef) ->
+    do_send(ServerRef, cast(Msg)).
+
+%% Call a state machine (synchronous; a reply is expected) that
+%% arrives with type {call,Client}
+-spec call(ServerRef :: server_ref(), Request :: term()) -> Reply :: term().
+call(ServerRef, Request) ->
+    call(ServerRef, Request, infinity).
+%%
+-spec call(
+	ServerRef :: server_ref(),
+	Request :: term(),
+	Timeout :: timeout()) ->
+		  Reply :: term().
+call(ServerRef, Request, infinity) ->
+    try gen:call(ServerRef, '$gen_call', Request, infinity) of
+	{ok,Reply} ->
+	    Reply
+    catch
+	Class:Reason ->
+	    erlang:raise(
+	      Class,
+	      {Reason,{?MODULE,call,[ServerRef,Request,infinity]}},
+	      erlang:get_stacktrace())
+    end;
+call(ServerRef, Request, Timeout) ->
+    %% Call server through proxy process to dodge any late reply
+    Ref = make_ref(),
+    Self = self(),
+    Pid = spawn(
+	    fun () ->
+		    Self !
+			try gen:call(
+			      ServerRef, '$gen_call', Request, Timeout) of
+			    Result ->
+				{Ref,Result}
+			catch Class:Reason ->
+				{Ref,Class,Reason,erlang:get_stacktrace()}
+			end
+	    end),
+    Mref = monitor(process, Pid),
+    receive
+	{Ref,Result} ->
+	    demonitor(Mref, [flush]),
+	    case Result of
+		{ok,Reply} ->
+		    Reply
+	    end;
+	{Ref,Class,Reason,Stacktrace} ->
+	    demonitor(Mref, [flush]),
+	    erlang:raise(
+	      Class,
+	      {Reason,{?MODULE,call,[ServerRef,Request,Timeout]}},
+	      Stacktrace);
+	{'DOWN',Mref,_,_,Reason} ->
+	    %% There is just a theoretical possibility that the
+	    %% proxy process gets killed between try--of and !
+	    %% so this clause is in case of that
+	    exit(Reason)
+    end.
+
+%% Reply from a state machine callback to whom awaits in call/2
+-spec reply(Client :: client(), Reply :: term()) -> ok.
+reply({To,Tag}, Reply) ->
+    Msg = {Tag,Reply},
+    try To ! Msg of
+	_ ->
+	    ok
+    catch
+	_:_ -> ok
+    end.
+
+%% Instead of starting the state machine through start/3,4
+%% or start_link/3,4 turn the current process presumably
+%% started by proc_lib into a state machine using
+%% the same arguments as you would have returned from init/1
+-spec enter_loop(
+	Module :: module(), Options :: [debug_opt()],
+	State :: state(), StateData :: state_data()) ->
+			no_return().
+enter_loop(Module, Options, State, StateData) ->
+    enter_loop(Module, Options, State, StateData, self()).
+%%
+-spec enter_loop(
+	Module :: module(), Options :: [debug_opt()],
+	State :: state(), StateData :: state_data(),
+	Server_or_StateOps :: server_name() | pid() | [state_op()]) ->
+			no_return().
+enter_loop(Module, Options, State, StateData, Server_or_StateOps) ->
+    if
+	is_list(Server_or_StateOps) ->
+	    enter_loop(
+	      Module, Options, State, StateData,
+	      self(), Server_or_StateOps);
+	true ->
+	    enter_loop(
+	      Module, Options, State, StateData,
+	      Server_or_StateOps, [])
+    end.
+%%
+-spec enter_loop(
+	Module :: module(), Options :: [debug_opt()],
+	State :: state(), StateData :: state_data(),
+	Server :: server_name() | pid(),
+	StateOps :: [state_op()]) ->
+			no_return().
+enter_loop(Module, Options, State, StateData, Server, StateOps) ->
+    Parent = gen:get_parent(),
+    enter(Module, Options, State, StateData, Server, StateOps, Parent).
+
+%%---------------------------------------------------------------------------
+%% API helpers
+
+cast(Event) ->
+    {'$gen_cast',Event}.
+
+%% Might actually not send the message in case of caught exception
+do_send(Proc, Msg) ->
+    try erlang:send(Proc, Msg, [noconnect]) of
+	noconnect ->
+	    _ = spawn(erlang, send, [Proc,Msg]),
+	    ok;
+	ok ->
+	    ok
+    catch
+	_:_ ->
+	    ok
+    end.
+
+%% Here init_it and all enter_loop functions converge
+enter(Module, Options, State, StateData, Server, StateOps, Parent) ->
+    Name = gen:get_proc_name(Server),
+    Debug = gen:debug_options(Name, Options),
+    PrevState = make_ref(),
+    S = #{
+      module => Module,
+      name => Name,
+      prev_state => PrevState,
+      state => PrevState,
+      state_data => StateData,
+      timer => undefined,
+      postponed => [],
+      hibernate => false},
+    loop_event_state_ops(
+      Parent, Debug, S, [], {event,undefined},
+      State, StateData, [{retry,false}|StateOps]).
+
+%%%==========================================================================
+%%%  gen callbacks
+
+init_it(Starter, Parent, ServerRef, Module, Args, Options) ->
+    try Module:init(Args) of
+	Result ->
+	    init_result(Starter, Parent, ServerRef, Module, Result, Options)
+    catch
+	Result ->
+	    init_result(Starter, Parent, ServerRef, Module, Result, Options);
+	Class:Reason ->
+	    gen:unregister_name(ServerRef),
+	    proc_lib:init_ack(Starter, {error,Reason}),
+	    erlang:raise(Class, Reason, erlang:get_stacktrace())
+    end.
+
+%%---------------------------------------------------------------------------
+%% gen callbacks helpers
+
+init_result(Starter, Parent, ServerRef, Module, Result, Options) ->
+    case Result of
+	{ok,State,StateData} ->
+	    proc_lib:init_ack(Starter, {ok,self()}),
+	    enter(
+	      Module, Options, State, StateData, ServerRef,
+	      [], Parent);
+	{ok,State,StateData,StateOps} ->
+	    proc_lib:init_ack(Starter, {ok,self()}),
+	    enter(
+	      Module, Options, State, StateData, ServerRef,
+	      StateOps, Parent);
+	{stop,Reason} ->
+	    gen:unregister_name(ServerRef),
+	    proc_lib:init_ack(Starter, {error,Reason}),
+	    exit(Reason);
+	ignore ->
+	    gen:unregister_name(ServerRef),
+	    proc_lib:init_ack(Starter, ignore),
+	    exit(normal);
+	Other ->
+	    Error = {bad_return_value,Other},
+	    proc_lib:init_ack(Starter, {error,Error}),
+	    exit(Error)
+    end.
+
+%%%==========================================================================
+%%% sys callbacks
+
+system_continue(Parent, Debug, S) ->
+    loop(Parent, Debug, S).
+
+system_terminate(Reason, _Parent, Debug, S) ->
+    terminate(Reason, Debug, S, []).
+
+system_code_change(
+  #{module := Module,
+    state := State,
+    state_data := StateData} = S,
+  _Mod, OldVsn, Extra) ->
+    case
+	try Module:code_change(OldVsn, State, StateData, Extra)
+	catch
+	    Result -> Result
+	end
+    of
+	{ok,{NewState,NewStateData}} ->
+	    {ok,
+	     S#{
+	       state := NewState,
+	       state_data := NewStateData}};
+	Error ->
+	    Error
+    end.
+
+system_get_state(#{state := State, state_data := StateData}) ->
+    {ok,{State,StateData}}.
+
+system_replace_state(
+  StateFun,
+  #{state := State,
+    state_data := StateData} = S) ->
+    {NewState,NewStateData} = Result = StateFun({State,StateData}),
+    {ok,Result,S#{state := NewState, state_data := NewStateData}}.
+
+format_status(
+  Opt,
+  [PDict,SysState,Parent,Debug,
+   #{name := Name, postponed := P} = S]) ->
+    Header = gen:format_status_header("Status for state machine", Name),
+    Log = sys:get_debug(log, Debug, []),
+    [{header,Header},
+     {data,
+      [{"Status",SysState},
+       {"Parent",Parent},
+       {"Logged Events",Log},
+       {"Postponed",P}]} |
+     case format_status(Opt, PDict, S) of
+	 L when is_list(L) -> L;
+	 T -> [T]
+     end].
+
+%%---------------------------------------------------------------------------
+%% Format debug messages.  Print them as the call-back module sees
+%% them, not as the real erlang messages.  Use trace for that.
+%%---------------------------------------------------------------------------
+
+print_event(Dev, {in,Event}, #{name := Name}) ->
+    io:format(
+      Dev, "*DBG* ~p received ~s~n",
+      [Name,event_string(Event)]);
+print_event(Dev, {out,Reply,{To,_Tag}}, #{name := Name}) ->
+    io:format(
+      Dev, "*DBG* ~p sent ~p to ~p~n",
+      [Name,Reply,To]);
+print_event(Dev, {Tag,Event,NewState}, #{name := Name, state := State}) ->
+    StateString =
+	case NewState of
+	    State ->
+		io_lib:format("~p", [State]);
+	    _ ->
+		io_lib:format("~p => ~p", [State,NewState])
+	end,
+    io:format(
+      Dev, "*DBG* ~p ~w ~s in state ~s~n",
+      [Name,Tag,event_string(Event),StateString]).
+
+event_string(Event) ->
+    case Event of
+	{{call,{Pid,_Tag}},Request} ->
+	    io_lib:format("call ~p from ~w", [Request,Pid]);
+	{Tag,Content} ->
+	    io_lib:format("~w ~p", [Tag,Content])
+    end.
+
+sys_debug(Debug, S, Entry) ->
+    case Debug of
+	[] ->
+	    Debug;
+	_ ->
+	    sys:handle_debug(Debug, fun print_event/3, S, Entry)
+    end.
+
+%%%==========================================================================
+%%% Internal callbacks
+
+wakeup_from_hibernate(Parent, Debug, S) ->
+    %% It is a new message that woke us up so we have to receive it now
+    loop_receive(Parent, Debug, S).
+
+%%%==========================================================================
+%%% STate Machine engine implementation of proc_lib/gen server
+
+%% Server loop, consists of all loop* functions
+%% and some detours through sys and proc_lib
+
+%% Entry point for system_continue/3
+loop(Parent, Debug, #{hibernate := Hib} = S) ->
+    case Hib of
+	true ->
+	    loop_hibernate(Parent, Debug, S);
+	false ->
+	    loop_receive(Parent, Debug, S)
+    end.
+
+loop_hibernate(Parent, Debug, S) ->
+    %% Does not return but restarts process at
+    %% wakeup_from_hibernate/3 that jumps to loop_receive/3
+    proc_lib:hibernate(
+      ?MODULE, wakeup_from_hibernate, [Parent,Debug,S]),
+    error(
+      {should_not_have_arrived_here_but_instead_in,
+       {wakeup_from_hibernate,3}}).
+
+%% Entry point for wakeup_from_hibernate/3
+loop_receive(Parent, Debug, #{timer := Timer} = S) ->
+    receive
+	Msg ->
+	    case Msg of
+		{system,Pid,Req} ->
+		    %% Does not return but tail recursively calls
+		    %% system_continue/3 that jumps to loop/3
+		    sys:handle_system_msg(
+		      Req, Pid, Parent, ?MODULE, Debug, S,
+		      maps:get(hibernate, S));
+		{'EXIT',Parent,Reason} = EXIT ->
+		    %% EXIT is not a 2-tuple and therefore
+		    %% not an event and has no event_type(),
+		    %% but this will stand out in the crash report...
+		    terminate(Reason, Debug, S, [EXIT]);
+		{timeout,Timer,Content} when Timer =/= undefined ->
+		    loop_receive(
+		      Parent, Debug, S, {timeout,Content}, undefined);
+		_ ->
+		    Event =
+			case Msg of
+			    {'$gen_call',Client,Request} ->
+				{{call,Client},Request};
+			    {'$gen_cast',E} ->
+				{cast,E};
+			    _ ->
+				{info,Msg}
+			end,
+		    loop_receive(Parent, Debug, S, Event, Timer)
+	    end
+    end.
+
+loop_receive(Parent, Debug, S, Event, Timer) ->
+    NewDebug = sys_debug(Debug, S, {in,Event}),
+    %% Here the queue of not yet processed events is created
+    loop_events(Parent, NewDebug, S, [Event], Timer).
+
+%% Process first event in queue, or if there is none receive a new
+%%
+%% The loop_event* functions optimize S map handling by dismantling it,
+%% passing the parts in arguments to avoid map lookups and construct the
+%% new S map in one go on exit.  Premature optimization, I know, but
+%% the code was way to readable and there were quite some map lookups
+%% repeated in different functions.
+loop_events(Parent, Debug, S, [], _Timer) ->
+    loop(Parent, Debug, S);
+loop_events(
+  Parent, Debug,
+  #{module := Module,
+    prev_state := PrevState,
+    state := State,
+    state_data := StateData} = S,
+  [{Type,Content} = Event|Events] = Q, Timer) ->
+    _ = (Timer =/= undefined) andalso
+	cancel_timer(Timer),
+    Func =
+	if
+	    is_atom(State) ->
+		State;
+	    true ->
+		handle_event
+	end,
+    try Module:Func(Type, Content, PrevState, State, StateData) of
+	Result ->
+	    loop_event_result(
+	      Parent, Debug, S, Events, Event, Result)
+    catch
+	Result ->
+	    loop_event_result(
+	      Parent, Debug, S, Events, Event, Result);
+	error:undef ->
+	    %% Process an undef to check for the simple mistake
+	    %% of calling a nonexistent state function
+	    case erlang:get_stacktrace() of
+		[{Module,State,[Event,StateData]=Args,_}|Stacktrace] ->
+		    terminate(
+		      error,
+		      {undef_state_function,{Module,State,Args}},
+		      Stacktrace,
+		      Debug, S, Q);
+		Stacktrace ->
+		    terminate(error, undef, Stacktrace, Debug, S, Q)
+	    end;
+	Class:Reason ->
+	    Stacktrace = erlang:get_stacktrace(),
+	    terminate(Class, Reason, Stacktrace, Debug, S, Q)
+    end.
+
+%% Interprete all callback return value variants
+loop_event_result(
+  Parent, Debug,
+  #{state := State, state_data := StateData} = S,
+  Events, Event, Result) ->
+    case Result of
+	{} -> % Ignore
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, StateData, []);
+	{NewStateData} -> % Retry
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, NewStateData, [retry]);
+	{NewState,NewStateData} -> % Consume
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      NewState, NewStateData, []);
+	{NewState,NewStateData,StateOps} when is_list(StateOps) ->
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      NewState, NewStateData, StateOps);
+	StateOps when is_list(StateOps) -> % Stay in state
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, StateData, StateOps);
+	BadReturn ->
+	    terminate(
+	      {bad_return_value,BadReturn}, Debug, S, [Event|Events])
+    end.
+
+loop_event_state_ops(
+  Parent, Debug0, #{state := State, postponed := P0} = S, Events, Event,
+  NewState, NewStateData, StateOps) ->
+    case collect_state_options(StateOps) of
+	{Retry,Hibernate,Timeout,Operations} ->
+	    P1 = % Move current event to postponed if Retry
+		case Retry of
+		    true ->
+			[Event|P0];
+		    false ->
+			P0
+		end,
+	    {Q2,P2} = % Move all postponed events to queue if state change
+		if
+		    NewState =:= State ->
+			{Events,P1};
+		    true ->
+			{lists:reverse(P1, Events),[]}
+		end,
+	    %%
+	    case process_state_operations(
+		   Operations, Debug0, S, Q2, P2) of
+		{Debug,Q3,P} ->
+		    NewDebug =
+			sys_debug(
+			  Debug, S,
+			  case Retry of
+			      true ->
+				  {retry,Event,NewState};
+			      false ->
+				  {consume,Event,NewState}
+			  end),
+		    {Timer,Q} =
+			case Timeout of
+			    undefined ->
+				{undefined,Q3};
+			    {timeout,0,Msg} ->
+				%% Pretend the timeout has just been received
+				{undefined,Q3 ++ [{timeout,Msg}]};
+			    {timeout,Time,Msg} ->
+				{erlang:start_timer(Time, self(), Msg),Q3}
+			end,
+		    loop_events(
+		      Parent, NewDebug,
+		      S#{
+			prev_state := State,
+			state := NewState,
+			state_data := NewStateData,
+			timer := Timer,
+			hibernate := Hibernate,
+			postponed := P},
+		      Q, Timer);
+		[Reason,Debug] ->
+		    terminate(Reason, Debug, S, [Event|Events]);
+		[Class,Reason,Stacktrace,Debug] ->
+		    terminate(
+		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
+	    end;
+	%%
+	[Reason] ->
+	    terminate(Reason, Debug0, S, [Event|Events])
+    end.
+
+%%---------------------------------------------------------------------------
+%% Server helpers
+
+collect_state_options(StateOps) ->
+    collect_state_options(
+      lists:reverse(StateOps), false, false, undefined, []).
+%% Keep the last of each kind
+collect_state_options(
+  [], Retry, Hibernate, Timeout, Operations) ->
+    {Retry,Hibernate,Timeout,Operations};
+collect_state_options(
+  [StateOp|StateOps] = SOSOs, Retry, Hibernate, Timeout, Operations) ->
+    case StateOp of
+	retry ->
+	    collect_state_options(
+	      StateOps, true, Hibernate, Timeout, Operations);
+	{retry,NewRetry} when is_boolean(NewRetry) ->
+	    collect_state_options(
+	      StateOps, NewRetry, Hibernate, Timeout, Operations);
+	{retry,_} ->
+	    [{bad_state_ops,SOSOs}];
+	hibernate ->
+	    collect_state_options(
+	      StateOps, Retry, true, Timeout, Operations);
+	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
+	    collect_state_options(
+	      StateOps, Retry, NewHibernate, Timeout, Operations);
+	{hibernate,_} ->
+	    [{bad_state_ops,SOSOs}];
+	{timeout,infinity,_} -> % Ignore since it will never time out
+	    collect_state_options(
+	      StateOps, Retry, Hibernate, undefined, Operations);
+	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
+	    collect_state_options(
+	      StateOps, Retry, Hibernate, NewTimeout, Operations);
+	{timeout,_,_} ->
+	    [{bad_state_ops,SOSOs}];
+	_ -> % Collect others as operations
+	    collect_state_options(
+	      StateOps, Retry, Hibernate, Timeout, [StateOp|Operations])
+    end.
+
+process_state_operations([], Debug, _S, Q, P) ->
+    {Debug,Q,P};
+process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
+    case Operation of
+	{reply,{_To,_Tag}=Client,Reply} ->
+	    reply(Client, Reply),
+	    NewDebug = sys_debug(Debug, S, {out,Reply,Client}),
+	    process_state_operations(Operations, NewDebug, S, Q, P);
+	{stop,Reason} ->
+	    [Reason,Debug];
+	{insert_event,Type,Content} ->
+	    case event_type(Type) of
+		true ->
+		    process_state_operations(
+		      Operations, Debug, S, [{Type,Content}|Q], P);
+		false ->
+		    [{bad_state_ops,OOs},Debug]
+	    end;
+	_ ->
+	    %% All others are remove operations
+	    case remove_fun(Operation) of
+		false ->
+		    process_state_operations(
+		      Operations, Debug, S, Q, P);
+		undefined ->
+		    [{bad_state_ops,OOs},Debug];
+		RemoveFun when is_function(RemoveFun, 2) ->
+		    case remove_event(RemoveFun, Q, P) of
+			{NewQ,NewP} ->
+			    process_state_operations(
+			      Operations, Debug, S, NewQ, NewP);
+			Error ->
+			    Error ++ [Debug]
+		    end;
+		Error ->
+		    Error ++ [Debug]
+	    end
+    end.
+
+%% Remove oldest matching event from the queue(s)
+remove_event(RemoveFun, Q, P) ->
+    try
+	case remove_tail_event(RemoveFun, P) of
+	    false ->
+		case remove_head_event(RemoveFun, Q) of
+		    false ->
+			{P,Q};
+		    NewQ ->
+			{P,NewQ}
+		end;
+	    NewP ->
+		{NewP,Q}
+	end
+    catch
+	Class:Reason ->
+	    [Class,Reason,erlang:get_stacktrace()]
+    end.
+
+%% Do the given state operation and create an event removal predicate fun()
+remove_fun({remove_event,Type,Content}) ->
+    fun (T, C) when T =:= Type, C =:= Content -> true;
+	(_, _) -> false
+    end;
+remove_fun({remove_event,RemoveFun}) when is_function(RemoveFun, 2) ->
+    RemoveFun;
+remove_fun({cancel_timer,TimerRef}) ->
+    try cancel_timer(TimerRef) of
+	false ->
+	    false;
+	true ->
+	    fun
+		(info, {timeout,TRef,_})
+		  when TRef =:= TimerRef ->
+		    true;
+		(_, _) ->
+		    false
+	    end
+    catch
+	Class:Reason ->
+	    [Class,Reason,erlang:get_stacktrace()]
+    end;
+remove_fun({demonitor,MonitorRef}) ->
+    try erlang:demonitor(MonitorRef, [flush,info]) of
+	false ->
+	    false;
+	true ->
+	    fun (info, {'DOWN',MRef,_,_,_})
+		  when MRef =:= MonitorRef->
+		    true;
+		(_, _) ->
+		    false
+	    end
+    catch
+	Class:Reason ->
+	    [Class,Reason,erlang:get_stacktrace()]
+    end;
+remove_fun({unlink,Id}) ->
+    try unlink(Id) of
+	true ->
+	    receive
+		{'EXIT',Id,_} ->
+		    ok
+	    after 0 ->
+		    ok
+	    end,
+	    fun (info, {'EXIT',I,_})
+		  when I =:= Id ->
+		    true;
+		(_, _) ->
+		    false
+	    end
+    catch
+	Class:Reason ->
+	    {Class,Reason,erlang:get_stacktrace()}
+    end;
+remove_fun(_) ->
+    undefined.
+
+
+%% Cancel a timer and clense the process mailbox returning
+%% false if no such timer message can arrive after this or
+%% true otherwise
+cancel_timer(TimerRef) ->
+    case erlang:cancel_timer(TimerRef) of
+	TimeLeft when is_integer(TimeLeft) ->
+	    false;
+	false ->
+	    receive
+		{timeout,TimerRef,_} ->
+		    false
+	    after 0 ->
+		    true
+	    end
+    end.
+
+
+terminate(Reason, Debug, S, Q) ->
+    terminate(exit, Reason, [], Debug, S, Q).
+%%
+terminate(
+  Class, Reason, Stacktrace, Debug,
+  #{name := Name, module := Module,
+    state := State, state_data := StateData} = S,
+  Q) ->
+    try Module:terminate(Reason, State, StateData) of
+	_ -> ok
+    catch
+	_ -> ok;
+	C:R ->
+	    ST = erlang:get_stacktrace(),
+	    error_info(
+	      C, R, ST, Debug, Name, Q,
+	      format_status(terminate, get(), S)),
+	    erlang:raise(C, R, ST)
+    end,
+    case Reason of
+	normal -> ok;
+	shutdown -> ok;
+	{shutdown,_} -> ok;
+	_ ->
+	    error_info(
+	      Class, Reason, Stacktrace, Debug, Name, Q,
+	      format_status(terminate, get(), S))
+    end,
+    case Stacktrace of
+	[] ->
+	    erlang:Class(Reason);
+	_ ->
+	    erlang:raise(Class, Reason, Stacktrace)
+    end.
+
+error_info(
+  Class, Reason, Stacktrace, Debug, Name, Q, FmtStateData) ->
+    {FixedReason,FixedStacktrace} =
+	case Stacktrace of
+	    [{M,F,Args,_}|ST]
+	      when Class =:= error, Reason =:= undef ->
+		case code:is_loaded(M) of
+		    false ->
+			{{'module could not be loaded',M},ST};
+		    _ ->
+			Arity = length(Args),
+			case erlang:function_exported(M, F, Arity) of
+			    true ->
+				{Reason,Stacktrace};
+			    false ->
+				{{'function not exported',{M,F,Arity}},
+				 ST}
+			end
+		end;
+	    _ -> {Reason,Stacktrace}
+	end,
+    error_logger:format(
+      "** State machine ~p terminating~n" ++
+	  case Q of
+	      [] ->
+		  "";
+	      _ ->
+		  "** Last event = ~p~n"
+	  end ++
+	  "** When Server state  = ~p~n" ++
+	  "** Reason for termination = ~w:~p~n" ++
+	  case FixedStacktrace of
+	      [] ->
+		  "";
+	      _ ->
+		  "** Stacktrace =~n"
+		      "**  ~p~n"
+	  end,
+      [Name |
+       case Q of
+	   [] ->
+	       [FmtStateData,Class,FixedReason];
+	   [Event|_] ->
+	       [Event,FmtStateData,Class,FixedReason]
+       end] ++
+	  case FixedStacktrace of
+	      [] ->
+		  [];
+	      _ ->
+		  [FixedStacktrace]
+	  end),
+    sys:print_log(Debug),
+    ok.
+
+
+%% Call Module:format_status/2 or return a default value
+format_status(
+  Opt, PDict,
+  #{module := Module, state := State, state_data := StateData}) ->
+    case erlang:function_exported(Module, format_status, 2) of
+	true ->
+	    try Module:format_status(Opt, [PDict,State,StateData])
+	    catch
+		Result -> Result;
+		_:_ ->
+		    format_status_default(Opt, State, StateData)
+	    end;
+	false ->
+	    format_status_default(Opt, State, StateData)
+    end.
+
+%% The default Module:format_status/2
+format_status_default(Opt, State, StateData) ->
+    SSD = {State,StateData},
+    case Opt of
+	terminate ->
+	    SSD;
+	_ ->
+	    [{data,[{"State",SSD}]}]
+    end.
+
+%%---------------------------------------------------------------------------
+%% Farily general helpers
+
+%% Return the modified list where the first element that satisfies
+%% the RemoveFun predicate is removed, or false if no such element exists.
+remove_head_event(_RemoveFun, []) ->
+    false;
+remove_head_event(RemoveFun, [{Tag,Content}|Events]) ->
+    case RemoveFun(Tag, Content) of
+	false ->
+	    remove_head_event(RemoveFun, Events);
+	true ->
+	    Events
+    end.
+
+%% Return the modified list where the last element that satisfies
+%% the RemoveFun predicate is removed, or false if no such element exists.
+remove_tail_event(_RemoveFun, []) ->
+    false;
+remove_tail_event(RemoveFun, [{Tag,Content} = Event|Events]) ->
+    case remove_tail_event(RemoveFun, Events) of
+	false ->
+	    RemoveFun(Tag, Content) andalso Events;
+	NewEvents ->
+	    [Event|NewEvents]
+    end.
diff --git a/lib/stdlib/src/proc_lib.erl b/lib/stdlib/src/proc_lib.erl
index 10c476a6f5..3f79ed0f87 100644
--- a/lib/stdlib/src/proc_lib.erl
+++ b/lib/stdlib/src/proc_lib.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2016. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -472,13 +472,15 @@ trans_init(gen,init_it,[gen_server,_,_,supervisor_bridge,[Module|_],_]) ->
     {supervisor_bridge,Module,1};
 trans_init(gen,init_it,[gen_server,_,_,_,supervisor_bridge,[Module|_],_]) ->
     {supervisor_bridge,Module,1};
-trans_init(gen,init_it,[gen_server,_,_,Module,_,_]) ->
+trans_init(gen,init_it,[GenMod,_,_,Module,_,_])
+  when GenMod =:= gen_server;
+       GenMod =:= gen_statem;
+       GenMod =:= gen_fsm ->
     {Module,init,1};
-trans_init(gen,init_it,[gen_server,_,_,_,Module|_]) ->
-    {Module,init,1};
-trans_init(gen,init_it,[gen_fsm,_,_,Module,_,_]) ->
-    {Module,init,1};
-trans_init(gen,init_it,[gen_fsm,_,_,_,Module|_]) ->
+trans_init(gen,init_it,[GenMod,_,_,_,Module|_])
+  when GenMod =:= gen_server;
+       GenMod =:= gen_statem;
+       GenMod =:= gen_fsm ->
     {Module,init,1};
 trans_init(gen,init_it,[gen_event|_]) ->
     {gen_event,init_it,6};
diff --git a/lib/stdlib/src/stdlib.app.src b/lib/stdlib/src/stdlib.app.src
index 7f9bbbf649..dc17a44150 100644
--- a/lib/stdlib/src/stdlib.app.src
+++ b/lib/stdlib/src/stdlib.app.src
@@ -2,7 +2,7 @@
 %% 
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2015. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2016. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -65,6 +65,7 @@
 	     gen_event,
 	     gen_fsm,
 	     gen_server,
+	     gen_statem,
 	     io,
 	     io_lib,
 	     io_lib_format,
diff --git a/lib/stdlib/test/Makefile b/lib/stdlib/test/Makefile
index e366c2b755..427d7fcaea 100644
--- a/lib/stdlib/test/Makefile
+++ b/lib/stdlib/test/Makefile
@@ -46,6 +46,7 @@ MODULES= \
 	gen_event_SUITE \
 	gen_fsm_SUITE \
 	gen_server_SUITE \
+	gen_statem_SUITE \
 	id_transform_SUITE \
 	io_SUITE \
 	io_proto_SUITE \
diff --git a/lib/stdlib/test/error_logger_forwarder.erl b/lib/stdlib/test/error_logger_forwarder.erl
index 7ac2cfce82..d34dde9def 100644
--- a/lib/stdlib/test/error_logger_forwarder.erl
+++ b/lib/stdlib/test/error_logger_forwarder.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 2010. All Rights Reserved.
+%% Copyright Ericsson AB 2010-2015. All Rights Reserved.
 %% 
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -20,7 +20,7 @@
 -module(error_logger_forwarder).
 
 %% API.
--export([register/0]).
+-export([register/0, unregister/0]).
 
 %% Internal export for error_logger.
 -export([init/1,
@@ -33,6 +33,10 @@
 register() ->
     error_logger:add_report_handler(?MODULE, self()).
 
+unregister() ->
+    Self = self(),
+    Self = error_logger:delete_report_handler(?MODULE).
+
 init(Tester) ->
     {ok,Tester}.
     
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
new file mode 100644
index 0000000000..342be32acb
--- /dev/null
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -0,0 +1,1250 @@
+%%
+%% %CopyrightBegin%
+%%
+%% Copyright Ericsson AB 2016. All Rights Reserved.
+%%
+%% 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.
+%%
+%% %CopyrightEnd%
+%%
+-module(gen_statem_SUITE).
+
+-include_lib("test_server/include/test_server.hrl").
+
+-compile(export_all).
+-behaviour(gen_statem).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+suite() -> [{ct_hooks,[ts_install_cth]}].
+
+all() ->
+    [{group, start},
+     {group, abnormal},
+     shutdown,
+     {group, sys}, hibernate, enter_loop].
+
+groups() ->
+    [{start, [],
+      [start1, start2, start3, start4, start5, start6, start7,
+       start8, start9, start10, start11, start12]},
+     {stop, [],
+      [stop1, stop2, stop3, stop4, stop5, stop6, stop7, stop8, stop9, stop10]},
+     {abnormal, [], [abnormal1, abnormal2]},
+     {sys, [],
+      [sys1,
+       call_format_status,
+       error_format_status, terminate_crash_format,
+       get_state, replace_state]}].
+
+init_per_suite(Config) ->
+    Config.
+
+end_per_suite(_Config) ->
+    ok.
+
+init_per_group(_GroupName, Config) ->
+    Config.
+
+end_per_group(_GroupName, Config) ->
+    Config.
+
+init_per_testcase(_CaseName, Config) ->
+    ?t:messages_get(),
+    Dog = ?t:timetrap(?t:minutes(1)),
+%%%    dbg:tracer(),
+%%%    dbg:p(all, c),
+%%%    dbg:tpl(gen_statem, cx),
+    [{watchdog, Dog} | Config].
+
+end_per_testcase(_CaseName, Config) ->
+%%%    dbg:stop(),
+    Dog = ?config(watchdog, Config),
+    test_server:timetrap_cancel(Dog),
+    Config.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+-define(EXPECT_FAILURE(Code, Reason),
+	try begin Code end of
+	    _ ->
+		?t:fail()
+	catch
+	    error:Reason -> Reason;
+	    exit:Reason -> Reason
+	end).
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% anonymous
+start1(Config) when is_list(Config) ->
+    %%OldFl = process_flag(trap_exit, true),
+
+    {ok,Pid0} = gen_statem:start_link(?MODULE, [], []),
+    ok = do_func_test(Pid0),
+    ok = do_sync_func_test(Pid0),
+    stop_it(Pid0),
+%%    stopped = gen_statem:call(Pid0, stop),
+%%    timeout =
+%%	?EXPECT_FAILURE(gen_statem:call(Pid0, hej), Reason),
+
+    %%process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+%% anonymous w. shutdown
+start2(Config) when is_list(Config) ->
+    %% Dont link when shutdown
+    {ok,Pid0} = gen_statem:start(?MODULE, [], []),
+    ok = do_func_test(Pid0),
+    ok = do_sync_func_test(Pid0),
+    stopped = gen_statem:call(Pid0, {stop,shutdown}),
+    check_stopped(Pid0),
+    ok = verify_empty_msgq().
+
+%% anonymous with timeout
+start3(Config) when is_list(Config) ->
+    %%OldFl = process_flag(trap_exit, true),
+
+    {ok,Pid0} = gen_statem:start(?MODULE, [], [{timeout,5}]),
+    ok = do_func_test(Pid0),
+    ok = do_sync_func_test(Pid0),
+    stop_it(Pid0),
+
+    {error,timeout} = gen_statem:start(?MODULE, sleep,
+					   [{timeout,5}]),
+
+    %%process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+%% anonymous with ignore
+start4(Config) when is_list(Config) ->
+    OldFl = process_flag(trap_exit, true),
+
+    ignore = gen_statem:start(?MODULE, ignore, []),
+
+    process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+%% anonymous with stop
+start5(suite) -> [];
+start5(Config) when is_list(Config) ->
+    OldFl = process_flag(trap_exit, true),
+
+    {error,stopped} = gen_statem:start(?MODULE, stop, []),
+
+    process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+%% anonymous linked
+start6(Config) when is_list(Config) ->
+    {ok,Pid} = gen_statem:start_link(?MODULE, [], []),
+    ok = do_func_test(Pid),
+    ok = do_sync_func_test(Pid),
+    stop_it(Pid),
+
+    ok = verify_empty_msgq().
+
+%% global register linked
+start7(Config) when is_list(Config) ->
+    STM = {global,my_stm},
+
+    {ok,Pid} =
+	gen_statem:start_link(STM, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start_link(STM, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start(STM, ?MODULE, [], []),
+
+    ok = do_func_test(Pid),
+    ok = do_sync_func_test(Pid),
+    ok = do_func_test(STM),
+    ok = do_sync_func_test(STM),
+    stop_it(STM),
+
+    ok = verify_empty_msgq().
+
+
+%% local register
+start8(Config) when is_list(Config) ->
+    %%OldFl = process_flag(trap_exit, true),
+    Name = my_stm,
+    STM = {local,Name},
+
+    {ok,Pid} =
+	gen_statem:start(STM, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start(STM, ?MODULE, [], []),
+
+    ok = do_func_test(Pid),
+    ok = do_sync_func_test(Pid),
+    ok = do_func_test(Name),
+    ok = do_sync_func_test(Name),
+    stop_it(Pid),
+
+    %%process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+%% local register linked
+start9(Config) when is_list(Config) ->
+    %%OldFl = process_flag(trap_exit, true),
+    Name = my_stm,
+    STM = {local,Name},
+
+    {ok,Pid} =
+	gen_statem:start_link(STM, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start(STM, ?MODULE, [], []),
+
+    ok = do_func_test(Pid),
+    ok = do_sync_func_test(Pid),
+    ok = do_func_test(Name),
+    ok = do_sync_func_test(Name),
+    stop_it(Pid),
+
+    %%process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+%% global register
+start10(Config) when is_list(Config) ->
+    STM = {global,my_stm},
+
+    {ok,Pid} =
+	gen_statem:start(STM, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start(STM, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start_link(STM, ?MODULE, [], []),
+
+    ok = do_func_test(Pid),
+    ok = do_sync_func_test(Pid),
+    ok = do_func_test(STM),
+    ok = do_sync_func_test(STM),
+    stop_it(STM),
+
+    ok = verify_empty_msgq().
+
+%% Stop registered processes
+start11(Config) when is_list(Config) ->
+    Name = my_stm,
+    LocalSTM = {local,Name},
+    GlobalSTM = {global,Name},
+
+    {ok,Pid} =
+	gen_statem:start_link(LocalSTM, ?MODULE, [], []),
+    stop_it(Pid),
+
+    {ok,_Pid1} =
+	gen_statem:start_link(LocalSTM, ?MODULE, [], []),
+    stop_it(Name),
+
+    {ok,Pid2} =
+	gen_statem:start(GlobalSTM, ?MODULE, [], []),
+    stop_it(Pid2),
+    receive after 1 -> true end,
+    Result =
+	gen_statem:start(GlobalSTM, ?MODULE, [], []),
+    io:format("Result = ~p~n",[Result]),
+    {ok,_Pid3} = Result,
+    stop_it(GlobalSTM),
+
+    ok = verify_empty_msgq().
+
+%% Via register linked
+start12(Config) when is_list(Config) ->
+    dummy_via:reset(),
+    VIA = {via,dummy_via,my_stm},
+
+    {ok,Pid} =
+	gen_statem:start_link(VIA, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start_link(VIA, ?MODULE, [], []),
+    {error,{already_started,Pid}} =
+	gen_statem:start(VIA, ?MODULE, [], []),
+
+    ok = do_func_test(Pid),
+    ok = do_sync_func_test(Pid),
+    ok = do_func_test(VIA),
+    ok = do_sync_func_test(VIA),
+    stop_it(VIA),
+
+    ok = verify_empty_msgq().
+
+
+%% Anonymous, reason 'normal'
+stop1(_Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    ok = gen_statem:stop(Pid),
+    false = erlang:is_process_alive(Pid),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason).
+
+%% Anonymous, other reason
+stop2(_Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    ok = gen_statem:stop(Pid, other_reason, infinity),
+    false = erlang:is_process_alive(Pid),
+    ok.
+
+%% Anonymous, invalid timeout
+stop3(_Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    _ =
+	?EXPECT_FAILURE(
+	   gen_statem:stop(Pid, other_reason, invalid_timeout),
+	   Reason),
+    true = erlang:is_process_alive(Pid),
+    ok = gen_statem:stop(Pid),
+    false = erlang:is_process_alive(Pid),
+    ok.
+
+%% Registered name
+stop4(_Config) ->
+    {ok,Pid} = gen_statem:start({local,to_stop},?MODULE, [], []),
+    ok = gen_statem:stop(to_stop),
+    false = erlang:is_process_alive(Pid),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(to_stop), Reason),
+    ok.
+
+%% Registered name and local node
+stop5(_Config) ->
+    Name = to_stop,
+    {ok,Pid} = gen_statem:start({local,Name},?MODULE, [], []),
+    ok = gen_statem:stop({Name,node()}),
+    false = erlang:is_process_alive(Pid),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop({Name,node()}), Reason),
+    ok.
+
+%% Globally registered name
+stop6(_Config) ->
+    STM = {global,to_stop},
+    {ok,Pid} = gen_statem:start(STM, ?MODULE, [], []),
+    ok = gen_statem:stop(STM),
+    false = erlang:is_process_alive(Pid),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(STM), Reason),
+    ok.
+
+%% 'via' registered name
+stop7(_Config) ->
+    VIA = {via,dummy_via,to_stop},
+    dummy_via:reset(),
+    {ok,Pid} = gen_statem:start(VIA,
+				  ?MODULE, [], []),
+    ok = gen_statem:stop(VIA),
+    false = erlang:is_process_alive(Pid),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(VIA), Reason),
+    ok.
+
+%% Anonymous on remote node
+stop8(_Config) ->
+    {ok,Node} = ?t:start_node(gen_statem_stop8, slave, []),
+    Dir = filename:dirname(code:which(?MODULE)),
+    rpc:call(Node, code, add_path, [Dir]),
+    {ok,Pid} = rpc:call(Node, gen_statem,start, [?MODULE,[],[]]),
+    ok = gen_statem:stop(Pid),
+    false = rpc:call(Node, erlang, is_process_alive, [Pid]),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason1),
+    true = ?t:stop_node(Node),
+    {nodedown,Node} =
+	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason2),
+    ok.
+
+%% Registered name on remote node
+stop9(_Config) ->
+    Name = to_stop,
+    LocalSTM = {local,Name},
+    {ok,Node} = ?t:start_node(gen_statem__stop9, slave, []),
+    STM = {Name,Node},
+    Dir = filename:dirname(code:which(?MODULE)),
+    rpc:call(Node, code, add_path, [Dir]),
+    {ok,Pid} = rpc:call(Node, gen_statem, start, [LocalSTM,?MODULE,[],[]]),
+    ok = gen_statem:stop(STM),
+    undefined = rpc:call(Node,erlang,whereis,[Name]),
+    false = rpc:call(Node,erlang,is_process_alive,[Pid]),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(STM), Reason1),
+    true = ?t:stop_node(Node),
+    {nodedown,Node} =
+	?EXPECT_FAILURE(gen_statem:stop(STM), Reason2),
+    ok.
+
+%% Globally registered name on remote node
+stop10(_Config) ->
+    STM = {global,to_stop},
+    {ok,Node} = ?t:start_node(gen_statem_stop10, slave, []),
+    Dir = filename:dirname(code:which(?MODULE)),
+    rpc:call(Node,code,add_path,[Dir]),
+    {ok,Pid} = rpc:call(Node, gen_statem, start, [STM,?MODULE,[],[]]),
+    global:sync(),
+    ok = gen_statem:stop(STM),
+    false = rpc:call(Node, erlang, is_process_alive, [Pid]),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(STM), Reason1),
+    true = ?t:stop_node(Node),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(STM), Reason2),
+    ok.
+
+%% Check that time outs in calls work
+abnormal1(Config) when is_list(Config) ->
+    Name = abnormal1,
+    LocalSTM = {local,Name},
+
+    {ok, _Pid} = gen_statem:start(LocalSTM, ?MODULE, [], []),
+
+    %% timeout call.
+    delayed = gen_statem:call(Name, {delayed_answer,1}, 100),
+    {timeout,_} =
+	?EXPECT_FAILURE(
+	   gen_statem:call(Name, {delayed_answer,1000}, 10),
+	   Reason),
+    ok = verify_empty_msgq().
+
+%% Check that bad return values makes the stm crash. Note that we must
+%% trap exit since we must link to get the real bad_return_ error
+abnormal2(Config) when is_list(Config) ->
+    OldFl = process_flag(trap_exit, true),
+    {ok,Pid} = gen_statem:start_link(?MODULE, [], []),
+
+    %% bad return value in the gen_statem loop
+    {{bad_return_value,badreturn},_} =
+	?EXPECT_FAILURE(gen_statem:call(Pid, badreturn), Reason),
+    receive
+	{'EXIT',Pid,{bad_return_value,badreturn}} -> ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    process_flag(trap_exit, OldFl),
+    ok = verify_empty_msgq().
+
+shutdown(Config) when is_list(Config) ->
+    process_flag(trap_exit, true),
+
+    {ok,Pid0} = gen_statem:start_link(?MODULE, [], []),
+    ok = do_func_test(Pid0),
+    ok = do_sync_func_test(Pid0),
+    stopped = gen_statem:call(Pid0, {stop,{shutdown,reason}}),
+    receive {'EXIT',Pid0,{shutdown,reason}} -> ok end,
+    process_flag(trap_exit, false),
+
+    {noproc,_} =
+	?EXPECT_FAILURE(gen_statem:call(Pid0, hej), Reason),
+
+    receive
+	Any ->
+	    io:format("Unexpected: ~p", [Any]),
+	    ?t:fail()
+    after 500 ->
+	    ok
+    end.
+
+
+
+sys1(Config) when is_list(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    {status, Pid, {module,gen_statem}, _} = sys:get_status(Pid),
+    sys:suspend(Pid),
+    Parent = self(),
+    Tag = make_ref(),
+    Caller =
+	spawn(
+	  fun () ->
+		  Parent ! {Tag,gen_statem:call(Pid, hej)}
+	  end),
+    receive
+	{Tag,_} ->
+	    ?t:fail()
+    after 3000 ->
+	    exit(Caller, ok)
+    end,
+
+    %% {timeout,_} =
+    %% 	?EXPECT_FAILURE(gen_statem:call(Pid, hej), Reason),
+    sys:resume(Pid),
+    stop_it(Pid).
+
+call_format_status(Config) when is_list(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    Status = sys:get_status(Pid),
+    {status,Pid,_Mod,[_PDict,running,_,_, Data]} = Status,
+    [format_status_called|_] = lists:reverse(Data),
+    stop_it(Pid),
+
+    %% check that format_status can handle a name being an atom (pid is
+    %% already checked by the previous test)
+    {ok, Pid2} = gen_statem:start({local, gstm}, ?MODULE, [], []),
+    Status2 = sys:get_status(gstm),
+    {status,Pid2,_Mod,[_PDict2,running,_,_,Data2]} = Status2,
+    [format_status_called|_] = lists:reverse(Data2),
+    stop_it(Pid2),
+
+    %% check that format_status can handle a name being a term other than a
+    %% pid or atom
+    GlobalName1 = {global,"CallFormatStatus"},
+    {ok,Pid3} = gen_statem:start(GlobalName1, ?MODULE, [], []),
+    Status3 = sys:get_status(GlobalName1),
+    {status,Pid3,_Mod,[_PDict3,running,_,_,Data3]} = Status3,
+    [format_status_called|_] = lists:reverse(Data3),
+    stop_it(Pid3),
+    GlobalName2 = {global,{name, "term"}},
+    {ok,Pid4} = gen_statem:start(GlobalName2, ?MODULE, [], []),
+    Status4 = sys:get_status(GlobalName2),
+    {status,Pid4,_Mod,[_PDict4,running,_,_, Data4]} = Status4,
+    [format_status_called|_] = lists:reverse(Data4),
+    stop_it(Pid4),
+
+    %% check that format_status can handle a name being a term other than a
+    %% pid or atom
+    dummy_via:reset(),
+    ViaName1 = {via,dummy_via,"CallFormatStatus"},
+    {ok,Pid5} = gen_statem:start(ViaName1, ?MODULE, [], []),
+    Status5 = sys:get_status(ViaName1),
+    {status,Pid5,_Mod, [_PDict5,running,_,_, Data5]} = Status5,
+    [format_status_called|_] = lists:reverse(Data5),
+    stop_it(Pid5),
+    ViaName2 = {via,dummy_via,{name,"term"}},
+    {ok, Pid6} = gen_statem:start(ViaName2, ?MODULE, [], []),
+    Status6 = sys:get_status(ViaName2),
+    {status,Pid6,_Mod,[_PDict6,running,_,_,Data6]} = Status6,
+    [format_status_called|_] = lists:reverse(Data6),
+    stop_it(Pid6).
+
+
+
+error_format_status(Config) when is_list(Config) ->
+    error_logger_forwarder:register(),
+    OldFl = process_flag(trap_exit, true),
+    StateData = "called format_status",
+    {ok,Pid} = gen_statem:start(?MODULE, {state_data,StateData}, []),
+    %% bad return value in the gen_statem loop
+    {{bad_return_value,badreturn},_} =
+	?EXPECT_FAILURE(gen_statem:call(Pid, badreturn), Reason),
+    receive
+	{error,_,
+	 {Pid,
+	  "** State machine"++_,
+	  [Pid,{{call,_},badreturn},
+	   {formatted,idle,StateData},
+	   exit,{bad_return_value,badreturn}|_]}} ->
+	    ok;
+	Other when is_tuple(Other), element(1, Other) =:= error ->
+	    error_logger_forwarder:unregister(),
+	    ?t:fail({unexpected,Other})
+    after 1000 ->
+	    error_logger_forwarder:unregister(),
+	    ?t:fail()
+    end,
+    process_flag(trap_exit, OldFl),
+    error_logger_forwarder:unregister(),
+    receive
+	%% Comes with SASL
+	{error_report,_,{Pid,crash_report,_}} ->
+	    ok
+    after 500 ->
+	    ok
+    end,
+    ok = verify_empty_msgq().
+
+terminate_crash_format(Config) when is_list(Config) ->
+    error_logger_forwarder:register(),
+    OldFl = process_flag(trap_exit, true),
+    StateData = crash_terminate,
+    {ok,Pid} = gen_statem:start(?MODULE, {state_data,StateData}, []),
+    stop_it(Pid),
+    Self = self(),
+    receive
+	{error,_GroupLeader,
+	 {Pid,
+	  "** State machine"++_,
+	  [Pid,
+	   {{call,{Self,_}},stop},
+	   {formatted,idle,StateData},
+	   exit,{crash,terminate}|_]}} ->
+	    ok;
+	Other when is_tuple(Other), element(1, Other) =:= error ->
+	    error_logger_forwarder:unregister(),
+	    ?t:fail({unexpected,Other})
+    after 1000 ->
+	    error_logger_forwarder:unregister(),
+	    ?t:fail()
+    end,
+    process_flag(trap_exit, OldFl),
+    error_logger_forwarder:unregister(),
+    receive
+	%% Comes with SASL
+	{error_report,_,{Pid,crash_report,_}} ->
+	    ok
+    after 500 ->
+	    ok
+    end,
+    ok = verify_empty_msgq().
+
+
+get_state(Config) when is_list(Config) ->
+    State = self(),
+    {ok,Pid} = gen_statem:start(?MODULE, {state_data,State}, []),
+    {idle,State} = sys:get_state(Pid),
+    {idle,State} = sys:get_state(Pid, 5000),
+    stop_it(Pid),
+
+    %% check that get_state can handle a name being an atom (pid is
+    %% already checked by the previous test)
+    {ok,Pid2} =
+	gen_statem:start({local,gstm}, ?MODULE, {state_data,State}, []),
+    {idle,State} = sys:get_state(gstm),
+    {idle,State} = sys:get_state(gstm, 5000),
+    stop_it(Pid2),
+
+    %% check that get_state works when pid is sys suspended
+    {ok,Pid3} = gen_statem:start(?MODULE, {state_data,State}, []),
+    {idle,State} = sys:get_state(Pid3),
+    ok = sys:suspend(Pid3),
+    {idle,State} = sys:get_state(Pid3, 5000),
+    ok = sys:resume(Pid3),
+    stop_it(Pid3),
+    ok = verify_empty_msgq().
+
+replace_state(Config) when is_list(Config) ->
+    State = self(),
+    {ok, Pid} = gen_statem:start(?MODULE, {state_data,State}, []),
+    {idle,State} = sys:get_state(Pid),
+    NState1 = "replaced",
+    Replace1 = fun({StateName, _}) -> {StateName,NState1} end,
+    {idle,NState1} = sys:replace_state(Pid, Replace1),
+    {idle,NState1} = sys:get_state(Pid),
+    NState2 = "replaced again",
+    Replace2 = fun({idle, _}) -> {state0,NState2} end,
+    {state0,NState2} = sys:replace_state(Pid, Replace2, 5000),
+    {state0,NState2} = sys:get_state(Pid),
+    %% verify no change in state if replace function crashes
+    Replace3 = fun(_) -> error(fail) end,
+    {callback_failed,
+     {gen_statem,system_replace_state},{error,fail}} =
+	?EXPECT_FAILURE(sys:replace_state(Pid, Replace3), Reason),
+    {state0, NState2} = sys:get_state(Pid),
+    %% verify state replaced if process sys suspended
+    ok = sys:suspend(Pid),
+    Suffix2 = " and again",
+    NState3 = NState2 ++ Suffix2,
+    Replace4 = fun({StateName, _}) -> {StateName, NState3} end,
+    {state0,NState3} = sys:replace_state(Pid, Replace4),
+    ok = sys:resume(Pid),
+    {state0,NState3} = sys:get_state(Pid, 5000),
+    stop_it(Pid),
+    ok = verify_empty_msgq().
+
+%% Hibernation
+hibernate(Config) when is_list(Config) ->
+    OldFl = process_flag(trap_exit, true),
+
+    {ok,Pid0} = gen_statem:start_link(?MODULE, hiber_now, []),
+    is_in_erlang_hibernate(Pid0),
+    stop_it(Pid0),
+    receive
+	{'EXIT',Pid0,normal} -> ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    {ok,Pid} = gen_statem:start_link(?MODULE, hiber, []),
+    true = ({current_function,{erlang,hibernate,3}} =/=
+		erlang:process_info(Pid,current_function)),
+    hibernating = gen_statem:call(Pid, hibernate_sync),
+    is_in_erlang_hibernate(Pid),
+    good_morning = gen_statem:call(Pid, wakeup_sync),
+    is_not_in_erlang_hibernate(Pid),
+    hibernating = gen_statem:call(Pid, hibernate_sync),
+    is_in_erlang_hibernate(Pid),
+    please_just_five_more = gen_statem:call(Pid, snooze_sync),
+    is_in_erlang_hibernate(Pid),
+    good_morning = gen_statem:call(Pid, wakeup_sync),
+    is_not_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, hibernate_async),
+    is_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, wakeup_async),
+    is_not_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, hibernate_async),
+    is_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, snooze_async),
+    is_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, wakeup_async),
+    is_not_in_erlang_hibernate(Pid),
+
+    Pid ! hibernate_later,
+    true =
+	({current_function,{erlang,hibernate,3}} =/=
+	     erlang:process_info(Pid, current_function)),
+    is_in_erlang_hibernate(Pid),
+
+    'alive!' = gen_statem:call(Pid, 'alive?'),
+    true =
+	({current_function,{erlang,hibernate,3}} =/=
+	     erlang:process_info(Pid, current_function)),
+    Pid ! hibernate_now,
+    is_in_erlang_hibernate(Pid),
+
+    'alive!' = gen_statem:call(Pid, 'alive?'),
+    true =
+	({current_function,{erlang,hibernate,3}} =/=
+	     erlang:process_info(Pid, current_function)),
+
+    hibernating = gen_statem:call(Pid, hibernate_sync),
+    is_in_erlang_hibernate(Pid),
+    good_morning = gen_statem:call(Pid, wakeup_sync),
+    is_not_in_erlang_hibernate(Pid),
+    hibernating = gen_statem:call(Pid, hibernate_sync),
+    is_in_erlang_hibernate(Pid),
+    please_just_five_more = gen_statem:call(Pid, snooze_sync),
+    is_in_erlang_hibernate(Pid),
+    good_morning = gen_statem:call(Pid, wakeup_sync),
+    is_not_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, hibernate_async),
+    is_in_erlang_hibernate(Pid),
+    ok  = gen_statem:cast(Pid, wakeup_async),
+    is_not_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, hibernate_async),
+    is_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, snooze_async),
+    is_in_erlang_hibernate(Pid),
+    ok = gen_statem:cast(Pid, wakeup_async),
+    is_not_in_erlang_hibernate(Pid),
+
+    hibernating = gen_statem:call(Pid, hibernate_sync),
+    is_in_erlang_hibernate(Pid),
+    sys:suspend(Pid),
+    is_in_erlang_hibernate(Pid),
+    sys:resume(Pid),
+    is_in_erlang_hibernate(Pid),
+    receive after 1000 -> ok end,
+    is_in_erlang_hibernate(Pid),
+
+    good_morning  = gen_statem:call(Pid, wakeup_sync),
+    is_not_in_erlang_hibernate(Pid),
+    stop_it(Pid),
+    process_flag(trap_exit, OldFl),
+    receive
+	{'EXIT',Pid,normal} -> ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+    ok = verify_empty_msgq().
+
+is_in_erlang_hibernate(Pid) ->
+    receive after 1 -> ok end,
+    is_in_erlang_hibernate_1(200, Pid).
+
+is_in_erlang_hibernate_1(0, Pid) ->
+    io:format("~p\n", [erlang:process_info(Pid, current_function)]),
+    ?t:fail(not_in_erlang_hibernate_3);
+is_in_erlang_hibernate_1(N, Pid) ->
+    {current_function,MFA} = erlang:process_info(Pid, current_function),
+    case MFA of
+	{erlang,hibernate,3} ->
+	    ok;
+	_ ->
+	    receive after 10 -> ok end,
+	    is_in_erlang_hibernate_1(N-1, Pid)
+    end.
+
+is_not_in_erlang_hibernate(Pid) ->
+    receive after 1 -> ok end,
+    is_not_in_erlang_hibernate_1(200, Pid).
+
+is_not_in_erlang_hibernate_1(0, Pid) ->
+    io:format("~p\n", [erlang:process_info(Pid, current_function)]),
+    ?t:fail(not_in_erlang_hibernate_3);
+is_not_in_erlang_hibernate_1(N, Pid) ->
+    {current_function,MFA} = erlang:process_info(Pid, current_function),
+    case MFA of
+	{erlang,hibernate,3} ->
+	    receive after 10 -> ok end,
+	    is_not_in_erlang_hibernate_1(N-1, Pid);
+	_ ->
+	    ok
+    end.
+
+%%sys1(suite) -> [];
+%%sys1(_) ->
+
+enter_loop(Config) when is_list(Config) ->
+    OldFlag = process_flag(trap_exit, true),
+
+    dummy_via:reset(),
+
+    %% Locally registered process + {local,Name}
+    {ok,Pid1a} =
+	proc_lib:start_link(?MODULE, enter_loop, [local,local]),
+    yes = gen_statem:call(Pid1a, 'alive?'),
+    stopped = gen_statem:call(Pid1a, stop),
+    receive
+	{'EXIT',Pid1a,normal} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Unregistered process + {local,Name}
+    {ok,Pid1b} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,local]),
+    receive
+	{'EXIT',Pid1b,process_not_registered} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Globally registered process + {global,Name}
+    {ok,Pid2a} =
+	proc_lib:start_link(?MODULE, enter_loop, [global,global]),
+    yes = gen_statem:call(Pid2a, 'alive?'),
+    stopped = gen_statem:call(Pid2a, stop),
+    receive
+	{'EXIT',Pid2a,normal} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Unregistered process + {global,Name}
+    {ok,Pid2b} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,global]),
+    receive
+	{'EXIT',Pid2b,process_not_registered_globally} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Unregistered process + no name
+    {ok,Pid3} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,anon]),
+    yes = gen_statem:call(Pid3, 'alive?'),
+    stopped = gen_statem:call(Pid3, stop),
+    receive
+	{'EXIT',Pid3,normal} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Process not started using proc_lib
+    Pid4 =
+	spawn_link(gen_statem, enter_loop, [?MODULE,[],state0,[]]),
+    receive
+	{'EXIT',Pid4,process_was_not_started_by_proc_lib} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Make sure I am the parent, ie that ordering a shutdown will
+    %% result in the process terminating with Reason==shutdown
+    {ok,Pid5} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,anon]),
+    yes = gen_statem:call(Pid5, 'alive?'),
+    exit(Pid5, shutdown),
+    receive
+	{'EXIT',Pid5,shutdown} ->
+	    ok
+    after 5000 ->
+	    ?t:fail(gen_statem_did_not_die)
+    end,
+
+    %% Make sure gen_statem:enter_loop does not accept {local,Name}
+    %% when it's another process than the calling one which is
+    %% registered under that name
+    register(armitage, self()),
+    {ok,Pid6a} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,local]),
+    receive
+	{'EXIT',Pid6a,process_not_registered} ->
+	    ok
+    after 1000 ->
+	    ?t:fail(gen_statem_started)
+    end,
+    unregister(armitage),
+
+    %% Make sure gen_statem:enter_loop does not accept {global,Name}
+    %% when it's another process than the calling one which is
+    %% registered under that name
+    global:register_name(armitage, self()),
+    {ok,Pid6b} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,global]),
+    receive
+	{'EXIT',Pid6b,process_not_registered_globally} ->
+	    ok
+    after 1000 ->
+	    ?t:fail(gen_statem_started)
+    end,
+    global:unregister_name(armitage),
+
+    dummy_via:register_name(armitage, self()),
+    {ok,Pid6c} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon,via]),
+    receive
+	{'EXIT',Pid6c,{process_not_registered_via,dummy_via}} ->
+	    ok
+    after 1000 ->
+	    ?t:fail(
+	      {gen_statem_started,
+	       process_info(self(), messages)})
+    end,
+    dummy_via:unregister_name(armitage),
+
+    process_flag(trap_exit, OldFlag),
+    ok = verify_empty_msgq().
+
+enter_loop(Reg1, Reg2) ->
+    process_flag(trap_exit, true),
+    case Reg1 of
+	local -> register(armitage, self());
+	global -> global:register_name(armitage, self());
+	via -> dummy_via:register_name(armitage, self());
+	anon -> ignore
+    end,
+    proc_lib:init_ack({ok, self()}),
+    case Reg2 of
+	local ->
+	    gen_statem:enter_loop(?MODULE, [], state0, [], {local,armitage});
+	global ->
+	    gen_statem:enter_loop(?MODULE, [], state0, [], {global,armitage});
+	via ->
+	    gen_statem:enter_loop(?MODULE, [], state0, [],
+			       {via, dummy_via, armitage});
+	anon ->
+	    gen_statem:enter_loop(?MODULE, [], state0, [])
+    end.
+
+%%
+%% Functionality check
+%%
+
+wfor(Msg) ->
+    receive
+	Msg -> ok
+    after 5000 ->
+	    error(timeout)
+    end.
+
+
+stop_it(STM) ->
+    stopped = gen_statem:call(STM, stop),
+    check_stopped(STM).
+
+
+check_stopped(STM) ->
+    Call = there_you_are,
+    {_,{gen_statem,call,[_,Call,infinity]}} =
+	?EXPECT_FAILURE(gen_statem:call(STM, Call), Reason),
+    ok.
+
+
+do_func_test(STM) ->
+    ok = gen_statem:cast(STM, {'alive?',self()}),
+    wfor(yes),
+    ok = do_connect(STM),
+    ok = gen_statem:cast(STM, {'alive?',self()}),
+    wfor(yes),
+    ?t:do_times(3, ?MODULE, do_msg, [STM]),
+    ok = gen_statem:cast(STM, {'alive?',self()}),
+    wfor(yes),
+    ok = do_disconnect(STM),
+    ok = gen_statem:cast(STM, {'alive?',self()}),
+    wfor(yes),
+    ok.
+
+
+do_connect(STM) ->
+    check_state(STM, idle),
+    gen_statem:cast(STM, {connect,self()}),
+    wfor(accept),
+    check_state(STM, wfor_conf),
+    gen_statem:cast(STM, confirm),
+    check_state(STM, connected),
+    ok.
+
+do_msg(STM) ->
+    check_state(STM, connected),
+    R = make_ref(),
+    ok = gen_statem:cast(STM, {msg,self(),R}),
+    wfor({ack,R}).
+
+
+do_disconnect(STM) ->
+    ok = gen_statem:cast(STM, disconnect),
+    check_state(STM, idle).
+
+check_state(STM, State) ->
+    case gen_statem:call(STM, get) of
+	{state, State, _} -> ok
+    end.
+
+do_sync_func_test(STM) ->
+    yes = gen_statem:call(STM, 'alive?'),
+    ok = do_sync_connect(STM),
+    yes = gen_statem:call(STM, 'alive?'),
+    ?t:do_times(3, ?MODULE, do_sync_msg, [STM]),
+    yes = gen_statem:call(STM, 'alive?'),
+    ok = do_sync_disconnect(STM),
+    yes = gen_statem:call(STM, 'alive?'),
+    check_state(STM, idle),
+    ok = gen_statem:call(STM, {timeout,200}),
+    yes = gen_statem:call(STM, 'alive?'),
+    check_state(STM, idle),
+    ok.
+
+
+do_sync_connect(STM) ->
+    check_state(STM, idle),
+    accept = gen_statem:call(STM, connect),
+    check_state(STM, wfor_conf),
+    yes = gen_statem:call(STM, confirm),
+    check_state(STM, connected),
+    ok.
+
+do_sync_msg(STM) ->
+    check_state(STM, connected),
+    R = make_ref(),
+    {ack,R} = gen_statem:call(STM, {msg,R}),
+    ok.
+
+do_sync_disconnect(STM) ->
+    yes = gen_statem:call(STM, disconnect),
+    check_state(STM, idle).
+
+
+verify_empty_msgq() ->
+    receive after 500 -> ok end,
+    [] = ?t:messages_get(),
+    ok.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%
+%% The State Machine
+%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+init(ignore) ->
+    ignore;
+init(stop) ->
+    {stop,stopped};
+init(stop_shutdown) ->
+    {stop,shutdown};
+init(sleep) ->
+    ?t:sleep(1000),
+    {ok,idle,data};
+init(hiber) ->
+    {ok,hiber_idle,[]};
+init(hiber_now) ->
+    {ok,hiber_idle,[],[hibernate]};
+init({state_data, StateData}) ->
+    {ok,idle,StateData};
+init(_) ->
+    {ok,idle,state_data}.
+
+terminate(_, _State, crash_terminate) ->
+    exit({crash,terminate});
+terminate({From,stopped}, State, _Data) ->
+    From ! {self(),{stopped,State}},
+    ok;
+terminate(_Reason, _State, _Data) ->
+    ok.
+
+
+%% State functions
+
+idle(cast, {connect,Pid}, _, _, Data) ->
+    Pid ! accept,
+    {wfor_conf,Data};
+idle({call,From}, connect, _, _, Data) ->
+    {wfor_conf,Data,[{reply,From,accept}]};
+idle(cast, badreturn, _, _, _Data) ->
+    badreturn;
+idle({call,_From}, badreturn, _, _, _Data) ->
+    badreturn;
+idle({call,From}, {delayed_answer,T}, _, _, _Data) ->
+    receive
+    after T ->
+	    [{reply,From,delayed}]
+    end;
+idle({call,From}, {timeout,Time}, _, State, _Data) ->
+    {timeout, {From,Time}, [{timeout,Time,State}]};
+idle(Type, Content, PrevState, State, Data) ->
+    case handle_common_events(Type, Content, PrevState, State, Data) of
+	[] ->
+	    case Type of
+		{call,From} ->
+		    {State,Data,[{reply,From,'eh?'}]};
+		_ ->
+		    {State,Data,
+		     [{stop,{unexpected,State,PrevState,Type,Content}}]}
+	    end;
+	Result ->
+	    Result
+    end.
+
+timeout(timeout, idle, idle, timeout, {From,Time}) ->
+    TRef2 = erlang:start_timer(Time, self(), ok),
+    TRefC1 = erlang:start_timer(Time, self(), cancel1),
+    TRefC2 = erlang:start_timer(Time, self(), cancel2),
+    {timeout2,
+     {From, Time, TRef2},
+     [{cancel_timer, TRefC1},
+      {insert_event,internal,{cancel_timer,TRefC2}}]};
+timeout(_, _, _, _, Data) ->
+    {Data}.
+
+timeout2(
+  internal, {cancel_timer,TRefC2}, timeout, _, {From,Time,TRef2}) ->
+    Time4 = Time * 4,
+    receive after Time4 -> ok end,
+    {timeout3,{From,TRef2},[{cancel_timer,TRefC2}]};
+timeout2(_, _, _, _, Data) ->
+    {Data}.
+
+timeout3(info, {timeout,TRef2,Result}, _, _, {From,TRef2}) ->
+    {idle,state,[{reply,From,Result}]};
+timeout3(_, _, _, _, Data) ->
+    {Data}.
+
+wfor_conf({call,From}, confirm, _, _, Data) ->
+    {connected,Data,[{reply,From,yes}]};
+wfor_conf(cast, confirm, _, _, Data) ->
+    {connected,Data};
+wfor_conf(Type, Content, PrevState, State, Data) ->
+    case handle_common_events(Type, Content, PrevState, State, Data) of
+	[] ->
+	    case Type of
+		{call,From} ->
+		    {idle,Data,[{reply,From,'eh?'}]};
+		_ ->
+		    {Data}
+	    end;
+	Result ->
+	    Result
+    end.
+
+connected({call,From}, {msg,Ref}, _, State, Data) ->
+    {State,Data,[{reply,From,{ack,Ref}}]};
+connected(cast, {msg,From,Ref}, _, _, _Data) ->
+    From ! {ack,Ref},
+    {};
+connected({call,From}, disconnect, _, _, Data) ->
+    {idle,Data,[{reply,From,yes}]};
+connected(cast, disconnect, _, _, Data) ->
+    {idle,Data};
+connected(Type, Content, PrevState, State, Data) ->
+    case handle_common_events(Type, Content, PrevState, State, Data) of
+	[] ->
+	    case Type of
+		{call,From} ->
+		    [{reply,From,'eh?'}];
+		_ ->
+		    {Data}
+	    end;
+	Result ->
+	    Result
+    end.
+
+state0({call,From}, stop, _, State, Data) ->
+    {State,Data,
+     [{reply,From,stopped},
+      {stop,normal}]};
+state0(Type, Content, PrevState, State, Data) ->
+    case handle_common_events(Type, Content, PrevState, State, Data) of
+	[] ->
+	    {Data};
+	Result ->
+	    Result
+    end.
+
+hiber_idle({call,From}, 'alive?', _, _, _) ->
+    [{reply,From,'alive!'}];
+hiber_idle({call,From}, hibernate_sync, _, _, Data) ->
+    {hiber_wakeup,Data,
+     [{reply,From,hibernating},
+      hibernate]};
+hiber_idle(info, hibernate_later, _, State, _) ->
+    Tref = erlang:start_timer(1000, self(), hibernate),
+    {State,Tref};
+hiber_idle(info, hibernate_now, _, State, Data) ->
+    {State,Data,[hibernate]};
+hiber_idle(info, {timeout,Tref,hibernate}, _, State, Tref) ->
+    {State,[],
+     [hibernate]};
+hiber_idle(cast, hibernate_async, _, _, Data) ->
+    {hiber_wakeup,Data,
+     [hibernate]};
+hiber_idle(Type, Content, PrevState, State, Data) ->
+    case handle_common_events(Type, Content, PrevState, State, Data) of
+	[] ->
+	    {Data};
+	Result ->
+	    Result
+    end.
+
+hiber_wakeup({call,From}, wakeup_sync, _, _, Data) ->
+    {hiber_idle,Data,[{reply,From,good_morning}]};
+hiber_wakeup({call,From}, snooze_sync, _, State, Data) ->
+    {State,Data,
+     [{reply,From,please_just_five_more},
+      hibernate]};
+hiber_wakeup(cast, wakeup_async, _, _, Data) ->
+    {hiber_idle,Data};
+hiber_wakeup(cast, snooze_async, _, _, _Data) ->
+    [hibernate];
+hiber_wakeup(Type, Content, PrevState, State, Data) ->
+    case handle_common_events(Type, Content, PrevState, State, Data) of
+	[] ->
+	    {Data};
+	Result ->
+	    Result
+    end.
+
+
+handle_common_events({call,From}, get, _, State, Data) ->
+    [{reply,From,{state,State,Data}}];
+handle_common_events(cast, {get,Pid}, _, State, Data) ->
+    Pid ! {state,State,Data},
+    {};
+handle_common_events({call,From}, stop, _, _, _) ->
+    [{reply,From,stopped},
+     {stop,normal}];
+handle_common_events(cast, stop, _, State, Data) ->
+    {State,Data,
+     [{stop,normal}]};
+handle_common_events({call,From}, {stop,Reason}, _, State, Data) ->
+    {State,Data,
+     [{reply,From,stopped},
+      {stop,Reason}]};
+handle_common_events(cast, {stop,Reason}, _, _, _) ->
+     [{stop,Reason}];
+handle_common_events({call,From}, 'alive?', _, State, Data) ->
+    {State,Data,
+     [{reply,From,yes}]};
+handle_common_events(cast, {'alive?',Pid}, _, State, Data) ->
+    Pid ! yes,
+    {State,Data};
+handle_common_events(_, _, _, _, _) ->
+    [].
+
+code_change(_OldVsn, State, StateData, _Extra) ->
+    {ok,State,StateData}.
+
+format_status(terminate, [_Pdict,State,StateData]) ->
+    {formatted,State,StateData};
+format_status(normal, [_Pdict,_State,_StateData]) ->
+    [format_status_called].
-- 
cgit v1.2.3


From a07f6e35c3adb6e1536a63cc8137f48f64e2f6f7 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 9 Feb 2016 11:45:55 +0100
Subject: Correct grammar errors found by Magnus Henoch

---
 lib/stdlib/doc/src/gen_statem.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 885021f61c..83d1f1e9e6 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -96,10 +96,10 @@ erlang:'!'            -----> Module:State/5
       </seealso> will be called.
       If you use <c>handle_event</c> as a
       <seealso marker="#type-state">state</seealso> and later
-      decides to use non-atom states you will then have to
+      decide to use non-atom states you will then have to
       rewrite your code to stop using that state.
     </p>
-    <p>When the using an atom-only
+    <p>When using an atom-only
       <seealso marker="#type-state">State</seealso>
       it becomes fairly obvious in the implementation code
       which events are handled in which state
-- 
cgit v1.2.3


From 3815de0c7337058991066454c246587c0dbaa664 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 16 Feb 2016 10:51:39 +0100
Subject: Change to {next_state,...} and {stop,...} return format

---
 lib/stdlib/doc/src/gen_statem.xml    |  75 +++++++++++-------
 lib/stdlib/src/gen_statem.erl        | 103 +++++++++++++++---------
 lib/stdlib/test/gen_statem_SUITE.erl | 148 ++++++++++++++++++-----------------
 3 files changed, 191 insertions(+), 135 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 83d1f1e9e6..f7ce0f61ae 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -397,23 +397,6 @@ erlang:'!'            -----> Module:State/5
       <name name="state_operation" />
       <desc>
 	<taglist>
-	  <tag>
-	   <c>{reply,<anno>Client</anno>,<anno>Reply</anno>}</c>
-	  </tag>
-	  <item>Reply to a client that called
-	    <seealso marker="#call/2"><c>call/2</c></seealso>.
-            <c><anno>Client</anno></c> must be the term from the
-	    <seealso marker="#type-event_type">
-	      <c>{call,<anno>Client</anno>}</c>
-	    </seealso> argument to the
-	    <seealso marker="#state_function">state function</seealso>.
-	  </item>
-	  <tag><c>{stop,<anno>Reason</anno>}</c></tag>
-	  <item>The gen_statem will call
-	    <seealso marker="#Module:terminate/3">
-	      <c>Module:terminate/3</c>
-	    </seealso> with <c><anno>Reason</anno></c> and terminate.
-	  </item>
 	  <tag>
 	    <c>
 	      {insert_event,<anno>EventType</anno>,<anno>EventContent</anno>}
@@ -471,6 +454,24 @@ erlang:'!'            -----> Module:State/5
 	</taglist>
       </desc>
     </datatype>
+    <datatype>
+      <name name="reply_operation" />
+      <desc>
+	<taglist>
+	  <tag>
+	   <c>{reply,<anno>Client</anno>,<anno>Reply</anno>}</c>
+	  </tag>
+	  <item>Reply to a client that called
+	    <seealso marker="#call/2"><c>call/2</c></seealso>.
+            <c><anno>Client</anno></c> must be the term from the
+	    <seealso marker="#type-event_type">
+	      <c>{call,<anno>Client</anno>}</c>
+	    </seealso> argument to the
+	    <seealso marker="#state_function">state function</seealso>.
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
   </datatypes>
 
   <funcs>
@@ -867,22 +868,39 @@ erlang:'!'            -----> Module:State/5
 	  <seealso marker="#type-event_type">event_type()</seealso>
 	</v>
 	<v>EventContent = term()</v>
-	<v>Result = {NewState,NewStateData,StateOps}</v>
-	<v>&nbsp;&nbsp;| {NewState,NewStateData}</v>
-	<d>&nbsp;&nbsp;The same as <c>{NewState,NewStateData,[]}</c></d>
-	<v>&nbsp;&nbsp;| {NewStateData}</v>
-	<d>&nbsp;&nbsp;The same as <c>{State,NewStateData,[retry]}</c></d>
-	<v>&nbsp;&nbsp;| {}</v>
-	<d>&nbsp;&nbsp;The same as <c>{State,StateData,[]}</c></d>
-	<v>&nbsp;&nbsp;| StateOps</v>
-	<d>&nbsp;&nbsp;The same as <c>{State,StateData,StateOps}</c></d>
-
+	<v>Result = {stop,Reason,NewStateData}</v>
+	<d>&nbsp;&nbsp;The same as <c>{stop,Reason,[],NewStateData}</c></d>
+	<v>&nbsp;&nbsp;| {stop,Reason,Reply,NewStateData}</v>
+	<d>&nbsp;&nbsp;The same as
+	  <c>{stop,Reason,[Reply],NewStateData}</c>
+	</d>
+	<v>&nbsp;&nbsp;| {stop,Reason,Replies,NewStateData}</v>
+	<d>&nbsp;&nbsp;The gen_statem will first send all
+	  <c>Replies</c> and then call
+	    <seealso marker="#Module:terminate/3">
+	      <c>Module:terminate/3</c>
+	    </seealso> with <c>Reason</c> and terminate.
+	</d>
+	<v>&nbsp;&nbsp;| {next_state,NewState,NewStateData}</v>
+	<d>&nbsp;&nbsp;The same as
+	  <c>{next_state,NewState,NewStateData,NewStateData,[]}</c>
+	</d>
+	<v>&nbsp;&nbsp;| {next_state,NewState,NewStateData,StateOps}</v>
+	<d>&nbsp;&nbsp;The gen_statem will do a state transition to
+	  <c>NewState</c> (which may be the same as <c>State</c>)
+	  and execute all <c>StateOps</c>
+	</d>
+	<v>Reason = term()</v>
 	<v>PrevState = State = NewState =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
 	<v>StateData = NewStateData =
 	  <seealso marker="#type-state_data">state_data()</seealso>
 	</v>
+	<v>Reply =
+	  <seealso marker="#type-reply_operation">reply_operation()</seealso>
+	</v>
+	<v>Replies = [Reply]</v>
 	<v>StateOps =
 	  [<seealso marker="#type-state_op">state_op()</seealso>]
 	</v>
@@ -898,7 +916,8 @@ erlang:'!'            -----> Module:State/5
 	  from this or from any other
 	  <seealso marker="#state_function">state function</seealso>
 	  by returning with <c>{reply,Client,Reply}</c> in
-	  <seealso marker="#type-state_op">StateOps</seealso>
+	  <seealso marker="#type-state_op">StateOps</seealso>, in
+	  <seealso marker="#type-reply_operation">Replies</seealso>
 	  or by calling
 	  <seealso marker="#reply/2">
 	    <c>gen_statem:reply(Client, Reply)</c>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 9bb5ed013b..7c3cd8c2f3 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -74,14 +74,13 @@
 	{'retry', Retry :: boolean()} |
 	'hibernate' | % Hibernate the server instead of going into receive
 	{'hibernate', Hibernate :: boolean()} |
+	(Timeout :: timeout()) | % {timeout,Timeout}
 	{'timeout', % Generate a ('timeout', Msg, ...) event after Time
 	 Time :: timeout(), Msg :: term()}.
 -type state_operation() ::
 	%% These can occur multiple times and are executed in order
 	%% of appearence in the state_op() list
-	{'reply', % Reply to a client
-	 Client :: client(), Reply :: term()} |
-	{'stop', Reason :: term()} | % Stop the server
+	reply_operation() |
 	{'insert_event', % Insert event as the next to handle
 	 EventType :: event_type(),
 	 EventContent :: term()} |
@@ -95,6 +94,9 @@
 	 MonitorRef :: reference()} |
 	{'unlink', % Unlink and clean up mess(ages)
 	 Id :: pid() | port()}.
+-type reply_operation() ::
+	{'reply', % Reply to a client
+	 Client :: client(), Reply :: term()}.
 
 %% The state machine init function.  It is called only once and
 %% the server is not running until this function has returned
@@ -122,12 +124,20 @@
 	    PrevState :: state(),
 	    State :: state(), % Current state
 	    StateData :: state_data()) ->
-    [state_op()] | % {State,StateData,[state_op()]}
-    {} | % {State,StateData,[]}
-    {NewStateData :: state_data()} | % {State,NewStateData,[retry]}
-    {NewState :: state(),
-     NewStateData :: state_data()} | % {NewState,NewStateData,[]}
-    {NewState :: state(), NewStateData :: state_data(), [state_op()]}.
+    {stop, % Stop the server
+     Reason :: term(),
+     NewStateData :: state_data()} |
+    {stop, % Stop the server
+     Reason :: term(),
+     [reply_operation()] | reply_operation(),
+     NewStateData :: state_data()} |
+    {next_state, % {next_state,NewState,NewStateData,[]}
+     NewState :: state(),
+     NewStateData :: state_data()} |
+    {next_state, % State transition, maybe to the same state
+     NewState :: state(),
+     NewStateData :: state_data(),
+     [state_op()] | state_op()}.
 
 %% Clean up before the server terminates.
 -callback terminate(
@@ -679,35 +689,42 @@ loop_events(
 	    terminate(Class, Reason, Stacktrace, Debug, S, Q)
     end.
 
-%% Interprete all callback return value variants
-loop_event_result(
-  Parent, Debug,
-  #{state := State, state_data := StateData} = S,
-  Events, Event, Result) ->
+%% Interpret all callback return value variants
+loop_event_result(Parent, Debug, S, Events, Event, Result) ->
     case Result of
-	{} -> % Ignore
-	    loop_event_state_ops(
-	      Parent, Debug, S, Events, Event,
-	      State, StateData, []);
-	{NewStateData} -> % Retry
-	    loop_event_state_ops(
-	      Parent, Debug, S, Events, Event,
-	      State, NewStateData, [retry]);
-	{NewState,NewStateData} -> % Consume
+	{stop,Reason,NewStateData} ->
+	    terminate(
+	      Reason, Debug,
+	      S#{state_data := NewStateData},
+	      [Event|Events]);
+	{stop,Reason,Reply,NewStateData} ->
+	    NewS = S#{state_data := NewStateData},
+	    Q = [Event|Events],
+	    Replies =
+		if
+		    is_list(Reply) ->
+			Reply;
+		    true ->
+			[Reply]
+		end,
+	    BadReplies =
+		reply_then_terminate(Reason, Debug, NewS, Q, Replies),
+	    %% Since it returned Replies was bad
+	    terminate(
+	      {bad_return_value,{stop,Reason,BadReplies,NewStateData}},
+	      Debug, NewS, Q);
+	{next_state,NewState,NewStateData} ->
 	    loop_event_state_ops(
 	      Parent, Debug, S, Events, Event,
 	      NewState, NewStateData, []);
-	{NewState,NewStateData,StateOps} when is_list(StateOps) ->
+	{next_state,NewState,NewStateData,StateOps}
+	  when is_list(StateOps) ->
 	    loop_event_state_ops(
 	      Parent, Debug, S, Events, Event,
 	      NewState, NewStateData, StateOps);
-	StateOps when is_list(StateOps) -> % Stay in state
-	    loop_event_state_ops(
-	      Parent, Debug, S, Events, Event,
-	      State, StateData, StateOps);
-	BadReturn ->
+	_ ->
 	    terminate(
-	      {bad_return_value,BadReturn}, Debug, S, [Event|Events])
+	      {bad_return_value,Result}, Debug, S, [Event|Events])
     end.
 
 loop_event_state_ops(
@@ -750,7 +767,8 @@ loop_event_state_ops(
 				%% Pretend the timeout has just been received
 				{undefined,Q3 ++ [{timeout,Msg}]};
 			    {timeout,Time,Msg} ->
-				{erlang:start_timer(Time, self(), Msg),Q3}
+				{erlang:start_timer(Time, self(), Msg),
+				 Q3}
 			end,
 		    loop_events(
 		      Parent, NewDebug,
@@ -820,11 +838,8 @@ process_state_operations([], Debug, _S, Q, P) ->
 process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
     case Operation of
 	{reply,{_To,_Tag}=Client,Reply} ->
-	    reply(Client, Reply),
-	    NewDebug = sys_debug(Debug, S, {out,Reply,Client}),
+	    NewDebug = do_reply(Debug, S, Client, Reply),
 	    process_state_operations(Operations, NewDebug, S, Q, P);
-	{stop,Reason} ->
-	    [Reason,Debug];
 	{insert_event,Type,Content} ->
 	    case event_type(Type) of
 		true ->
@@ -854,6 +869,22 @@ process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
 	    end
     end.
 
+reply_then_terminate(Reason, Debug, S, Q, []) ->
+    terminate(Reason, Debug, S, Q);
+reply_then_terminate(Reason, Debug, S, Q, [R|Rs] = RRs) ->
+    case R of
+	{reply,{_To,_Tag}=Client,Reply} ->
+	    NewDebug = do_reply(Debug, S, Client, Reply),
+	    reply_then_terminate(Reason, NewDebug, S, Q, Rs);
+	_ ->
+	    RRs % bad_return_value
+    end.
+
+do_reply(Debug, S, Client, Reply) ->
+    reply(Client, Reply),
+    sys_debug(Debug, S, {out,Reply,Client}).
+
+
 %% Remove oldest matching event from the queue(s)
 remove_event(RemoveFun, Q, P) ->
     try
@@ -928,7 +959,7 @@ remove_fun({unlink,Id}) ->
 	    end
     catch
 	Class:Reason ->
-	    {Class,Reason,erlang:get_stacktrace()}
+	    [Class,Reason,erlang:get_stacktrace()]
     end;
 remove_fun(_) ->
     undefined.
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 342be32acb..51e08f5ec1 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1068,29 +1068,30 @@ terminate(_Reason, _State, _Data) ->
 
 idle(cast, {connect,Pid}, _, _, Data) ->
     Pid ! accept,
-    {wfor_conf,Data};
+    {next_state,wfor_conf,Data};
 idle({call,From}, connect, _, _, Data) ->
-    {wfor_conf,Data,[{reply,From,accept}]};
+    {next_state,wfor_conf,Data,[{reply,From,accept}]};
 idle(cast, badreturn, _, _, _Data) ->
     badreturn;
 idle({call,_From}, badreturn, _, _, _Data) ->
     badreturn;
-idle({call,From}, {delayed_answer,T}, _, _, _Data) ->
+idle({call,From}, {delayed_answer,T}, _, State, Data) ->
     receive
     after T ->
-	    [{reply,From,delayed}]
+	    {next_state,State,Data,
+	     [{reply,From,delayed}]}
     end;
 idle({call,From}, {timeout,Time}, _, State, _Data) ->
-    {timeout, {From,Time}, [{timeout,Time,State}]};
+    {next_state,timeout,{From,Time},
+     [{timeout,Time,State}]};
 idle(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
-	[] ->
+	undefined ->
 	    case Type of
 		{call,From} ->
-		    {State,Data,[{reply,From,'eh?'}]};
+		    {next_state,State,Data,[{reply,From,'eh?'}]};
 		_ ->
-		    {State,Data,
-		     [{stop,{unexpected,State,PrevState,Type,Content}}]}
+		    {stop,{unexpected,State,PrevState,Type,Content},Data}
 	    end;
 	Result ->
 	    Result
@@ -1100,146 +1101,151 @@ timeout(timeout, idle, idle, timeout, {From,Time}) ->
     TRef2 = erlang:start_timer(Time, self(), ok),
     TRefC1 = erlang:start_timer(Time, self(), cancel1),
     TRefC2 = erlang:start_timer(Time, self(), cancel2),
-    {timeout2,
-     {From, Time, TRef2},
+    {next_state,timeout2,{From,Time,TRef2},
      [{cancel_timer, TRefC1},
       {insert_event,internal,{cancel_timer,TRefC2}}]};
-timeout(_, _, _, _, Data) ->
-    {Data}.
+timeout(_, _, _, State, Data) ->
+    {next_state,State,Data}.
 
 timeout2(
   internal, {cancel_timer,TRefC2}, timeout, _, {From,Time,TRef2}) ->
     Time4 = Time * 4,
     receive after Time4 -> ok end,
-    {timeout3,{From,TRef2},[{cancel_timer,TRefC2}]};
-timeout2(_, _, _, _, Data) ->
-    {Data}.
+    {next_state,timeout3,{From,TRef2},
+     [{cancel_timer,TRefC2}]};
+timeout2(_, _, _, State, Data) ->
+    {next_state,State,Data}.
 
 timeout3(info, {timeout,TRef2,Result}, _, _, {From,TRef2}) ->
-    {idle,state,[{reply,From,Result}]};
-timeout3(_, _, _, _, Data) ->
-    {Data}.
+    {next_state,idle,state,
+     [{reply,From,Result}]};
+timeout3(_, _, _, State, Data) ->
+    {next_state,State,Data}.
 
 wfor_conf({call,From}, confirm, _, _, Data) ->
-    {connected,Data,[{reply,From,yes}]};
+    {next_state,connected,Data,
+     [{reply,From,yes}]};
 wfor_conf(cast, confirm, _, _, Data) ->
-    {connected,Data};
+    {next_state,connected,Data};
 wfor_conf(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
-	[] ->
+	undefined ->
 	    case Type of
 		{call,From} ->
-		    {idle,Data,[{reply,From,'eh?'}]};
+		    {next_state,idle,Data,
+		     [{reply,From,'eh?'}]};
 		_ ->
-		    {Data}
+		    {next_state,State,Data}
 	    end;
 	Result ->
 	    Result
     end.
 
 connected({call,From}, {msg,Ref}, _, State, Data) ->
-    {State,Data,[{reply,From,{ack,Ref}}]};
-connected(cast, {msg,From,Ref}, _, _, _Data) ->
+    {next_state,State,Data,
+     [{reply,From,{ack,Ref}}]};
+connected(cast, {msg,From,Ref}, _, State, Data) ->
     From ! {ack,Ref},
-    {};
+    {next_state,State,Data};
 connected({call,From}, disconnect, _, _, Data) ->
-    {idle,Data,[{reply,From,yes}]};
+    {next_state,idle,Data,
+     [{reply,From,yes}]};
 connected(cast, disconnect, _, _, Data) ->
-    {idle,Data};
+    {next_state,idle,Data};
 connected(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
-	[] ->
+	undefined ->
 	    case Type of
 		{call,From} ->
-		    [{reply,From,'eh?'}];
+		    {next_state,State,Data,
+		     [{reply,From,'eh?'}]};
 		_ ->
-		    {Data}
+		    {next_state,State,Data}
 	    end;
 	Result ->
 	    Result
     end.
 
-state0({call,From}, stop, _, State, Data) ->
-    {State,Data,
-     [{reply,From,stopped},
-      {stop,normal}]};
+state0({call,From}, stop, _, _, Data) ->
+    {stop,normal,[{reply,From,stopped}],Data};
 state0(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
-	[] ->
-	    {Data};
+	undefined ->
+	    {next_state,State,Data};
 	Result ->
 	    Result
     end.
 
-hiber_idle({call,From}, 'alive?', _, _, _) ->
-    [{reply,From,'alive!'}];
+hiber_idle({call,From}, 'alive?', _, State, Data) ->
+    {next_state,State,Data,
+     [{reply,From,'alive!'}]};
 hiber_idle({call,From}, hibernate_sync, _, _, Data) ->
-    {hiber_wakeup,Data,
+    {next_state,hiber_wakeup,Data,
      [{reply,From,hibernating},
       hibernate]};
 hiber_idle(info, hibernate_later, _, State, _) ->
     Tref = erlang:start_timer(1000, self(), hibernate),
-    {State,Tref};
+    {next_state,State,Tref};
 hiber_idle(info, hibernate_now, _, State, Data) ->
-    {State,Data,[hibernate]};
+    {next_state,State,Data,
+     [hibernate]};
 hiber_idle(info, {timeout,Tref,hibernate}, _, State, Tref) ->
-    {State,[],
+    {next_state,State,[],
      [hibernate]};
 hiber_idle(cast, hibernate_async, _, _, Data) ->
-    {hiber_wakeup,Data,
+    {next_state,hiber_wakeup,Data,
      [hibernate]};
 hiber_idle(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
-	[] ->
-	    {Data};
+	undefined ->
+	    {next_state,State,Data};
 	Result ->
 	    Result
     end.
 
 hiber_wakeup({call,From}, wakeup_sync, _, _, Data) ->
-    {hiber_idle,Data,[{reply,From,good_morning}]};
+    {next_state,hiber_idle,Data,
+     [{reply,From,good_morning}]};
 hiber_wakeup({call,From}, snooze_sync, _, State, Data) ->
-    {State,Data,
+    {next_state,State,Data,
      [{reply,From,please_just_five_more},
       hibernate]};
 hiber_wakeup(cast, wakeup_async, _, _, Data) ->
-    {hiber_idle,Data};
-hiber_wakeup(cast, snooze_async, _, _, _Data) ->
-    [hibernate];
+    {next_state,hiber_idle,Data};
+hiber_wakeup(cast, snooze_async, _, State, Data) ->
+    {next_state,State,Data,
+     [hibernate]};
 hiber_wakeup(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
-	[] ->
-	    {Data};
+	undefined ->
+	    {next_state,State,Data};
 	Result ->
 	    Result
     end.
 
 
 handle_common_events({call,From}, get, _, State, Data) ->
-    [{reply,From,{state,State,Data}}];
+    {next_state,State,Data,
+     [{reply,From,{state,State,Data}}]};
 handle_common_events(cast, {get,Pid}, _, State, Data) ->
     Pid ! {state,State,Data},
-    {};
-handle_common_events({call,From}, stop, _, _, _) ->
-    [{reply,From,stopped},
-     {stop,normal}];
-handle_common_events(cast, stop, _, State, Data) ->
-    {State,Data,
-     [{stop,normal}]};
-handle_common_events({call,From}, {stop,Reason}, _, State, Data) ->
-    {State,Data,
-     [{reply,From,stopped},
-      {stop,Reason}]};
-handle_common_events(cast, {stop,Reason}, _, _, _) ->
-     [{stop,Reason}];
+    {next_state,State,Data};
+handle_common_events({call,From}, stop, _, _, Data) ->
+    {stop,normal,[{reply,From,stopped}],Data};
+handle_common_events(cast, stop, _, _, Data) ->
+    {stop,normal,Data};
+handle_common_events({call,From}, {stop,Reason}, _, _, Data) ->
+    {stop,Reason,{reply,From,stopped},Data};
+handle_common_events(cast, {stop,Reason}, _, _, Data) ->
+     {stop,Reason,Data};
 handle_common_events({call,From}, 'alive?', _, State, Data) ->
-    {State,Data,
+    {next_state,State,Data,
      [{reply,From,yes}]};
 handle_common_events(cast, {'alive?',Pid}, _, State, Data) ->
     Pid ! yes,
-    {State,Data};
+    {next_state,State,Data};
 handle_common_events(_, _, _, _, _) ->
-    [].
+    undefined.
 
 code_change(_OldVsn, State, StateData, _Extra) ->
     {ok,State,StateData}.
-- 
cgit v1.2.3


From 99d48f5921f95073c8e46280494746b0e1a2c375 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 16 Feb 2016 17:54:15 +0100
Subject: Implement option callback_mode

---
 lib/stdlib/doc/src/gen_statem.xml    | 272 ++++++++++++++++++++++-------------
 lib/stdlib/src/gen_statem.erl        | 134 +++++++++++------
 lib/stdlib/test/gen_statem_SUITE.erl | 242 ++++++++++++++++++++++---------
 3 files changed, 439 insertions(+), 209 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index f7ce0f61ae..f608e10469 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -31,8 +31,15 @@
   <module>gen_statem</module>
   <modulesummary>Generic State Machine Behaviour</modulesummary>
   <description>
-    <p>A behaviour module for implementing a state machine, primarily
-      a finite state machine, but an infinite state space is possible.
+    <p>A behaviour module for implementing a state machine.
+      Two callback modes are supported.  One for a finite state
+      machine like <seealso marker="gen_fsm">gen_fsm</seealso>
+      that require the state to be an atom and use that state as
+      the name of the callback function for a particular state,
+      and one without restriction on the state that use the same
+      callback function for all states.
+    </p>
+    <p>
       A generic state machine process (gen_statem) implemented using
       this module will have a standard set of interface functions
       and include functionality for tracing and error reporting.
@@ -55,7 +62,7 @@ gen_statem:stop       -----> Module:terminate/2
 gen_statem:call
 gen_statem:cast
 erlang:send
-erlang:'!'            -----> Module:State/5
+erlang:'!'            -----> Module:StateName/5
                              Module:handle_event/5
 
 -                     -----> Module:terminate/3
@@ -75,47 +82,39 @@ erlang:'!'            -----> Module:State/5
     <p>The "<em>state function</em>" for a specific
       <seealso marker="#type-state">state</seealso>
       in a gen_statem is the callback function that is called
-      for all events in this state.
-      An event can can be postponed causing it to be retried
-      after the state has changed, or more precisely;
-      after a state change all postponed events are retried
-      in the new state.
+      for all events in this state, and is selected depending on
+      <seealso marker="#type-callback_mode">callback_mode</seealso>
+      that the implementation selects during gen_statem init.
     </p>
-    <p>The state machine
-      <seealso marker="#type-state"><c>State</c></seealso>
-      is normally an atom in which case the
-      <seealso marker="#state_function">state function</seealso>
-      that will be called is
-      <seealso marker="#Module:State/5"><c>Module:State/5</c></seealso>.
-      For a
-      <seealso marker="#type-state"><c>State</c></seealso>
-      that is <em>not</em> an atom the
-      <seealso marker="#state_function">state function</seealso>
-      <seealso marker="#Module:handle_event/5">
-	<c>Module:handle_event/5</c>
-      </seealso> will be called.
-      If you use <c>handle_event</c> as a
-      <seealso marker="#type-state">state</seealso> and later
-      decide to use non-atom states you will then have to
-      rewrite your code to stop using that state.
+    <p>When
+      <seealso marker="#type-callback_mode">callback_mode</seealso>
+      is <c>state_functions</c> the state has to be an atom and
+      is used as the state function name.
+      See
+      <seealso marker="#Module:StateName/5">
+        <c>Module:StateName/5</c>
+      </seealso>.
+      This naturally collects all code for a specific state
+      in one function and hence dispatches on state first.
     </p>
-    <p>When using an atom-only
-      <seealso marker="#type-state">State</seealso>
-      it becomes fairly obvious in the implementation code
-      which events are handled in which state
-      since there are different callback functions for different states.
+    <p>When
+      <seealso marker="#type-callback_mode">callback_mode</seealso>
+      is <c>handle_event_function</c> the state can be any term
+      and the state function name is
+      <seealso marker="#Module:handle_event/5">
+        <c>Module:handle_event/5</c>
+      </seealso>.
+      This makes it easy to dispatch on state or on event as
+      you like but you will have to implement it.
+      Also be careful about which events you handle in which
+      states so you do not accidentally postpone one event
+      forever creating an infinite busy loop.
     </p>
     <p>
-      When using a non-atom <seealso marker="#type-state">State</seealso>
-      all events are handled in the callback function
-      <seealso marker="#Module:handle_event/5">
-	<c>Module:handle_event/5</c>
-      </seealso>
-      so it may require more coding discipline to ensure what events
-      are handled in which state.  Therefore it might be a wee bit
-      easier to accidentally postpone an event in two or more states
-      and not handling it in any of them causing a tight infinite
-      loop when the event bounces to be retried between the states.
+      An event can can be postponed causing it to be retried
+      after the state has changed, or more precisely;
+      after a state change all postponed events are retried
+      in the new state.
     </p>
     <p>A gen_statem handles system messages as documented in
        <seealso marker="sys">sys</seealso>.
@@ -239,18 +238,22 @@ erlang:'!'            -----> Module:State/5
     <datatype>
       <name name="state" />
       <desc>
-	<p>If the gen_statem <c>State</c> is an <c>atom()</c>, the
-	  <seealso marker="#state_function">state function</seealso> is
-	  <seealso marker="#Module:State/5">Module:State/5</seealso>.
-	  If it is any other <c>term()</c> the
-	  <seealso marker="#state_function">state function</seealso> is
-	  <seealso marker="#Module:handle_event/5">
-	    Module:handle_event/5
-	  </seealso>.  After a state change (<c>NewState =/= State</c>)
+	<p>After a state change (<c>NewState =/= State</c>)
 	  all postponed events are retried.
 	</p>
       </desc>
     </datatype>
+    <datatype>
+      <name name="state_name" />
+      <desc>
+	<p>If
+	  <seealso marker="#type-callback_mode">
+	    callback_mode
+	  </seealso> is <c>state_functions</c>, which is the default,
+	  the state has to be of this type i.e an <c>atom()</c>.
+	</p>
+      </desc>
+    </datatype>
     <datatype>
       <name name="state_data" />
       <desc>
@@ -296,6 +299,33 @@ erlang:'!'            -----> Module:State/5
 	</p>
       </desc>
     </datatype>
+    <datatype>
+      <name name="init_option" />
+      <desc>
+	<p>Option that only is valid when initializing the gen_statem</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="callback_mode" />
+      <desc>
+	<taglist>
+	  <tag><c>state_functions</c></tag>
+	  <item>The state has to be of type
+	    <seealso marker="#type-state_name"><c>state_name()</c></seealso>
+	    and one callback function per state that is
+	    <seealso marker="#Module:StateName/5">
+	      <c>Module:StateName/5</c>
+	    </seealso> is used.  This is the default.
+	  </item>
+	  <tag><c>handle_event_function</c></tag>
+	  <item>The state can be any term and the callback function
+	    <seealso marker="#Module:handle_event/5">
+	      <c>Module:handle_event/5</c>
+	    </seealso> is used for all states.
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
     <datatype>
       <name name="state_op" />
       <desc>
@@ -472,6 +502,53 @@ erlang:'!'            -----> Module:State/5
 	</taglist>
       </desc>
     </datatype>
+    <datatype>
+      <name name="state_callback_result" />
+      <desc>
+	<taglist>
+	  <tag>
+	   <c>{stop,<anno>Reason</anno>,<anno>NewStateData</anno>}</c>
+	  </tag>
+	  <item>The same as
+	    <c>{stop,<anno>Reason</anno>,[],<anno>NewStateData</anno>}</c>
+	  </item>
+	  <tag><c>{stop,
+	    <anno>Reason</anno>,
+	    <anno>Replies</anno>,
+	    <anno>NewStateData</anno>}</c>
+	  </tag>
+	  <item>The gen_statem will first send all
+	    <c><anno>Replies</anno></c> and then terminate by calling
+	    <seealso marker="#Module:terminate/3">
+	      <c>Module:terminate/3</c>
+	    </seealso> with <c>Reason</c>.
+	  </item>
+	  <tag>
+	    <c>
+	      {next_state,<anno>NewState</anno>,<anno>NewStateData</anno>}
+	    </c>
+	  </tag>
+	  <item>The same as
+	    <c>
+	      {next_state,<anno>NewState</anno>,<anno>NewStateData</anno>,[]}
+	    </c>
+	  </item>
+	  <tag>
+	    <c>
+	      {next_state,
+	       <anno>NewState</anno>,
+	       <anno>NewStateData</anno>,
+	       <anno>StateOps</anno>}
+	    </c>
+	  </tag>
+	  <item>The gen_statem will do a state transition to
+	    <c><anno>NewState</anno></c>
+	    (which may be the same as <c>State</c>)
+	    and execute all <c>StateOps</c>
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
   </datatypes>
 
   <funcs>
@@ -777,13 +854,16 @@ erlang:'!'            -----> Module:State/5
         <p><c><anno>Module</anno></c>, <c><anno>Options</anno></c> and
 	  <c><anno>Server</anno></c> have the same meanings
 	  as when calling
-          <seealso marker="#start_link/3">gen_statem:start[_link]/3,4</seealso>.
+          <seealso marker="#start_link/3">
+	    gen_statem:start[_link]/3,4
+	  </seealso>.
           However, the
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
 	  </seealso> name must have been registered accordingly
 	  <em>before</em> this function is called.</p>
-        <p><c><anno>State</anno></c> and <c><anno>StateData</anno></c>
+        <p><c><anno>State</anno></c>, <c><anno>StateData</anno></c>
+	  and <c><anno>StateOps</anno></c>
 	  have the same meanings as in the return value of
           <seealso marker="#Module:init/1">Module:init/1</seealso>.
           Also, the callback module <c><anno>Module</anno></c>
@@ -821,8 +901,13 @@ erlang:'!'            -----> Module:State/5
 	<v>&nbsp;| {ok,State,StateData,StateOps}</v>
         <v>&nbsp;| {stop,Reason} | ignore</v>
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
-	<v>StateData = <seealso marker="#type-state_data">state_data()</seealso></v>
-	<v>StateOps = [<seealso marker="#type-state_op">state_op()</seealso>]</v>
+	<v>StateData =
+	  <seealso marker="#type-state_data">state_data()</seealso>
+	</v>
+	<v>StateOps =
+	  [<seealso marker="#type-state_op">state_op()</seealso>
+	   | <seealso marker="#type-init_option">init_option()</seealso>]
+	</v>
 	<v>Reason = term()</v>
       </type>
       <desc>
@@ -843,10 +928,15 @@ erlang:'!'            -----> Module:State/5
 	  of the gen_statem.
 	</p>
 	<p>The <seealso marker="#type-state_op"><c>StateOps</c></seealso>
-	  are executed before entering the first
+	  are executed when entering the first
 	  <seealso marker="#type-state">state</seealso> just as for a
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
+	<p>This function allows an option to select the callback mode
+	  of the gen_statem.  See
+	  <seealso marker="#type-init_option">init_option</seealso>.
+	  This option is not allowed from the state function(s).
+	</p>
         <p>If something goes wrong during the initialization
           the function should return <c>{stop,Reason}</c>
 	  or <c>ignore</c>. See
@@ -856,10 +946,10 @@ erlang:'!'            -----> Module:State/5
     </func>
 
     <func>
-      <name>Module:handle_event(EventType, EventContent,
-        PrevState, State, StateData) -> Result
+      <name>Module:StateName(EventType, EventContent,
+        PrevStateName, StateName, StateData) -> Result
       </name>
-      <name>Module:State(EventType, EventContent,
+      <name>Module:handle_event(EventType, EventContent,
         PrevState, State, StateData) -> Result
       </name>
       <fsummary>Handle an event</fsummary>
@@ -868,41 +958,23 @@ erlang:'!'            -----> Module:State/5
 	  <seealso marker="#type-event_type">event_type()</seealso>
 	</v>
 	<v>EventContent = term()</v>
-	<v>Result = {stop,Reason,NewStateData}</v>
-	<d>&nbsp;&nbsp;The same as <c>{stop,Reason,[],NewStateData}</c></d>
-	<v>&nbsp;&nbsp;| {stop,Reason,Reply,NewStateData}</v>
-	<d>&nbsp;&nbsp;The same as
-	  <c>{stop,Reason,[Reply],NewStateData}</c>
-	</d>
-	<v>&nbsp;&nbsp;| {stop,Reason,Replies,NewStateData}</v>
-	<d>&nbsp;&nbsp;The gen_statem will first send all
-	  <c>Replies</c> and then call
-	    <seealso marker="#Module:terminate/3">
-	      <c>Module:terminate/3</c>
-	    </seealso> with <c>Reason</c> and terminate.
-	</d>
-	<v>&nbsp;&nbsp;| {next_state,NewState,NewStateData}</v>
-	<d>&nbsp;&nbsp;The same as
-	  <c>{next_state,NewState,NewStateData,NewStateData,[]}</c>
-	</d>
-	<v>&nbsp;&nbsp;| {next_state,NewState,NewStateData,StateOps}</v>
-	<d>&nbsp;&nbsp;The gen_statem will do a state transition to
-	  <c>NewState</c> (which may be the same as <c>State</c>)
-	  and execute all <c>StateOps</c>
-	</d>
-	<v>Reason = term()</v>
-	<v>PrevState = State = NewState =
+	<v>PrevStateName =
+	  <seealso marker="#type-state_name">state_name()</seealso>
+	  | reference()
+	</v>
+	<v>StateName =
+	  <seealso marker="#type-state_name">state_name()</seealso>
+	</v>
+	<v>PrevState = State =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
 	<v>StateData = NewStateData =
 	  <seealso marker="#type-state_data">state_data()</seealso>
 	</v>
-	<v>Reply =
-	  <seealso marker="#type-reply_operation">reply_operation()</seealso>
-	</v>
-	<v>Replies = [Reply]</v>
-	<v>StateOps =
-	  [<seealso marker="#type-state_op">state_op()</seealso>]
+	<v>Result =
+	  <seealso marker="#type-state_callback_result">
+	    state_callback_result()
+	  </seealso>
 	</v>
       </type>
       <desc>
@@ -923,19 +995,18 @@ erlang:'!'            -----> Module:State/5
 	    <c>gen_statem:reply(Client, Reply)</c>
 	  </seealso>.
 	</p>
-        <p><seealso marker="#type-state"><c>State</c></seealso>
-	  is the internal state of the gen_statem which
-	  when <c>State</c> is an <c>atom()</c>
-	  is the same as this function's name, so it is seldom useful,
-	  except for example when comparing with <c>PrevState</c>
-	  that is the gen_statem's previous state, or in
-	  <seealso marker="#Module:handle_event/5">
-	    Module:handle_event/5
-	  </seealso> since that function is common for all states
-	  that are not an <c>atom()</c>.
-	</p>
-	<p>If this function returns with
-	  <seealso marker="#type-state"><c>NewState =/= State</c></seealso>
+        <p><c>StateName</c> is rarely useful.  One exception is if
+	  you call a common event handling function from your state
+	  function then you might want to pass <c>StateName</c>.
+	</p>
+	<p><c>PrevStateName</c> and <c>PrevState</c> are rarely useful.
+	  They can be used when you want to do something only at the
+	  first event in a state.  Note that when gen_statem enters
+	  its first state this is set to a <c>reference()</c> since
+	  that can not match the state.
+	</p>
+	<p>If this function returns with a new state that
+	  does not match equal (<c>=/=</c>) to the current state
 	  all postponed events will be retried in the new state.
 	</p>
 	<p>See <seealso marker="#type-state_op">state_op()</seealso>
@@ -946,7 +1017,7 @@ erlang:'!'            -----> Module:State/5
     </func>
 
     <func>
-      <name>Module:terminate(Reason, State, StateData)</name>
+      <name>Module:terminate(Reason, State, StateData) -> Ignored</name>
       <fsummary>Clean up before termination</fsummary>
       <type>
         <v>Reason = normal | shutdown | {shutdown,term()} | term()</v>
@@ -956,6 +1027,7 @@ erlang:'!'            -----> Module:State/5
 	    state_data()
 	  </seealso>
 	</v>
+	<v>Ignored = term()</v>
       </type>
       <desc>
         <p>This function is called by a gen_statem when it is about to
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 7c3cd8c2f3..e6bb38fc2c 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -44,6 +44,9 @@
 -export(
    [wakeup_from_hibernate/3]).
 
+%% Fix problem for doc build
+-export_type([state_callback_result/0]).
+
 %%%==========================================================================
 %%% Interface functions.
 %%%==========================================================================
@@ -51,14 +54,18 @@
 -type client() ::
 	{To :: pid(), Tag :: term()}. % Reply-to specifier for call
 -type state() ::
-	atom() | % Calls state callback function State/5
-	term(). % Calls state callback function handle_event/5
+	state_name() | % For state callback function StateName/5
+	term(). % For state callback function handle_event/5
+-type state_name() :: atom().
 -type state_data() :: term().
 -type event_type() ::
 	{'call',Client :: client()} | 'cast' |
 	'info' | 'timeout' | 'internal'.
 -type event_predicate() :: % Return true for the event in question
 	fun((event_type(), term()) -> boolean()).
+-type init_option() ::
+	{'callback_mode', callback_mode()}.
+-type callback_mode() :: 'state_functions' | 'handle_event_function'.
 -type state_op() ::
 	%% First NewState and NewStateData are set,
 	%% then all state_operations() are executed in order of
@@ -97,6 +104,21 @@
 -type reply_operation() ::
 	{'reply', % Reply to a client
 	 Client :: client(), Reply :: term()}.
+-type state_callback_result() ::
+    {stop, % Stop the server
+     Reason :: term(),
+     NewStateData :: state_data()} |
+    {stop, % Stop the server
+     Reason :: term(),
+     Replies :: [reply_operation()] | reply_operation(),
+     NewStateData :: state_data()} |
+    {next_state, % {next_state,NewState,NewStateData,[]}
+     NewState :: state(),
+     NewStateData :: state_data()} |
+    {next_state, % State transition, maybe to the same state
+     NewState :: state(),
+     NewStateData :: state_data(),
+     StateOps :: [state_op()] | state_op()}.
 
 %% The state machine init function.  It is called only once and
 %% the server is not running until this function has returned
@@ -104,40 +126,36 @@
 %% for all events to this server.
 -callback init(Args :: term()) ->
     {'ok', state(), state_data()} |
-    {'ok', state(), state_data(), [state_op()]} |
+    {'ok', state(), state_data(), [state_op()|init_option()]} |
     'ignore' |
     {'stop', Reason :: term()}.
 
-%% An example callback for a fictive state 'handle_event'
-%% that you should avoid having. See below.
+%% Example callback for callback_mode =:= state_functions
+%% state name 'state_name'.
+%%
+%% In this mode all states has to be type state_name() i.e atom().
 %%
 %% Note that state callbacks and only state callbacks have arity 5
 %% and that is intended.
+-callback state_name(
+	    event_type(),
+	    EventContent :: term(),
+	    PrevStateName :: state_name() | reference(),
+	    StateName :: state_name(), % Current state
+	    StateData :: state_data()) ->
+    state_callback_result().
+%%
+%% Callback for callback_mode =:= handle_event_function.
 %%
-%% You should not actually use 'handle_event' as a state name,
-%% since it is the callback function that is used if you would use
-%% a State that is not an atom().  This is because since there is
-%% no obvious way to decide on a state function name from any term().
+%% Note that state callbacks and only state callbacks have arity 5
+%% and that is intended.
 -callback handle_event(
 	    event_type(),
 	    EventContent :: term(),
 	    PrevState :: state(),
 	    State :: state(), % Current state
 	    StateData :: state_data()) ->
-    {stop, % Stop the server
-     Reason :: term(),
-     NewStateData :: state_data()} |
-    {stop, % Stop the server
-     Reason :: term(),
-     [reply_operation()] | reply_operation(),
-     NewStateData :: state_data()} |
-    {next_state, % {next_state,NewState,NewStateData,[]}
-     NewState :: state(),
-     NewStateData :: state_data()} |
-    {next_state, % State transition, maybe to the same state
-     NewState :: state(),
-     NewStateData :: state_data(),
-     [state_op()] | state_op()}.
+    state_callback_result().
 
 %% Clean up before the server terminates.
 -callback terminate(
@@ -171,8 +189,11 @@
 
 -optional_callbacks(
    [format_status/2, % Has got a default implementation
-    handle_event/5]). % Only needed for State not an atom()
-%%  For every atom() State there has to be a State/5 callback function
+    %%
+    state_name/5, % Example for callback_mode =:= state_functions:
+    %% there has to be a StateName/5 callback function for every StateName.
+    %%
+    handle_event/5]). % For callback_mode =:= handle_event_function
 
 %% Type validation functions
 client({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
@@ -366,7 +387,8 @@ enter_loop(Module, Options, State, StateData) ->
 -spec enter_loop(
 	Module :: module(), Options :: [debug_opt()],
 	State :: state(), StateData :: state_data(),
-	Server_or_StateOps :: server_name() | pid() | [state_op()]) ->
+	Server_or_StateOps ::
+	  server_name() | pid() | [state_op()|init_option()]) ->
 			no_return().
 enter_loop(Module, Options, State, StateData, Server_or_StateOps) ->
     if
@@ -384,7 +406,7 @@ enter_loop(Module, Options, State, StateData, Server_or_StateOps) ->
 	Module :: module(), Options :: [debug_opt()],
 	State :: state(), StateData :: state_data(),
 	Server :: server_name() | pid(),
-	StateOps :: [state_op()]) ->
+	StateOps :: [state_op()|init_option()]) ->
 			no_return().
 enter_loop(Module, Options, State, StateData, Server, StateOps) ->
     Parent = gen:get_parent(),
@@ -410,11 +432,12 @@ do_send(Proc, Msg) ->
     end.
 
 %% Here init_it and all enter_loop functions converge
-enter(Module, Options, State, StateData, Server, StateOps, Parent) ->
+enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
     Name = gen:get_proc_name(Server),
     Debug = gen:debug_options(Name, Options),
     PrevState = make_ref(),
     S = #{
+      callback_mode => state_functions,
       module => Module,
       name => Name,
       prev_state => PrevState,
@@ -423,9 +446,17 @@ enter(Module, Options, State, StateData, Server, StateOps, Parent) ->
       timer => undefined,
       postponed => [],
       hibernate => false},
-    loop_event_state_ops(
-      Parent, Debug, S, [], {event,undefined},
-      State, StateData, [{retry,false}|StateOps]).
+    case collect_init_options(InitOps) of
+	{CallbackMode,StateOps} ->
+	    loop_event_state_ops(
+	      Parent, Debug,
+	      S#{callback_mode := CallbackMode},
+	      [], {event,undefined},
+	      State, StateData,
+	      [{retry,false}|StateOps]);
+	[Reason] ->
+	    terminate(Reason, Debug, S, [])
+    end.
 
 %%%==========================================================================
 %%%  gen callbacks
@@ -643,13 +674,13 @@ loop_receive(Parent, Debug, S, Event, Timer) ->
 %% The loop_event* functions optimize S map handling by dismantling it,
 %% passing the parts in arguments to avoid map lookups and construct the
 %% new S map in one go on exit.  Premature optimization, I know, but
-%% the code was way to readable and there were quite some map lookups
-%% repeated in different functions.
+%% there were quite some map lookups repeated in different functions.
 loop_events(Parent, Debug, S, [], _Timer) ->
     loop(Parent, Debug, S);
 loop_events(
   Parent, Debug,
-  #{module := Module,
+  #{callback_mode := CallbackMode,
+    module := Module,
     prev_state := PrevState,
     state := State,
     state_data := StateData} = S,
@@ -657,11 +688,11 @@ loop_events(
     _ = (Timer =/= undefined) andalso
 	cancel_timer(Timer),
     Func =
-	if
-	    is_atom(State) ->
-		State;
-	    true ->
-		handle_event
+	case CallbackMode of
+	    handle_event_function ->
+		handle_event;
+	    state_functions ->
+		State
 	end,
     try Module:Func(Type, Content, PrevState, State, StateData) of
 	Result ->
@@ -675,7 +706,10 @@ loop_events(
 	    %% Process an undef to check for the simple mistake
 	    %% of calling a nonexistent state function
 	    case erlang:get_stacktrace() of
-		[{Module,State,[Event,StateData]=Args,_}|Stacktrace] ->
+		[{Module,Func,
+		  [Type,Content,PrevState,State,StateData]=Args,
+		  _}
+		 |Stacktrace] ->
 		    terminate(
 		      error,
 		      {undef_state_function,{Module,State,Args}},
@@ -709,7 +743,7 @@ loop_event_result(Parent, Debug, S, Events, Event, Result) ->
 		end,
 	    BadReplies =
 		reply_then_terminate(Reason, Debug, NewS, Q, Replies),
-	    %% Since it returned Replies was bad
+	    %% Since we got back here Replies was bad
 	    terminate(
 	      {bad_return_value,{stop,Reason,BadReplies,NewStateData}},
 	      Debug, NewS, Q);
@@ -794,6 +828,24 @@ loop_event_state_ops(
 %%---------------------------------------------------------------------------
 %% Server helpers
 
+collect_init_options(InitOps) ->
+    collect_init_options(lists:reverse(InitOps), state_functions, []).
+%% Keep the last of each kind
+collect_init_options([], CallbackMode, StateOps) ->
+    {CallbackMode,StateOps};
+collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) ->
+    case InitOp of
+	{callback_mode,Mode}
+	  when Mode =:= state_functions;
+	       Mode =:= handle_event_function ->
+	    collect_init_options(InitOps, Mode, StateOps);
+	{callback_mode,_} ->
+	    [{bad_init_ops,IOIOs}];
+	_ -> % Collect others as StateOps
+	    collect_init_options(
+	      InitOps, CallbackMode, [InitOp|StateOps])
+    end.
+
 collect_state_options(StateOps) ->
     collect_state_options(
       lists:reverse(StateOps), false, false, undefined, []).
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 51e08f5ec1..8a96f0e8e2 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -19,7 +19,7 @@
 %%
 -module(gen_statem_SUITE).
 
--include_lib("test_server/include/test_server.hrl").
+-include_lib("common_test/include/ct.hrl").
 
 -compile(export_all).
 -behaviour(gen_statem).
@@ -30,7 +30,11 @@ suite() -> [{ct_hooks,[ts_install_cth]}].
 
 all() ->
     [{group, start},
+     {group, start_handle_event},
+     {group, stop},
+     {group, stop_handle_event},
      {group, abnormal},
+     {group, abnormal_handle_event},
      shutdown,
      {group, sys}, hibernate, enter_loop].
 
@@ -38,10 +42,21 @@ groups() ->
     [{start, [],
       [start1, start2, start3, start4, start5, start6, start7,
        start8, start9, start10, start11, start12]},
+     {start_handle_event, [],
+      [start1, start2, start3, start4, start5, start6, start7,
+       start8, start9, start10, start11, start12]},
      {stop, [],
       [stop1, stop2, stop3, stop4, stop5, stop6, stop7, stop8, stop9, stop10]},
+     {stop_handle_event, [],
+      [stop1, stop2, stop3, stop4, stop5, stop6, stop7, stop8, stop9, stop10]},
      {abnormal, [], [abnormal1, abnormal2]},
+     {abnormal_handle_event, [], [abnormal1, abnormal2]},
      {sys, [],
+      [sys1,
+       call_format_status,
+       error_format_status, terminate_crash_format,
+       get_state, replace_state]},
+     {sys_handle_event, [],
       [sys1,
        call_format_status,
        error_format_status, terminate_crash_format,
@@ -53,6 +68,12 @@ init_per_suite(Config) ->
 end_per_suite(_Config) ->
     ok.
 
+init_per_group(GroupName, Config)
+  when GroupName =:= start_handle_event;
+       GroupName =:= stop_handle_event;
+       GroupName =:= abnormal_handle_event;
+       GroupName =:= sys_handle_event ->
+    [{init_ops,[{callback_mode,handle_event_function}]}|Config];
 init_per_group(_GroupName, Config) ->
     Config.
 
@@ -65,6 +86,7 @@ init_per_testcase(_CaseName, Config) ->
 %%%    dbg:tracer(),
 %%%    dbg:p(all, c),
 %%%    dbg:tpl(gen_statem, cx),
+%%%    dbg:tpl(sys, cx),
     [{watchdog, Dog} | Config].
 
 end_per_testcase(_CaseName, Config) ->
@@ -88,7 +110,7 @@ end_per_testcase(_CaseName, Config) ->
 start1(Config) when is_list(Config) ->
     %%OldFl = process_flag(trap_exit, true),
 
-    {ok,Pid0} = gen_statem:start_link(?MODULE, [], []),
+    {ok,Pid0} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
     ok = do_func_test(Pid0),
     ok = do_sync_func_test(Pid0),
     stop_it(Pid0),
@@ -102,7 +124,7 @@ start1(Config) when is_list(Config) ->
 %% anonymous w. shutdown
 start2(Config) when is_list(Config) ->
     %% Dont link when shutdown
-    {ok,Pid0} = gen_statem:start(?MODULE, [], []),
+    {ok,Pid0} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     ok = do_func_test(Pid0),
     ok = do_sync_func_test(Pid0),
     stopped = gen_statem:call(Pid0, {stop,shutdown}),
@@ -113,13 +135,15 @@ start2(Config) when is_list(Config) ->
 start3(Config) when is_list(Config) ->
     %%OldFl = process_flag(trap_exit, true),
 
-    {ok,Pid0} = gen_statem:start(?MODULE, [], [{timeout,5}]),
+    {ok,Pid0} =
+	gen_statem:start(?MODULE, start_arg(Config, []), [{timeout,5}]),
     ok = do_func_test(Pid0),
     ok = do_sync_func_test(Pid0),
     stop_it(Pid0),
 
-    {error,timeout} = gen_statem:start(?MODULE, sleep,
-					   [{timeout,5}]),
+    {error,timeout} =
+	gen_statem:start(
+	  ?MODULE, start_arg(Config, sleep), [{timeout,5}]),
 
     %%process_flag(trap_exit, OldFl),
     ok = verify_empty_msgq().
@@ -128,7 +152,7 @@ start3(Config) when is_list(Config) ->
 start4(Config) when is_list(Config) ->
     OldFl = process_flag(trap_exit, true),
 
-    ignore = gen_statem:start(?MODULE, ignore, []),
+    ignore = gen_statem:start(?MODULE, start_arg(Config, ignore), []),
 
     process_flag(trap_exit, OldFl),
     ok = verify_empty_msgq().
@@ -138,14 +162,14 @@ start5(suite) -> [];
 start5(Config) when is_list(Config) ->
     OldFl = process_flag(trap_exit, true),
 
-    {error,stopped} = gen_statem:start(?MODULE, stop, []),
+    {error,stopped} = gen_statem:start(?MODULE, start_arg(Config, stop), []),
 
     process_flag(trap_exit, OldFl),
     ok = verify_empty_msgq().
 
 %% anonymous linked
 start6(Config) when is_list(Config) ->
-    {ok,Pid} = gen_statem:start_link(?MODULE, [], []),
+    {ok,Pid} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
     stop_it(Pid),
@@ -157,11 +181,11 @@ start7(Config) when is_list(Config) ->
     STM = {global,my_stm},
 
     {ok,Pid} =
-	gen_statem:start_link(STM, ?MODULE, [], []),
+	gen_statem:start_link(STM, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start_link(STM, ?MODULE, [], []),
+	gen_statem:start_link(STM, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start(STM, ?MODULE, [], []),
+	gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
 
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
@@ -179,9 +203,9 @@ start8(Config) when is_list(Config) ->
     STM = {local,Name},
 
     {ok,Pid} =
-	gen_statem:start(STM, ?MODULE, [], []),
+	gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start(STM, ?MODULE, [], []),
+	gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
 
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
@@ -199,9 +223,9 @@ start9(Config) when is_list(Config) ->
     STM = {local,Name},
 
     {ok,Pid} =
-	gen_statem:start_link(STM, ?MODULE, [], []),
+	gen_statem:start_link(STM, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start(STM, ?MODULE, [], []),
+	gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
 
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
@@ -217,11 +241,11 @@ start10(Config) when is_list(Config) ->
     STM = {global,my_stm},
 
     {ok,Pid} =
-	gen_statem:start(STM, ?MODULE, [], []),
+	gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start(STM, ?MODULE, [], []),
+	gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start_link(STM, ?MODULE, [], []),
+	gen_statem:start_link(STM, ?MODULE, start_arg(Config, []), []),
 
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
@@ -238,19 +262,19 @@ start11(Config) when is_list(Config) ->
     GlobalSTM = {global,Name},
 
     {ok,Pid} =
-	gen_statem:start_link(LocalSTM, ?MODULE, [], []),
+	gen_statem:start_link(LocalSTM, ?MODULE, start_arg(Config, []), []),
     stop_it(Pid),
 
     {ok,_Pid1} =
-	gen_statem:start_link(LocalSTM, ?MODULE, [], []),
+	gen_statem:start_link(LocalSTM, ?MODULE, start_arg(Config, []), []),
     stop_it(Name),
 
     {ok,Pid2} =
-	gen_statem:start(GlobalSTM, ?MODULE, [], []),
+	gen_statem:start(GlobalSTM, ?MODULE, start_arg(Config, []), []),
     stop_it(Pid2),
     receive after 1 -> true end,
     Result =
-	gen_statem:start(GlobalSTM, ?MODULE, [], []),
+	gen_statem:start(GlobalSTM, ?MODULE, start_arg(Config, []), []),
     io:format("Result = ~p~n",[Result]),
     {ok,_Pid3} = Result,
     stop_it(GlobalSTM),
@@ -263,11 +287,11 @@ start12(Config) when is_list(Config) ->
     VIA = {via,dummy_via,my_stm},
 
     {ok,Pid} =
-	gen_statem:start_link(VIA, ?MODULE, [], []),
+	gen_statem:start_link(VIA, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start_link(VIA, ?MODULE, [], []),
+	gen_statem:start_link(VIA, ?MODULE, start_arg(Config, []), []),
     {error,{already_started,Pid}} =
-	gen_statem:start(VIA, ?MODULE, [], []),
+	gen_statem:start(VIA, ?MODULE, start_arg(Config, []), []),
 
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
@@ -279,23 +303,23 @@ start12(Config) when is_list(Config) ->
 
 
 %% Anonymous, reason 'normal'
-stop1(_Config) ->
-    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+stop1(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     ok = gen_statem:stop(Pid),
     false = erlang:is_process_alive(Pid),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason).
 
 %% Anonymous, other reason
-stop2(_Config) ->
-    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+stop2(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     ok = gen_statem:stop(Pid, other_reason, infinity),
     false = erlang:is_process_alive(Pid),
     ok.
 
 %% Anonymous, invalid timeout
-stop3(_Config) ->
-    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+stop3(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     _ =
 	?EXPECT_FAILURE(
 	   gen_statem:stop(Pid, other_reason, invalid_timeout),
@@ -306,8 +330,10 @@ stop3(_Config) ->
     ok.
 
 %% Registered name
-stop4(_Config) ->
-    {ok,Pid} = gen_statem:start({local,to_stop},?MODULE, [], []),
+stop4(Config) ->
+    {ok,Pid} =
+	gen_statem:start(
+	  {local,to_stop},?MODULE, start_arg(Config, []), []),
     ok = gen_statem:stop(to_stop),
     false = erlang:is_process_alive(Pid),
     noproc =
@@ -315,9 +341,11 @@ stop4(_Config) ->
     ok.
 
 %% Registered name and local node
-stop5(_Config) ->
+stop5(Config) ->
     Name = to_stop,
-    {ok,Pid} = gen_statem:start({local,Name},?MODULE, [], []),
+    {ok,Pid} =
+	gen_statem:start(
+	  {local,Name},?MODULE, start_arg(Config, []), []),
     ok = gen_statem:stop({Name,node()}),
     false = erlang:is_process_alive(Pid),
     noproc =
@@ -325,9 +353,9 @@ stop5(_Config) ->
     ok.
 
 %% Globally registered name
-stop6(_Config) ->
+stop6(Config) ->
     STM = {global,to_stop},
-    {ok,Pid} = gen_statem:start(STM, ?MODULE, [], []),
+    {ok,Pid} = gen_statem:start(STM, ?MODULE, start_arg(Config, []), []),
     ok = gen_statem:stop(STM),
     false = erlang:is_process_alive(Pid),
     noproc =
@@ -335,11 +363,10 @@ stop6(_Config) ->
     ok.
 
 %% 'via' registered name
-stop7(_Config) ->
+stop7(Config) ->
     VIA = {via,dummy_via,to_stop},
     dummy_via:reset(),
-    {ok,Pid} = gen_statem:start(VIA,
-				  ?MODULE, [], []),
+    {ok,Pid} = gen_statem:start(VIA, ?MODULE, start_arg(Config, []), []),
     ok = gen_statem:stop(VIA),
     false = erlang:is_process_alive(Pid),
     noproc =
@@ -347,46 +374,55 @@ stop7(_Config) ->
     ok.
 
 %% Anonymous on remote node
-stop8(_Config) ->
+stop8(Config) ->
     {ok,Node} = ?t:start_node(gen_statem_stop8, slave, []),
     Dir = filename:dirname(code:which(?MODULE)),
     rpc:call(Node, code, add_path, [Dir]),
-    {ok,Pid} = rpc:call(Node, gen_statem,start, [?MODULE,[],[]]),
+    {ok,Pid} =
+	rpc:call(
+	  Node, gen_statem,start,
+	  [?MODULE,start_arg(Config, []),[]]),
     ok = gen_statem:stop(Pid),
     false = rpc:call(Node, erlang, is_process_alive, [Pid]),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason1),
     true = ?t:stop_node(Node),
-    {nodedown,Node} =
+    {{nodedown,Node},{sys,terminate,_}} =
 	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason2),
     ok.
 
 %% Registered name on remote node
-stop9(_Config) ->
+stop9(Config) ->
     Name = to_stop,
     LocalSTM = {local,Name},
     {ok,Node} = ?t:start_node(gen_statem__stop9, slave, []),
     STM = {Name,Node},
     Dir = filename:dirname(code:which(?MODULE)),
     rpc:call(Node, code, add_path, [Dir]),
-    {ok,Pid} = rpc:call(Node, gen_statem, start, [LocalSTM,?MODULE,[],[]]),
+    {ok,Pid} =
+	rpc:call(
+	  Node, gen_statem, start,
+	  [LocalSTM,?MODULE,start_arg(Config, []),[]]),
     ok = gen_statem:stop(STM),
     undefined = rpc:call(Node,erlang,whereis,[Name]),
     false = rpc:call(Node,erlang,is_process_alive,[Pid]),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(STM), Reason1),
     true = ?t:stop_node(Node),
-    {nodedown,Node} =
+    {{nodedown,Node},{sys,terminate,_}} =
 	?EXPECT_FAILURE(gen_statem:stop(STM), Reason2),
     ok.
 
 %% Globally registered name on remote node
-stop10(_Config) ->
+stop10(Config) ->
     STM = {global,to_stop},
     {ok,Node} = ?t:start_node(gen_statem_stop10, slave, []),
     Dir = filename:dirname(code:which(?MODULE)),
     rpc:call(Node,code,add_path,[Dir]),
-    {ok,Pid} = rpc:call(Node, gen_statem, start, [STM,?MODULE,[],[]]),
+    {ok,Pid} =
+	rpc:call(
+	  Node, gen_statem, start,
+	  [STM,?MODULE,start_arg(Config, []),[]]),
     global:sync(),
     ok = gen_statem:stop(STM),
     false = rpc:call(Node, erlang, is_process_alive, [Pid]),
@@ -402,7 +438,8 @@ abnormal1(Config) when is_list(Config) ->
     Name = abnormal1,
     LocalSTM = {local,Name},
 
-    {ok, _Pid} = gen_statem:start(LocalSTM, ?MODULE, [], []),
+    {ok, _Pid} =
+	gen_statem:start(LocalSTM, ?MODULE, start_arg(Config, []), []),
 
     %% timeout call.
     delayed = gen_statem:call(Name, {delayed_answer,1}, 100),
@@ -410,13 +447,14 @@ abnormal1(Config) when is_list(Config) ->
 	?EXPECT_FAILURE(
 	   gen_statem:call(Name, {delayed_answer,1000}, 10),
 	   Reason),
+    ok = gen_statem:stop(Name),
     ok = verify_empty_msgq().
 
 %% Check that bad return values makes the stm crash. Note that we must
 %% trap exit since we must link to get the real bad_return_ error
 abnormal2(Config) when is_list(Config) ->
     OldFl = process_flag(trap_exit, true),
-    {ok,Pid} = gen_statem:start_link(?MODULE, [], []),
+    {ok,Pid} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
 
     %% bad return value in the gen_statem loop
     {{bad_return_value,badreturn},_} =
@@ -433,7 +471,7 @@ abnormal2(Config) when is_list(Config) ->
 shutdown(Config) when is_list(Config) ->
     process_flag(trap_exit, true),
 
-    {ok,Pid0} = gen_statem:start_link(?MODULE, [], []),
+    {ok,Pid0} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
     ok = do_func_test(Pid0),
     ok = do_sync_func_test(Pid0),
     stopped = gen_statem:call(Pid0, {stop,{shutdown,reason}}),
@@ -454,7 +492,7 @@ shutdown(Config) when is_list(Config) ->
 
 
 sys1(Config) when is_list(Config) ->
-    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     {status, Pid, {module,gen_statem}, _} = sys:get_status(Pid),
     sys:suspend(Pid),
     Parent = self(),
@@ -477,7 +515,7 @@ sys1(Config) when is_list(Config) ->
     stop_it(Pid).
 
 call_format_status(Config) when is_list(Config) ->
-    {ok,Pid} = gen_statem:start(?MODULE, [], []),
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     Status = sys:get_status(Pid),
     {status,Pid,_Mod,[_PDict,running,_,_, Data]} = Status,
     [format_status_called|_] = lists:reverse(Data),
@@ -485,7 +523,9 @@ call_format_status(Config) when is_list(Config) ->
 
     %% check that format_status can handle a name being an atom (pid is
     %% already checked by the previous test)
-    {ok, Pid2} = gen_statem:start({local, gstm}, ?MODULE, [], []),
+    {ok, Pid2} =
+	gen_statem:start(
+	  {local, gstm}, ?MODULE, start_arg(Config, []), []),
     Status2 = sys:get_status(gstm),
     {status,Pid2,_Mod,[_PDict2,running,_,_,Data2]} = Status2,
     [format_status_called|_] = lists:reverse(Data2),
@@ -494,13 +534,17 @@ call_format_status(Config) when is_list(Config) ->
     %% check that format_status can handle a name being a term other than a
     %% pid or atom
     GlobalName1 = {global,"CallFormatStatus"},
-    {ok,Pid3} = gen_statem:start(GlobalName1, ?MODULE, [], []),
+    {ok,Pid3} =
+	gen_statem:start(
+	  GlobalName1, ?MODULE, start_arg(Config, []), []),
     Status3 = sys:get_status(GlobalName1),
     {status,Pid3,_Mod,[_PDict3,running,_,_,Data3]} = Status3,
     [format_status_called|_] = lists:reverse(Data3),
     stop_it(Pid3),
     GlobalName2 = {global,{name, "term"}},
-    {ok,Pid4} = gen_statem:start(GlobalName2, ?MODULE, [], []),
+    {ok,Pid4} =
+	gen_statem:start(
+	  GlobalName2, ?MODULE, start_arg(Config, []), []),
     Status4 = sys:get_status(GlobalName2),
     {status,Pid4,_Mod,[_PDict4,running,_,_, Data4]} = Status4,
     [format_status_called|_] = lists:reverse(Data4),
@@ -510,13 +554,15 @@ call_format_status(Config) when is_list(Config) ->
     %% pid or atom
     dummy_via:reset(),
     ViaName1 = {via,dummy_via,"CallFormatStatus"},
-    {ok,Pid5} = gen_statem:start(ViaName1, ?MODULE, [], []),
+    {ok,Pid5} = gen_statem:start(ViaName1, ?MODULE, start_arg(Config, []), []),
     Status5 = sys:get_status(ViaName1),
     {status,Pid5,_Mod, [_PDict5,running,_,_, Data5]} = Status5,
     [format_status_called|_] = lists:reverse(Data5),
     stop_it(Pid5),
     ViaName2 = {via,dummy_via,{name,"term"}},
-    {ok, Pid6} = gen_statem:start(ViaName2, ?MODULE, [], []),
+    {ok, Pid6} =
+	gen_statem:start(
+	  ViaName2, ?MODULE, start_arg(Config, []), []),
     Status6 = sys:get_status(ViaName2),
     {status,Pid6,_Mod,[_PDict6,running,_,_,Data6]} = Status6,
     [format_status_called|_] = lists:reverse(Data6),
@@ -528,7 +574,9 @@ error_format_status(Config) when is_list(Config) ->
     error_logger_forwarder:register(),
     OldFl = process_flag(trap_exit, true),
     StateData = "called format_status",
-    {ok,Pid} = gen_statem:start(?MODULE, {state_data,StateData}, []),
+    {ok,Pid} =
+	gen_statem:start(
+	  ?MODULE, start_arg(Config, {state_data,StateData}), []),
     %% bad return value in the gen_statem loop
     {{bad_return_value,badreturn},_} =
 	?EXPECT_FAILURE(gen_statem:call(Pid, badreturn), Reason),
@@ -562,7 +610,9 @@ terminate_crash_format(Config) when is_list(Config) ->
     error_logger_forwarder:register(),
     OldFl = process_flag(trap_exit, true),
     StateData = crash_terminate,
-    {ok,Pid} = gen_statem:start(?MODULE, {state_data,StateData}, []),
+    {ok,Pid} =
+	gen_statem:start(
+	  ?MODULE, start_arg(Config, {state_data,StateData}), []),
     stop_it(Pid),
     Self = self(),
     receive
@@ -595,7 +645,9 @@ terminate_crash_format(Config) when is_list(Config) ->
 
 get_state(Config) when is_list(Config) ->
     State = self(),
-    {ok,Pid} = gen_statem:start(?MODULE, {state_data,State}, []),
+    {ok,Pid} =
+	gen_statem:start(
+	  ?MODULE, start_arg(Config, {state_data,State}), []),
     {idle,State} = sys:get_state(Pid),
     {idle,State} = sys:get_state(Pid, 5000),
     stop_it(Pid),
@@ -603,13 +655,16 @@ get_state(Config) when is_list(Config) ->
     %% check that get_state can handle a name being an atom (pid is
     %% already checked by the previous test)
     {ok,Pid2} =
-	gen_statem:start({local,gstm}, ?MODULE, {state_data,State}, []),
+	gen_statem:start(
+	  {local,gstm}, ?MODULE, start_arg(Config, {state_data,State}), []),
     {idle,State} = sys:get_state(gstm),
     {idle,State} = sys:get_state(gstm, 5000),
     stop_it(Pid2),
 
     %% check that get_state works when pid is sys suspended
-    {ok,Pid3} = gen_statem:start(?MODULE, {state_data,State}, []),
+    {ok,Pid3} =
+	gen_statem:start(
+	  ?MODULE, start_arg(Config, {state_data,State}), []),
     {idle,State} = sys:get_state(Pid3),
     ok = sys:suspend(Pid3),
     {idle,State} = sys:get_state(Pid3, 5000),
@@ -619,7 +674,9 @@ get_state(Config) when is_list(Config) ->
 
 replace_state(Config) when is_list(Config) ->
     State = self(),
-    {ok, Pid} = gen_statem:start(?MODULE, {state_data,State}, []),
+    {ok, Pid} =
+	gen_statem:start(
+	  ?MODULE, start_arg(Config, {state_data,State}), []),
     {idle,State} = sys:get_state(Pid),
     NState1 = "replaced",
     Replace1 = fun({StateName, _}) -> {StateName,NState1} end,
@@ -650,7 +707,9 @@ replace_state(Config) when is_list(Config) ->
 hibernate(Config) when is_list(Config) ->
     OldFl = process_flag(trap_exit, true),
 
-    {ok,Pid0} = gen_statem:start_link(?MODULE, hiber_now, []),
+    {ok,Pid0} =
+	gen_statem:start_link(
+	  ?MODULE, start_arg(Config, hiber_now), []),
     is_in_erlang_hibernate(Pid0),
     stop_it(Pid0),
     receive
@@ -659,7 +718,8 @@ hibernate(Config) when is_list(Config) ->
 	    ?t:fail(gen_statem_did_not_die)
     end,
 
-    {ok,Pid} = gen_statem:start_link(?MODULE, hiber, []),
+    {ok,Pid} =
+	gen_statem:start_link(?MODULE, start_arg(Config, hiber), []),
     true = ({current_function,{erlang,hibernate,3}} =/=
 		erlang:process_info(Pid,current_function)),
     hibernating = gen_statem:call(Pid, hibernate_sync),
@@ -1031,6 +1091,14 @@ verify_empty_msgq() ->
     [] = ?t:messages_get(),
     ok.
 
+start_arg(Config, Arg) ->
+    case lists:keyfind(init_ops, 1, Config) of
+	{_,Ops} ->
+	    {init_ops,Arg,Ops};
+	false ->
+	    Arg
+    end.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%
 %% The State Machine
@@ -1052,7 +1120,16 @@ init(hiber_now) ->
     {ok,hiber_idle,[],[hibernate]};
 init({state_data, StateData}) ->
     {ok,idle,StateData};
-init(_) ->
+init({init_ops,Arg,InitOps}) ->
+    case init(Arg) of
+	{ok,State,Data,Ops} ->
+	    {ok,State,Data,InitOps++Ops};
+	{ok,State,Data} ->
+	    {ok,State,Data,InitOps};
+	Other ->
+	    Other
+    end;
+init([]) ->
     {ok,idle,state_data}.
 
 terminate(_, _State, crash_terminate) ->
@@ -1247,6 +1324,35 @@ handle_common_events(cast, {'alive?',Pid}, _, State, Data) ->
 handle_common_events(_, _, _, _, _) ->
     undefined.
 
+%% Dispatcher to test callback_mode handle_event_function
+%%
+%% Wrap the state in a 1 element list just to test non-atom
+%% states.  Note that the state from init/1 is not wrapped
+%% so both atom and non-atom states are tested.
+handle_event(Type, Event, PrevState, State, Data) ->
+    PrevStateName = unwrap(PrevState),
+    StateName = unwrap(State),
+    case
+	?MODULE:StateName(
+	   Type, Event, PrevStateName, StateName, Data) of
+	{next_state,NewState,NewStateData} ->
+	    {next_state,wrap(NewState),NewStateData};
+	{next_state,NewState,NewStateData,StateOps} ->
+	    {next_state,wrap(NewState),NewStateData,StateOps};
+	Other ->
+	    Other
+    end.
+
+unwrap([State]) ->
+    State;
+unwrap(State) ->
+    State.
+
+wrap(State) ->
+    [State].
+
+
+
 code_change(_OldVsn, State, StateData, _Extra) ->
     {ok,State,StateData}.
 
-- 
cgit v1.2.3


From b0357eba067295b61fac0128344d8c49a07254cf Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 17 Feb 2016 17:38:36 +0100
Subject: Clean up error report printouts

---
 lib/stdlib/src/gen_statem.erl | 76 ++++++++++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 23 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index e6bb38fc2c..782e027b29 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -217,6 +217,22 @@ event_type(Type) ->
 	    false
     end.
 
+
+
+-define(
+   STACKTRACE(),
+   try throw(ok) catch _ -> erlang:get_stacktrace() end).
+
+-define(
+   TERMINATE(Reason, Debug, S, Q),
+   terminate(
+     exit,
+     begin Reason end,
+     ?STACKTRACE(),
+     begin Debug end,
+     begin S end,
+     begin Q end)).
+
 %%%==========================================================================
 %%% API
 
@@ -455,7 +471,7 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
 	      State, StateData,
 	      [{retry,false}|StateOps]);
 	[Reason] ->
-	    terminate(Reason, Debug, S, [])
+	    ?TERMINATE(Reason, Debug, S, [])
     end.
 
 %%%==========================================================================
@@ -510,7 +526,7 @@ system_continue(Parent, Debug, S) ->
     loop(Parent, Debug, S).
 
 system_terminate(Reason, _Parent, Debug, S) ->
-    terminate(Reason, Debug, S, []).
+    ?TERMINATE(Reason, Debug, S, []).
 
 system_code_change(
   #{module := Module,
@@ -646,7 +662,7 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 		    %% EXIT is not a 2-tuple and therefore
 		    %% not an event and has no event_type(),
 		    %% but this will stand out in the crash report...
-		    terminate(Reason, Debug, S, [EXIT]);
+		    ?TERMINATE(Reason, Debug, S, [EXIT]);
 		{timeout,Timer,Content} when Timer =/= undefined ->
 		    loop_receive(
 		      Parent, Debug, S, {timeout,Content}, undefined);
@@ -727,7 +743,7 @@ loop_events(
 loop_event_result(Parent, Debug, S, Events, Event, Result) ->
     case Result of
 	{stop,Reason,NewStateData} ->
-	    terminate(
+	    ?TERMINATE(
 	      Reason, Debug,
 	      S#{state_data := NewStateData},
 	      [Event|Events]);
@@ -742,9 +758,10 @@ loop_event_result(Parent, Debug, S, Events, Event, Result) ->
 			[Reply]
 		end,
 	    BadReplies =
-		reply_then_terminate(Reason, Debug, NewS, Q, Replies),
+		reply_then_terminate(
+		  exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
 	    %% Since we got back here Replies was bad
-	    terminate(
+	    ?TERMINATE(
 	      {bad_return_value,{stop,Reason,BadReplies,NewStateData}},
 	      Debug, NewS, Q);
 	{next_state,NewState,NewStateData} ->
@@ -757,7 +774,7 @@ loop_event_result(Parent, Debug, S, Events, Event, Result) ->
 	      Parent, Debug, S, Events, Event,
 	      NewState, NewStateData, StateOps);
 	_ ->
-	    terminate(
+	    ?TERMINATE(
 	      {bad_return_value,Result}, Debug, S, [Event|Events])
     end.
 
@@ -815,14 +832,14 @@ loop_event_state_ops(
 			postponed := P},
 		      Q, Timer);
 		[Reason,Debug] ->
-		    terminate(Reason, Debug, S, [Event|Events]);
+		    ?TERMINATE(Reason, Debug, S, [Event|Events]);
 		[Class,Reason,Stacktrace,Debug] ->
 		    terminate(
 		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
 	    end;
 	%%
 	[Reason] ->
-	    terminate(Reason, Debug0, S, [Event|Events])
+	    ?TERMINATE(Reason, Debug0, S, [Event|Events])
     end.
 
 %%---------------------------------------------------------------------------
@@ -921,13 +938,15 @@ process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
 	    end
     end.
 
-reply_then_terminate(Reason, Debug, S, Q, []) ->
-    terminate(Reason, Debug, S, Q);
-reply_then_terminate(Reason, Debug, S, Q, [R|Rs] = RRs) ->
+reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
+    terminate(Class, Reason, Stacktrace, Debug, S, Q);
+reply_then_terminate(
+  Class, Reason, Stacktrace, Debug, S, Q, [R|Rs] = RRs) ->
     case R of
 	{reply,{_To,_Tag}=Client,Reply} ->
 	    NewDebug = do_reply(Debug, S, Client, Reply),
-	    reply_then_terminate(Reason, NewDebug, S, Q, Rs);
+	    reply_then_terminate(
+	      Class, Reason, Stacktrace, NewDebug, S, Q, Rs);
 	_ ->
 	    RRs % bad_return_value
     end.
@@ -1034,12 +1053,9 @@ cancel_timer(TimerRef) ->
     end.
 
 
-terminate(Reason, Debug, S, Q) ->
-    terminate(exit, Reason, [], Debug, S, Q).
-%%
 terminate(
   Class, Reason, Stacktrace, Debug,
-  #{name := Name, module := Module,
+  #{module := Module,
     state := State, state_data := StateData} = S,
   Q) ->
     try Module:terminate(Reason, State, StateData) of
@@ -1049,7 +1065,7 @@ terminate(
 	C:R ->
 	    ST = erlang:get_stacktrace(),
 	    error_info(
-	      C, R, ST, Debug, Name, Q,
+	      C, R, ST, Debug, S, Q,
 	      format_status(terminate, get(), S)),
 	    erlang:raise(C, R, ST)
     end,
@@ -1059,7 +1075,7 @@ terminate(
 	{shutdown,_} -> ok;
 	_ ->
 	    error_info(
-	      Class, Reason, Stacktrace, Debug, Name, Q,
+	      Class, Reason, Stacktrace, Debug, S, Q,
 	      format_status(terminate, get(), S))
     end,
     case Stacktrace of
@@ -1070,7 +1086,10 @@ terminate(
     end.
 
 error_info(
-  Class, Reason, Stacktrace, Debug, Name, Q, FmtStateData) ->
+  Class, Reason, Stacktrace, Debug,
+  #{name := Name, callback_mode := CallbackMode,
+    state := State, postponed := P},
+  Q, FmtStateData) ->
     {FixedReason,FixedStacktrace} =
 	case Stacktrace of
 	    [{M,F,Args,_}|ST]
@@ -1079,7 +1098,13 @@ error_info(
 		    false ->
 			{{'module could not be loaded',M},ST};
 		    _ ->
-			Arity = length(Args),
+			Arity =
+			    if
+				is_list(Args) ->
+				    length(Args);
+				is_integer(Args) ->
+				    Args
+			    end,
 			case erlang:function_exported(M, F, Arity) of
 			    true ->
 				{Reason,Stacktrace};
@@ -1100,6 +1125,9 @@ error_info(
 	  end ++
 	  "** When Server state  = ~p~n" ++
 	  "** Reason for termination = ~w:~p~n" ++
+	  "** State = ~p~n" ++
+	  "** Callback mode = ~p~n" ++
+	  "** Queued/Posponed = ~w/~w~n" ++
 	  case FixedStacktrace of
 	      [] ->
 		  "";
@@ -1110,10 +1138,12 @@ error_info(
       [Name |
        case Q of
 	   [] ->
-	       [FmtStateData,Class,FixedReason];
+	       [];
 	   [Event|_] ->
-	       [Event,FmtStateData,Class,FixedReason]
+	       [Event]
        end] ++
+	  [FmtStateData,Class,FixedReason,
+	   State,CallbackMode,length(Q),length(P)] ++
 	  case FixedStacktrace of
 	      [] ->
 		  [];
-- 
cgit v1.2.3


From 972a8fcb57a64c9a0dc7587e9072c15758e36da2 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 18 Feb 2016 10:22:50 +0100
Subject: Rename insert_event -> next_event

---
 lib/stdlib/doc/src/gen_statem.xml    | 130 ++++++++++++++++++++++-------------
 lib/stdlib/src/gen_statem.erl        |  15 ++--
 lib/stdlib/test/gen_statem_SUITE.erl |   2 +-
 3 files changed, 91 insertions(+), 56 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index f608e10469..5de1812b41 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -110,11 +110,28 @@ erlang:'!'            -----> Module:StateName/5
       states so you do not accidentally postpone one event
       forever creating an infinite busy loop.
     </p>
-    <p>
-      An event can can be postponed causing it to be retried
-      after the state has changed, or more precisely;
-      after a state change all postponed events are retried
-      in the new state.
+    <p>The gen_statem enqueues incoming events in order of arrival
+      and presents these to the
+      <seealso marker="#state_function">state function</seealso>
+      in that order.  The state function can postpone an event
+      so it is not retried in the current state.
+      After a state change all enqueued events (including postponed)
+      are again presented to the state function.
+    </p>
+    <p>The
+      <seealso marker="#state_function">state function</seealso>
+      can insert events using the
+      <seealso marker="#type-state_operation">
+	<c>state_operation()</c> <c>next_event</c>
+      </seealso>
+      and such an event is inserted as the next to present
+      to the state function.  That is: as if it is
+      the oldest incoming event.  There is a dedicated
+      <seealso marker="#type-event_type">
+        <c>event_type()</c> <c>internal</c>
+      </seealso>
+      that can be used for such events making it impossible
+      to mistake for an external event.
     </p>
     <p>A gen_statem handles system messages as documented in
        <seealso marker="sys">sys</seealso>.
@@ -302,7 +319,12 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="init_option" />
       <desc>
-	<p>Option that only is valid when initializing the gen_statem</p>
+	<p>Option that only is valid when initializing the gen_statem
+	  that is it can be returned from
+	  <seealso marker="#Module:init/1">Module:init/1</seealso>
+	  or given to
+	  <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
+	</p>
       </desc>
     </datatype>
     <datatype>
@@ -332,7 +354,7 @@ erlang:'!'            -----> Module:StateName/5
 	<p>Either a
 	  <seealso marker="#type-state_option">
 	    <c>state_option()</c>
-	  </seealso> of which the first occurence
+	  </seealso> of which the last occurence
 	  in the containing list takes precedence, or a
 	  <seealso marker="#type-state_operation">
 	    <c>state_operation()</c>
@@ -340,42 +362,34 @@ erlang:'!'            -----> Module:StateName/5
 	  the containing list.
 	</p>
 	<p>These may be returned from the
-	  <seealso marker="#state_function">state function</seealso>
-	  or from <seealso marker="#Module:init/1">Module:init/1</seealso>.
-	</p>
-	<p>The gen_statem enqueues postponed events and
-	  not yet processed events in order of arrival, except for
-	  an event that a callback function inserts with
-	  <c>{insert_event,EventType,EventContent}</c> that is inserted
-	  as the next event to process.
+	  <seealso marker="#state_function">state function</seealso>,
+	  from <seealso marker="#Module:init/1">Module:init/1</seealso>
+	  or given to
+	  <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
 	</p>
-	<p>When the state machine changes states all enqueued events
-	  becomes not yet processed to be processed before the old
-	  not yet processed events.  In other words; the order of arrival
-	  is retained.
-	</p>
-	<p>The processing order is:</p>
+	<p>The processing order for a state change is:</p>
 	<list type="ordered">
 	  <item>If the option <c>retry</c> is <c>true</c>
-	    the current event is enqueued as postponed to be retried.
+	    the current event is postponed.
 	  </item>
-	  <item>If the state changes all postponed events
-	    are transferred to not yet processed to be processed
-	    before other not yet processed events.
+	  <item>If the state changes the queue of incoming events
+	    is reset to start with the oldest postponed.
 	  </item>
 	  <item>All operations are processed in order of appearance.
 	  </item>
-	  <item>The <c>timeout</c> option is processed if present.
-	    So a state timer may be started or a timeout zero event
-	    may be inserted as if just received.
+	  <item>The <c>timeout</c> option is processed if present,
+	    so a state timer may be started or a timeout zero event
+	    may be enqueued as the newest incoming.
 	  </item>
 	  <item>The (possibly new)
 	    <seealso marker="#state_function">state function</seealso>
-	    is called with the next not yet processed event
-	    if there is any, otherwise the gen_statem goes into <c>receive</c>
+	    is called with the oldest enqueued event if there is any,
+	    otherwise the gen_statem goes into <c>receive</c>
 	    or hibernation (if the option <c>hibernate</c> is <c>true</c>)
 	    to wait for the next message.  In hibernation the next
-	    non-system event awakens the gen_statem.
+	    non-system event awakens the gen_statem, or rather
+	    the next incoming message awakens the gen_statem but if it
+	    is a system event it goes back into hibernation.
 	  </item>
 	</list>
       </desc>
@@ -383,12 +397,21 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="state_option" />
       <desc>
+	<p>If multiple state options of the same type are present
+	  in the containing list these are set in the list order
+	  and the last value is kept.
+	</p>
 	<taglist>
 	  <tag><c>retry</c></tag>
 	  <tag><c>{retry,<anno>Retry</anno>}</c></tag>
 	  <item>If <c><anno>Retry</anno> =:= true</c>
 	    or plain <c>retry</c> postpone the current event
 	    to be retried after a state change.
+	    This option is ignored when returned from
+	    <seealso marker="#Module:init/1">Module:init/1</seealso>
+	    or given to
+	    <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>
+	    since there is no event to postpone in those cases.
 	  </item>
 	  <tag><c>hibernate</c></tag>
 	  <tag><c>{hibernate,<anno>Hibernate</anno>}</c></tag>
@@ -397,9 +420,9 @@ erlang:'!'            -----> Module:StateName/5
 	    <seealso marker="proc_lib#hibernate/3">
 	      <c>proc_lib:hibernate/3</c>
 	    </seealso> before <c>receive</c> to wait for a new event.
-	    If there are not yet processed events the
-	    <c>hibernate</c> operation is ignored as if an event
-	    just arrived and awakened the gen_statem.
+	    If there are enqueued events the <c>hibernate</c> operation
+	    is ignored as if an event just arrived and awakened
+	    the gen_statem.
 	  </item>
 	  <tag>
 	    <c>{timeout,<anno>Time</anno>,<anno>Msg</anno>}</c>
@@ -426,14 +449,20 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="state_operation" />
       <desc>
+	<p>The state operations are executed in the containing
+	 list order.  This matters for <c>next_event</c> where
+	 the last one in the list will become the next event to present
+	 to the state functions.  Regarding the other operations
+	 it is only for <c>{remove_event,<anno>EventPredicate</anno>}</c>
+	 that the order may matter.
+	</p>
 	<taglist>
 	  <tag>
 	    <c>
-	      {insert_event,<anno>EventType</anno>,<anno>EventContent</anno>}
+	      {next_event,<anno>EventType</anno>,<anno>EventContent</anno>}
 	    </c>
 	  </tag>
-	  <item>Insert the given event as the next to process
-	    before any other not yet processed events.
+	  <item>Insert the given event as the next to process.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
@@ -982,7 +1011,13 @@ erlang:'!'            -----> Module:StateName/5
           <seealso marker="#call/2">gen_statem:call/2</seealso>,
           <seealso marker="#cast/2">gen_statem:cast/2</seealso> or
 	  as a normal process message this function is called.
-	  If the <c>EventType</c> is
+	  If
+	  <seealso marker="#type-callback_mode">callback_mode</seealso>
+	  is <c>state_functions</c> then <c>Module:StateName/5</c> is called,
+	  and if it is <c>handle_event_function</c>
+	  then <c>Module:handle_event/5</c> is called.
+	</p>
+	<p>If <c>EventType</c> is
 	  <seealso marker="#type-event_type"><c>{call,Client}</c></seealso>
 	  the client is waiting for a reply.  The reply can be sent
 	  from this or from any other
@@ -995,23 +1030,24 @@ erlang:'!'            -----> Module:StateName/5
 	    <c>gen_statem:reply(Client, Reply)</c>
 	  </seealso>.
 	</p>
-        <p><c>StateName</c> is rarely useful.  One exception is if
-	  you call a common event handling function from your state
+        <p><c>StateName</c> is useful in some odd cases for example
+	  if you call a common event handling function from your state
 	  function then you might want to pass <c>StateName</c>.
 	</p>
-	<p><c>PrevStateName</c> and <c>PrevState</c> are rarely useful.
-	  They can be used when you want to do something only at the
-	  first event in a state.  Note that when gen_statem enters
-	  its first state this is set to a <c>reference()</c> since
-	  that can not match the state.
+	<p><c>PrevStateName</c> and <c>PrevState</c> are useful
+	  in some odd cases for example when you want to do something
+	  only at the first event in a state.
+	  Note that when gen_statem enters its first state
+	  this is set to a <c>reference()</c>
+	  since that can not match equal to any state.
 	</p>
 	<p>If this function returns with a new state that
 	  does not match equal (<c>=/=</c>) to the current state
 	  all postponed events will be retried in the new state.
 	</p>
 	<p>See <seealso marker="#type-state_op">state_op()</seealso>
-	  for the operations that can be done by gen_statem
-	  after returning from this function.
+	  for options that can be set and operations that can be done
+	  by gen_statem after returning from this function.
 	</p>
       </desc>
     </func>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 782e027b29..52fde7df7b 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -88,7 +88,7 @@
 	%% These can occur multiple times and are executed in order
 	%% of appearence in the state_op() list
 	reply_operation() |
-	{'insert_event', % Insert event as the next to handle
+	{'next_event', % Insert event as the next to handle
 	 EventType :: event_type(),
 	 EventContent :: term()} |
 	{'remove_event', % Remove the oldest matching (=:=) event
@@ -469,7 +469,7 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
 	      S#{callback_mode := CallbackMode},
 	      [], {event,undefined},
 	      State, StateData,
-	      [{retry,false}|StateOps]);
+	      StateOps++[{retry,false}]);
 	[Reason] ->
 	    ?TERMINATE(Reason, Debug, S, [])
     end.
@@ -846,10 +846,10 @@ loop_event_state_ops(
 %% Server helpers
 
 collect_init_options(InitOps) ->
-    collect_init_options(lists:reverse(InitOps), state_functions, []).
+    collect_init_options(InitOps, state_functions, []).
 %% Keep the last of each kind
 collect_init_options([], CallbackMode, StateOps) ->
-    {CallbackMode,StateOps};
+    {CallbackMode,lists:reverse(StateOps)};
 collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) ->
     case InitOp of
 	{callback_mode,Mode}
@@ -864,12 +864,11 @@ collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) ->
     end.
 
 collect_state_options(StateOps) ->
-    collect_state_options(
-      lists:reverse(StateOps), false, false, undefined, []).
+    collect_state_options(StateOps, false, false, undefined, []).
 %% Keep the last of each kind
 collect_state_options(
   [], Retry, Hibernate, Timeout, Operations) ->
-    {Retry,Hibernate,Timeout,Operations};
+    {Retry,Hibernate,Timeout,lists:reverse(Operations)};
 collect_state_options(
   [StateOp|StateOps] = SOSOs, Retry, Hibernate, Timeout, Operations) ->
     case StateOp of
@@ -909,7 +908,7 @@ process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
 	{reply,{_To,_Tag}=Client,Reply} ->
 	    NewDebug = do_reply(Debug, S, Client, Reply),
 	    process_state_operations(Operations, NewDebug, S, Q, P);
-	{insert_event,Type,Content} ->
+	{next_event,Type,Content} ->
 	    case event_type(Type) of
 		true ->
 		    process_state_operations(
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 8a96f0e8e2..facc36fb9f 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1180,7 +1180,7 @@ timeout(timeout, idle, idle, timeout, {From,Time}) ->
     TRefC2 = erlang:start_timer(Time, self(), cancel2),
     {next_state,timeout2,{From,Time,TRef2},
      [{cancel_timer, TRefC1},
-      {insert_event,internal,{cancel_timer,TRefC2}}]};
+      {next_event,internal,{cancel_timer,TRefC2}}]};
 timeout(_, _, _, State, Data) ->
     {next_state,State,Data}.
 
-- 
cgit v1.2.3


From fdd72bc94149c7e279b5c4fd5a040af1886a4c72 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 18 Feb 2016 11:17:42 +0100
Subject: Rename retry -> postpone

---
 lib/stdlib/doc/src/gen_statem.xml    | 15 ++++++-------
 lib/stdlib/src/gen_statem.erl        | 42 ++++++++++++++++++------------------
 lib/stdlib/test/gen_statem_SUITE.erl | 11 ++++++++++
 3 files changed, 39 insertions(+), 29 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 5de1812b41..aeab09615c 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -369,7 +369,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>The processing order for a state change is:</p>
 	<list type="ordered">
-	  <item>If the option <c>retry</c> is <c>true</c>
+	  <item>If the option <c>postpone</c> is <c>true</c>
 	    the current event is postponed.
 	  </item>
 	  <item>If the state changes the queue of incoming events
@@ -402,10 +402,10 @@ erlang:'!'            -----> Module:StateName/5
 	  and the last value is kept.
 	</p>
 	<taglist>
-	  <tag><c>retry</c></tag>
-	  <tag><c>{retry,<anno>Retry</anno>}</c></tag>
-	  <item>If <c><anno>Retry</anno> =:= true</c>
-	    or plain <c>retry</c> postpone the current event
+	  <tag><c>postpone</c></tag>
+	  <tag><c>{postpone,<anno>Postpone</anno>}</c></tag>
+	  <item>If <c><anno>Postpone</anno> =:= true</c>
+	    or plain <c>postpone</c> postpone the current event
 	    to be retried after a state change.
 	    This option is ignored when returned from
 	    <seealso marker="#Module:init/1">Module:init/1</seealso>
@@ -434,9 +434,8 @@ erlang:'!'            -----> Module:StateName/5
 	    event counts just like a new in this respect.
 	    If <c>Time =:= infinity</c> or <c>Time =:= 0</c>
 	    no timer is started but for zero time the timeout
-	    event is enqued as just received after all
-	    other already received events.
-	    Also note that it is not possible
+	    event is immediately enqueued as the newest received.
+	    Also note that it is not possible nor needed
 	    to cancel this timeout using the
 	    <seealso marker="#type-state_operation">
 	      <c>state_operation()</c>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 52fde7df7b..32174687cf 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -70,15 +70,15 @@
 	%% First NewState and NewStateData are set,
 	%% then all state_operations() are executed in order of
 	%% apperance. Postponing the current event is performed
-	%% (iff state_option() 'retry' is 'true').
+	%% (iff state_option() 'postpone' is 'true').
 	%% Lastly pending events are processed or if there are
 	%% no pending events the server goes into receive
 	%% or hibernate (iff state_option() 'hibernate' is 'true')
 	state_option() | state_operation().
 -type state_option() ::
 	%% The first of each kind in the state_op() list takes precedence
-	'retry' |  % Postpone the current event to a different (=/=) state
-	{'retry', Retry :: boolean()} |
+	'postpone' |  % Postpone the current event to a different (=/=) state
+	{'postpone', Postpone :: boolean()} |
 	'hibernate' | % Hibernate the server instead of going into receive
 	{'hibernate', Hibernate :: boolean()} |
 	(Timeout :: timeout()) | % {timeout,Timeout}
@@ -469,7 +469,7 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
 	      S#{callback_mode := CallbackMode},
 	      [], {event,undefined},
 	      State, StateData,
-	      StateOps++[{retry,false}]);
+	      StateOps++[{postpone,false}]);
 	[Reason] ->
 	    ?TERMINATE(Reason, Debug, S, [])
     end.
@@ -782,9 +782,9 @@ loop_event_state_ops(
   Parent, Debug0, #{state := State, postponed := P0} = S, Events, Event,
   NewState, NewStateData, StateOps) ->
     case collect_state_options(StateOps) of
-	{Retry,Hibernate,Timeout,Operations} ->
-	    P1 = % Move current event to postponed if Retry
-		case Retry of
+	{Postpone,Hibernate,Timeout,Operations} ->
+	    P1 = % Move current event to postponed if Postpone
+		case Postpone of
 		    true ->
 			[Event|P0];
 		    false ->
@@ -804,9 +804,9 @@ loop_event_state_ops(
 		    NewDebug =
 			sys_debug(
 			  Debug, S,
-			  case Retry of
+			  case Postpone of
 			      true ->
-				  {retry,Event,NewState};
+				  {postpone,Event,NewState};
 			      false ->
 				  {consume,Event,NewState}
 			  end),
@@ -867,38 +867,38 @@ collect_state_options(StateOps) ->
     collect_state_options(StateOps, false, false, undefined, []).
 %% Keep the last of each kind
 collect_state_options(
-  [], Retry, Hibernate, Timeout, Operations) ->
-    {Retry,Hibernate,Timeout,lists:reverse(Operations)};
+  [], Postpone, Hibernate, Timeout, Operations) ->
+    {Postpone,Hibernate,Timeout,lists:reverse(Operations)};
 collect_state_options(
-  [StateOp|StateOps] = SOSOs, Retry, Hibernate, Timeout, Operations) ->
+  [StateOp|StateOps] = SOSOs, Postpone, Hibernate, Timeout, Operations) ->
     case StateOp of
-	retry ->
+	postpone ->
 	    collect_state_options(
 	      StateOps, true, Hibernate, Timeout, Operations);
-	{retry,NewRetry} when is_boolean(NewRetry) ->
+	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
 	    collect_state_options(
-	      StateOps, NewRetry, Hibernate, Timeout, Operations);
-	{retry,_} ->
+	      StateOps, NewPostpone, Hibernate, Timeout, Operations);
+	{postpone,_} ->
 	    [{bad_state_ops,SOSOs}];
 	hibernate ->
 	    collect_state_options(
-	      StateOps, Retry, true, Timeout, Operations);
+	      StateOps, Postpone, true, Timeout, Operations);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
 	    collect_state_options(
-	      StateOps, Retry, NewHibernate, Timeout, Operations);
+	      StateOps, Postpone, NewHibernate, Timeout, Operations);
 	{hibernate,_} ->
 	    [{bad_state_ops,SOSOs}];
 	{timeout,infinity,_} -> % Ignore since it will never time out
 	    collect_state_options(
-	      StateOps, Retry, Hibernate, undefined, Operations);
+	      StateOps, Postpone, Hibernate, undefined, Operations);
 	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
 	    collect_state_options(
-	      StateOps, Retry, Hibernate, NewTimeout, Operations);
+	      StateOps, Postpone, Hibernate, NewTimeout, Operations);
 	{timeout,_,_} ->
 	    [{bad_state_ops,SOSOs}];
 	_ -> % Collect others as operations
 	    collect_state_options(
-	      StateOps, Retry, Hibernate, Timeout, [StateOp|Operations])
+	      StateOps, Postpone, Hibernate, Timeout, [StateOp|Operations])
     end.
 
 process_state_operations([], Debug, _S, Q, P) ->
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index facc36fb9f..8b619b6a60 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1032,7 +1032,10 @@ do_connect(STM) ->
     gen_statem:cast(STM, {connect,self()}),
     wfor(accept),
     check_state(STM, wfor_conf),
+    Tag = make_ref(),
+    gen_statem:cast(STM, {ping,self(),Tag}),
     gen_statem:cast(STM, confirm),
+    wfor({pong,Tag}),
     check_state(STM, connected),
     ok.
 
@@ -1071,7 +1074,10 @@ do_sync_connect(STM) ->
     check_state(STM, idle),
     accept = gen_statem:call(STM, connect),
     check_state(STM, wfor_conf),
+    Tag = make_ref(),
+    gen_statem:cast(STM, {ping,self(),Tag}),
     yes = gen_statem:call(STM, confirm),
+    wfor({pong,Tag}),
     check_state(STM, connected),
     ok.
 
@@ -1202,6 +1208,8 @@ timeout3(_, _, _, State, Data) ->
 wfor_conf({call,From}, confirm, _, _, Data) ->
     {next_state,connected,Data,
      [{reply,From,yes}]};
+wfor_conf(cast, {ping,_,_}, _, State, Data) ->
+    {next_state,State,Data,[postpone]};
 wfor_conf(cast, confirm, _, _, Data) ->
     {next_state,connected,Data};
 wfor_conf(Type, Content, PrevState, State, Data) ->
@@ -1229,6 +1237,9 @@ connected({call,From}, disconnect, _, _, Data) ->
      [{reply,From,yes}]};
 connected(cast, disconnect, _, _, Data) ->
     {next_state,idle,Data};
+connected(cast, {ping,Pid,Tag}, _, State, Data) ->
+    Pid ! {pong,Tag},
+    {next_state,State,Data};
 connected(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
 	undefined ->
-- 
cgit v1.2.3


From 82f34a7a9de85b4afc0dac4c9c426939264c5039 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 18 Feb 2016 16:06:57 +0100
Subject: Write some convenience helpers

---
 lib/stdlib/doc/src/gen_statem.xml    | 23 +++++++++++++++++++++
 lib/stdlib/src/gen_statem.erl        | 39 +++++++++++++++++++++++++++++-------
 lib/stdlib/test/gen_statem_SUITE.erl | 24 +++++++++++-----------
 3 files changed, 67 insertions(+), 19 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index aeab09615c..5fbedb12f8 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -534,6 +534,13 @@ erlang:'!'            -----> Module:StateName/5
       <name name="state_callback_result" />
       <desc>
 	<taglist>
+	  <tag>
+	   <c>{stop,<anno>Reason</anno>}</c>
+	  </tag>
+	  <item>The same as
+	    <c>{stop,<anno>Reason</anno>,[],StateData}</c>
+	    but keeps the old <c>StateData</c>.
+	  </item>
 	  <tag>
 	   <c>{stop,<anno>Reason</anno>,<anno>NewStateData</anno>}</c>
 	  </tag>
@@ -551,6 +558,19 @@ erlang:'!'            -----> Module:StateName/5
 	      <c>Module:terminate/3</c>
 	    </seealso> with <c>Reason</c>.
 	  </item>
+	  <tag>
+	    <c>
+	      {next_state,<anno>StateOps</anno>}
+	    </c>
+	  </tag>
+	  <item>The same as
+	    <c>
+	      {next_state,State,StateData,<anno>StateOps</anno>}
+	    </c>but keeps the old <c>State</c> and <c>StateData</c>.
+	    Believe it or not, but this one has actually
+	    been proven useful to <c>throw/1</c> from deep down
+	    in the state logic.
+	  </item>
 	  <tag>
 	    <c>
 	      {next_state,<anno>NewState</anno>,<anno>NewStateData</anno>}
@@ -805,6 +825,7 @@ erlang:'!'            -----> Module:StateName/5
     </func>
 
     <func>
+      <name name="reply" arity="1" />
       <name name="reply" arity="2" />
       <fsummary>Send a reply to a client</fsummary>
       <desc>
@@ -820,6 +841,8 @@ erlang:'!'            -----> Module:StateName/5
 	    <c>{call,<anno>Client</anno>}</c>
 	  </seealso> argument to the
 	  <seealso marker="#state_function">state function</seealso>.
+	  <c><anno>Client</anno></c> and <c><anno>Reply</anno></c>
+	  an also be specified using <c><anno>ReplyOperation</anno></c>.
 	</p>
 	<note>
 	  <p>A reply sent with this function will not be visible
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 32174687cf..486f61b1ed 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -25,7 +25,7 @@
     stop/1,stop/3,
     cast/2,call/2,call/3,
     enter_loop/4,enter_loop/5,enter_loop/6,
-    reply/2]).
+    reply/1,reply/2]).
 
 %% gen callbacks
 -export(
@@ -105,17 +105,21 @@
 	{'reply', % Reply to a client
 	 Client :: client(), Reply :: term()}.
 -type state_callback_result() ::
-    {stop, % Stop the server
+    {'stop', % Stop the server
+     Reason :: term()} |
+    {'stop', % Stop the server
      Reason :: term(),
      NewStateData :: state_data()} |
-    {stop, % Stop the server
+    {'stop', % Stop the server
      Reason :: term(),
      Replies :: [reply_operation()] | reply_operation(),
      NewStateData :: state_data()} |
-    {next_state, % {next_state,NewState,NewStateData,[]}
+    {'next_state', % {next_state,State,StateData,StateOps} % Actually useful
+     StateOps :: [state_op()] | state_op()} |
+    {'next_state', % {next_state,NewState,NewStateData,[]}
      NewState :: state(),
      NewStateData :: state_data()} |
-    {next_state, % State transition, maybe to the same state
+    {'next_state', % State transition, maybe to the same state
      NewState :: state(),
      NewStateData :: state_data(),
      StateOps :: [state_op()] | state_op()}.
@@ -379,6 +383,10 @@ call(ServerRef, Request, Timeout) ->
     end.
 
 %% Reply from a state machine callback to whom awaits in call/2
+-spec reply(ReplyOperation :: reply_operation()) -> ok.
+reply({reply,{_To,_Tag}=Client,Reply}) ->
+    reply(Client, Reply).
+%%
 -spec reply(Client :: client(), Reply :: term()) -> ok.
 reply({To,Tag}, Reply) ->
     Msg = {Tag,Reply},
@@ -742,6 +750,8 @@ loop_events(
 %% Interpret all callback return value variants
 loop_event_result(Parent, Debug, S, Events, Event, Result) ->
     case Result of
+	{stop,Reason} ->
+	    ?TERMINATE(Reason, Debug, S, [Event|Events]);
 	{stop,Reason,NewStateData} ->
 	    ?TERMINATE(
 	      Reason, Debug,
@@ -764,6 +774,11 @@ loop_event_result(Parent, Debug, S, Events, Event, Result) ->
 	    ?TERMINATE(
 	      {bad_return_value,{stop,Reason,BadReplies,NewStateData}},
 	      Debug, NewS, Q);
+	{next_state,StateOps} ->
+	    #{state := State, state_data := StateData} = S,
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, StateData, StateOps);
 	{next_state,NewState,NewStateData} ->
 	    loop_event_state_ops(
 	      Parent, Debug, S, Events, Event,
@@ -846,7 +861,12 @@ loop_event_state_ops(
 %% Server helpers
 
 collect_init_options(InitOps) ->
-    collect_init_options(InitOps, state_functions, []).
+    if
+	is_list(InitOps) ->
+	    collect_init_options(InitOps, state_functions, []);
+	true ->
+	    collect_init_options([InitOps], state_functions, [])
+    end.
 %% Keep the last of each kind
 collect_init_options([], CallbackMode, StateOps) ->
     {CallbackMode,lists:reverse(StateOps)};
@@ -864,7 +884,12 @@ collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) ->
     end.
 
 collect_state_options(StateOps) ->
-    collect_state_options(StateOps, false, false, undefined, []).
+    if
+	is_list(StateOps) ->
+	    collect_state_options(StateOps, false, false, undefined, []);
+	true ->
+	    collect_state_options([StateOps], false, false, undefined, [])
+    end.
 %% Keep the last of each kind
 collect_state_options(
   [], Postpone, Hibernate, Timeout, Operations) ->
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 8b619b6a60..6249ada027 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1158,11 +1158,10 @@ idle(cast, badreturn, _, _, _Data) ->
     badreturn;
 idle({call,_From}, badreturn, _, _, _Data) ->
     badreturn;
-idle({call,From}, {delayed_answer,T}, _, State, Data) ->
+idle({call,From}, {delayed_answer,T}, _, _, _) ->
     receive
     after T ->
-	    {next_state,State,Data,
-	     [{reply,From,delayed}]}
+	    throw({next_state,{reply,From,delayed}})
     end;
 idle({call,From}, {timeout,Time}, _, State, _Data) ->
     {next_state,timeout,{From,Time},
@@ -1172,9 +1171,10 @@ idle(Type, Content, PrevState, State, Data) ->
 	undefined ->
 	    case Type of
 		{call,From} ->
-		    {next_state,State,Data,[{reply,From,'eh?'}]};
+		    throw({next_state,[{reply,From,'eh?'}]});
 		_ ->
-		    {stop,{unexpected,State,PrevState,Type,Content},Data}
+		    throw(
+		      {stop,{unexpected,State,PrevState,Type,Content}})
 	    end;
 	Result ->
 	    Result
@@ -1208,8 +1208,8 @@ timeout3(_, _, _, State, Data) ->
 wfor_conf({call,From}, confirm, _, _, Data) ->
     {next_state,connected,Data,
      [{reply,From,yes}]};
-wfor_conf(cast, {ping,_,_}, _, State, Data) ->
-    {next_state,State,Data,[postpone]};
+wfor_conf(cast, {ping,_,_}, _, _, _) ->
+    {next_state,[postpone]};
 wfor_conf(cast, confirm, _, _, Data) ->
     {next_state,connected,Data};
 wfor_conf(Type, Content, PrevState, State, Data) ->
@@ -1220,7 +1220,7 @@ wfor_conf(Type, Content, PrevState, State, Data) ->
 		    {next_state,idle,Data,
 		     [{reply,From,'eh?'}]};
 		_ ->
-		    {next_state,State,Data}
+		    throw({next_state,[]})
 	    end;
 	Result ->
 	    Result
@@ -1320,12 +1320,12 @@ handle_common_events(cast, {get,Pid}, _, State, Data) ->
     {next_state,State,Data};
 handle_common_events({call,From}, stop, _, _, Data) ->
     {stop,normal,[{reply,From,stopped}],Data};
-handle_common_events(cast, stop, _, _, Data) ->
-    {stop,normal,Data};
+handle_common_events(cast, stop, _, _, _) ->
+    {stop,normal};
 handle_common_events({call,From}, {stop,Reason}, _, _, Data) ->
     {stop,Reason,{reply,From,stopped},Data};
-handle_common_events(cast, {stop,Reason}, _, _, Data) ->
-     {stop,Reason,Data};
+handle_common_events(cast, {stop,Reason}, _, _, _) ->
+     {stop,Reason};
 handle_common_events({call,From}, 'alive?', _, State, Data) ->
     {next_state,State,Data,
      [{reply,From,yes}]};
-- 
cgit v1.2.3


From 26a7af61fbffae90c0968d945ae8b146582ba068 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 18 Feb 2016 16:38:57 +0100
Subject: Change initial PrevState to 'undefined'

---
 lib/stdlib/doc/src/gen_statem.xml | 27 ++++++++++++++++++++++++---
 lib/stdlib/src/gen_statem.erl     |  7 ++++---
 2 files changed, 28 insertions(+), 6 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 5fbedb12f8..9d98763973 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -110,6 +110,14 @@ erlang:'!'            -----> Module:StateName/5
       states so you do not accidentally postpone one event
       forever creating an infinite busy loop.
     </p>
+    <p>Any state name or any state value (depending on
+      <seealso marker="#type-callback_mode">callback_mode</seealso>)
+      is permitted with a small gotcha regarding the state
+      <c>undefined</c> that is used as the previous state when
+      the first gen_statem state function is called.
+      You might need to know about this faked state if you
+      inspect the previous state argument in your state functions.
+    </p>
     <p>The gen_statem enqueues incoming events in order of arrival
       and presents these to the
       <seealso marker="#state_function">state function</seealso>
@@ -118,6 +126,12 @@ erlang:'!'            -----> Module:StateName/5
       After a state change all enqueued events (including postponed)
       are again presented to the state function.
     </p>
+    <p>The gen_statem event queue model is sufficient to emulate
+      the normal process message queue and selective receive
+      with postponing an event corresponding to not matching
+      it in a receive statement and changing states corresponding
+      to entering a new receive statement.
+    </p>
     <p>The
       <seealso marker="#state_function">state function</seealso>
       can insert events using the
@@ -133,6 +147,15 @@ erlang:'!'            -----> Module:StateName/5
       that can be used for such events making it impossible
       to mistake for an external event.
     </p>
+    <p>Inserting an event replaces the trick of calling your own
+      state handling functions that you often would have to
+      resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
+      to force processing a faked event before others.
+      If you for example in gen_statem postpone an event
+      in one state and then call some other state function of yours,
+      you have not changed states and hence the postponed event
+      will not be retried, which is logical but might be confusing.
+    </p>
     <p>A gen_statem handles system messages as documented in
        <seealso marker="sys">sys</seealso>.
        The <seealso marker="sys">sys</seealso> module
@@ -1011,7 +1034,6 @@ erlang:'!'            -----> Module:StateName/5
 	<v>EventContent = term()</v>
 	<v>PrevStateName =
 	  <seealso marker="#type-state_name">state_name()</seealso>
-	  | reference()
 	</v>
 	<v>StateName =
 	  <seealso marker="#type-state_name">state_name()</seealso>
@@ -1060,8 +1082,7 @@ erlang:'!'            -----> Module:StateName/5
 	  in some odd cases for example when you want to do something
 	  only at the first event in a state.
 	  Note that when gen_statem enters its first state
-	  this is set to a <c>reference()</c>
-	  since that can not match equal to any state.
+	  this is set to <c>undefined</c>.
 	</p>
 	<p>If this function returns with a new state that
 	  does not match equal (<c>=/=</c>) to the current state
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 486f61b1ed..e03e22b087 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -459,13 +459,13 @@ do_send(Proc, Msg) ->
 enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
     Name = gen:get_proc_name(Server),
     Debug = gen:debug_options(Name, Options),
-    PrevState = make_ref(),
+    PrevState = undefined,
     S = #{
       callback_mode => state_functions,
       module => Module,
       name => Name,
       prev_state => PrevState,
-      state => PrevState,
+      state => PrevState, % Will be discarded by loop_event_state_ops
       state_data => StateData,
       timer => undefined,
       postponed => [],
@@ -475,7 +475,8 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
 	    loop_event_state_ops(
 	      Parent, Debug,
 	      S#{callback_mode := CallbackMode},
-	      [], {event,undefined},
+	      [],
+	      {event,undefined}, % Will be discarded by {postpone,false}
 	      State, StateData,
 	      StateOps++[{postpone,false}]);
 	[Reason] ->
-- 
cgit v1.2.3


From 65767cfc36cf8658b45d68b3c17d4bd612198165 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 19 Feb 2016 09:22:52 +0100
Subject: Add {keep_state,...} and {keep_state_and_data,...}

---
 lib/stdlib/doc/src/gen_statem.xml    | 61 ++++++++++++++++++++++++++----------
 lib/stdlib/src/gen_statem.erl        | 46 +++++++++++++++++++--------
 lib/stdlib/test/gen_statem_SUITE.erl | 44 +++++++++++++++-----------
 3 files changed, 102 insertions(+), 49 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 9d98763973..f66f399137 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -475,8 +475,9 @@ erlang:'!'            -----> Module:StateName/5
 	 list order.  This matters for <c>next_event</c> where
 	 the last one in the list will become the next event to present
 	 to the state functions.  Regarding the other operations
-	 it is only for <c>{remove_event,<anno>EventPredicate</anno>}</c>
-	 that the order may matter.
+	 it is only for <c>remove_event</c> with
+	 <c><anno>EventPredicate</anno></c>
+	 and for <c>reply_operation()</c> that the order may matter.
 	</p>
 	<taglist>
 	  <tag>
@@ -581,19 +582,6 @@ erlang:'!'            -----> Module:StateName/5
 	      <c>Module:terminate/3</c>
 	    </seealso> with <c>Reason</c>.
 	  </item>
-	  <tag>
-	    <c>
-	      {next_state,<anno>StateOps</anno>}
-	    </c>
-	  </tag>
-	  <item>The same as
-	    <c>
-	      {next_state,State,StateData,<anno>StateOps</anno>}
-	    </c>but keeps the old <c>State</c> and <c>StateData</c>.
-	    Believe it or not, but this one has actually
-	    been proven useful to <c>throw/1</c> from deep down
-	    in the state logic.
-	  </item>
 	  <tag>
 	    <c>
 	      {next_state,<anno>NewState</anno>,<anno>NewStateData</anno>}
@@ -614,8 +602,47 @@ erlang:'!'            -----> Module:StateName/5
 	  </tag>
 	  <item>The gen_statem will do a state transition to
 	    <c><anno>NewState</anno></c>
-	    (which may be the same as <c>State</c>)
-	    and execute all <c>StateOps</c>
+	    (which may be the same as the current state)
+	    and execute all <c><anno>StateOps</anno></c>
+	  </item>
+	  <tag>
+	    <c>
+	      {keep_state,<anno>NewStateData</anno>}}
+	    </c>
+	  </tag>
+	  <item>The same as
+	    <c>
+	      {keep_state,<anno>NewStateData</anno>,[]}
+	    </c>
+	  </item>
+	  <tag>
+	    <c>
+	      {keep_state,<anno>NewStateData</anno>,<anno>StateOps</anno>}
+	    </c>
+	  </tag>
+	  <item>The gen_statem will keep the current state, or
+	    do a state transition to the current state if you like,
+	    and execute all <c><anno>StateOps</anno></c>
+	  </item>
+	  <tag>
+	    <c>
+	      {keep_state_and_data}
+	    </c>
+	  </tag>
+	  <item>The same as
+	    <c>
+	      {keep_state_and_data,[]}
+	    </c>
+	  </item>
+	  <tag>
+	    <c>
+	      {keep_state_and_data,<anno>StateOps</anno>}
+	    </c>
+	  </tag>
+	  <item>The gen_statem will keep the current state, or
+	    do a state transition to the current state if you like,
+	    also keep the current state data,
+	    and execute all <c><anno>StateOps</anno></c>
 	  </item>
 	</taglist>
       </desc>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index e03e22b087..3da4443f13 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -114,14 +114,20 @@
      Reason :: term(),
      Replies :: [reply_operation()] | reply_operation(),
      NewStateData :: state_data()} |
-    {'next_state', % {next_state,State,StateData,StateOps} % Actually useful
-     StateOps :: [state_op()] | state_op()} |
     {'next_state', % {next_state,NewState,NewStateData,[]}
      NewState :: state(),
      NewStateData :: state_data()} |
     {'next_state', % State transition, maybe to the same state
      NewState :: state(),
      NewStateData :: state_data(),
+     StateOps :: [state_op()] | state_op()} |
+    {'keep_state', % {keep_state,NewStateData,[]}
+     NewStateData :: state_data()} |
+    {'keep_state',
+     NewStateData :: state_data(),
+     StateOps :: [state_op()] | state_op()} |
+    {'keep_state_and_data'} | % {keep_state_and_data,[]}
+    {'keep_state_and_data',
      StateOps :: [state_op()] | state_op()}.
 
 %% The state machine init function.  It is called only once and
@@ -477,7 +483,7 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
 	      S#{callback_mode := CallbackMode},
 	      [],
 	      {event,undefined}, % Will be discarded by {postpone,false}
-	      State, StateData,
+	      PrevState, State, StateData,
 	      StateOps++[{postpone,false}]);
 	[Reason] ->
 	    ?TERMINATE(Reason, Debug, S, [])
@@ -749,7 +755,10 @@ loop_events(
     end.
 
 %% Interpret all callback return value variants
-loop_event_result(Parent, Debug, S, Events, Event, Result) ->
+loop_event_result(
+  Parent, Debug,
+  #{state := State, state_data := StateData} = S,
+  Events, Event, Result) ->
     case Result of
 	{stop,Reason} ->
 	    ?TERMINATE(Reason, Debug, S, [Event|Events]);
@@ -775,28 +784,39 @@ loop_event_result(Parent, Debug, S, Events, Event, Result) ->
 	    ?TERMINATE(
 	      {bad_return_value,{stop,Reason,BadReplies,NewStateData}},
 	      Debug, NewS, Q);
-	{next_state,StateOps} ->
-	    #{state := State, state_data := StateData} = S,
-	    loop_event_state_ops(
-	      Parent, Debug, S, Events, Event,
-	      State, StateData, StateOps);
 	{next_state,NewState,NewStateData} ->
 	    loop_event_state_ops(
 	      Parent, Debug, S, Events, Event,
-	      NewState, NewStateData, []);
+	      State, NewState, NewStateData, []);
 	{next_state,NewState,NewStateData,StateOps}
 	  when is_list(StateOps) ->
 	    loop_event_state_ops(
 	      Parent, Debug, S, Events, Event,
-	      NewState, NewStateData, StateOps);
+	      State, NewState, NewStateData, StateOps);
+	{keep_state,NewStateData} ->
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, State, NewStateData, []);
+	{keep_state,NewStateData,StateOps} ->
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, State, NewStateData, StateOps);
+	{keep_state_and_data} ->
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, State, StateData, []);
+	{keep_state_and_data,StateOps} ->
+	    loop_event_state_ops(
+	      Parent, Debug, S, Events, Event,
+	      State, State, StateData, StateOps);
 	_ ->
 	    ?TERMINATE(
 	      {bad_return_value,Result}, Debug, S, [Event|Events])
     end.
 
 loop_event_state_ops(
-  Parent, Debug0, #{state := State, postponed := P0} = S, Events, Event,
-  NewState, NewStateData, StateOps) ->
+  Parent, Debug0, #{postponed := P0} = S, Events, Event,
+  State, NewState, NewStateData, StateOps) ->
     case collect_state_options(StateOps) of
 	{Postpone,Hibernate,Timeout,Operations} ->
 	    P1 = % Move current event to postponed if Postpone
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 6249ada027..92dc59e843 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1158,10 +1158,10 @@ idle(cast, badreturn, _, _, _Data) ->
     badreturn;
 idle({call,_From}, badreturn, _, _, _Data) ->
     badreturn;
-idle({call,From}, {delayed_answer,T}, _, _, _) ->
+idle({call,From}, {delayed_answer,T}, _, _, Data) ->
     receive
     after T ->
-	    throw({next_state,{reply,From,delayed}})
+	    throw({keep_state,Data,{reply,From,delayed}})
     end;
 idle({call,From}, {timeout,Time}, _, State, _Data) ->
     {next_state,timeout,{From,Time},
@@ -1171,7 +1171,7 @@ idle(Type, Content, PrevState, State, Data) ->
 	undefined ->
 	    case Type of
 		{call,From} ->
-		    throw({next_state,[{reply,From,'eh?'}]});
+		    throw({keep_state,Data,[{reply,From,'eh?'}]});
 		_ ->
 		    throw(
 		      {stop,{unexpected,State,PrevState,Type,Content}})
@@ -1209,7 +1209,7 @@ wfor_conf({call,From}, confirm, _, _, Data) ->
     {next_state,connected,Data,
      [{reply,From,yes}]};
 wfor_conf(cast, {ping,_,_}, _, _, _) ->
-    {next_state,[postpone]};
+    {keep_state_and_data,[postpone]};
 wfor_conf(cast, confirm, _, _, Data) ->
     {next_state,connected,Data};
 wfor_conf(Type, Content, PrevState, State, Data) ->
@@ -1220,7 +1220,7 @@ wfor_conf(Type, Content, PrevState, State, Data) ->
 		    {next_state,idle,Data,
 		     [{reply,From,'eh?'}]};
 		_ ->
-		    throw({next_state,[]})
+		    throw({keep_state_and_data})
 	    end;
 	Result ->
 	    Result
@@ -1341,26 +1341,32 @@ handle_common_events(_, _, _, _, _) ->
 %% states.  Note that the state from init/1 is not wrapped
 %% so both atom and non-atom states are tested.
 handle_event(Type, Event, PrevState, State, Data) ->
-    PrevStateName = unwrap(PrevState),
-    StateName = unwrap(State),
-    case
-	?MODULE:StateName(
+    PrevStateName = unwrap_state(PrevState),
+    StateName = unwrap_state(State),
+    try ?MODULE:StateName(
 	   Type, Event, PrevStateName, StateName, Data) of
-	{next_state,NewState,NewStateData} ->
-	    {next_state,wrap(NewState),NewStateData};
-	{next_state,NewState,NewStateData,StateOps} ->
-	    {next_state,wrap(NewState),NewStateData,StateOps};
-	Other ->
-	    Other
+	Result ->
+	    wrap_result(Result)
+    catch
+	throw:Result ->
+	    erlang:raise(
+	      throw, wrap_result(Result), erlang:get_stacktrace())
     end.
 
-unwrap([State]) ->
+unwrap_state([State]) ->
     State;
-unwrap(State) ->
+unwrap_state(State) ->
     State.
 
-wrap(State) ->
-    [State].
+wrap_result(Result) ->
+    case Result of
+	{next_state,NewState,NewStateData} ->
+	    {next_state,[NewState],NewStateData};
+	{next_state,NewState,NewStateData,StateOps} ->
+	    {next_state,[NewState],NewStateData,StateOps};
+	Other ->
+	    Other
+    end.
 
 
 
-- 
cgit v1.2.3


From fc1e649e3613f18dec8514921d0439ddcca73bdb Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 19 Feb 2016 09:39:46 +0100
Subject: Add reply([Reply])

---
 lib/stdlib/doc/src/gen_statem.xml    |  5 ++++-
 lib/stdlib/src/gen_statem.erl        |  7 +++++--
 lib/stdlib/test/gen_statem_SUITE.erl | 10 ++++++----
 3 files changed, 15 insertions(+), 7 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index f66f399137..5f9ec6736e 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -892,7 +892,10 @@ erlang:'!'            -----> Module:StateName/5
 	  </seealso> argument to the
 	  <seealso marker="#state_function">state function</seealso>.
 	  <c><anno>Client</anno></c> and <c><anno>Reply</anno></c>
-	  an also be specified using <c><anno>ReplyOperation</anno></c>.
+	  can also be specified using a
+	  <seealso marker="#type-reply_operation">
+	    <c>reply_operation()</c>
+	  </seealso> and multiple replies with a list of them.
 	</p>
 	<note>
 	  <p>A reply sent with this function will not be visible
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 3da4443f13..8aa8afd091 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -389,9 +389,12 @@ call(ServerRef, Request, Timeout) ->
     end.
 
 %% Reply from a state machine callback to whom awaits in call/2
--spec reply(ReplyOperation :: reply_operation()) -> ok.
+-spec reply([reply_operation()] | reply_operation()) -> ok.
 reply({reply,{_To,_Tag}=Client,Reply}) ->
-    reply(Client, Reply).
+    reply(Client, Reply);
+reply(Replies) when is_list(Replies) ->
+    [reply(Reply) || Reply <- Replies],
+    ok.
 %%
 -spec reply(Client :: client(), Reply :: term()) -> ok.
 reply({To,Tag}, Reply) ->
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 92dc59e843..4ac4acd189 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1153,7 +1153,8 @@ idle(cast, {connect,Pid}, _, _, Data) ->
     Pid ! accept,
     {next_state,wfor_conf,Data};
 idle({call,From}, connect, _, _, Data) ->
-    {next_state,wfor_conf,Data,[{reply,From,accept}]};
+    gen_statem:reply(From, accept),
+    {next_state,wfor_conf,Data};
 idle(cast, badreturn, _, _, _Data) ->
     badreturn;
 idle({call,_From}, badreturn, _, _, _Data) ->
@@ -1161,7 +1162,8 @@ idle({call,_From}, badreturn, _, _, _Data) ->
 idle({call,From}, {delayed_answer,T}, _, _, Data) ->
     receive
     after T ->
-	    throw({keep_state,Data,{reply,From,delayed}})
+	    gen_statem:reply({reply,From,delayed}),
+	    throw({keep_state,Data})
     end;
 idle({call,From}, {timeout,Time}, _, State, _Data) ->
     {next_state,timeout,{From,Time},
@@ -1200,8 +1202,8 @@ timeout2(_, _, _, State, Data) ->
     {next_state,State,Data}.
 
 timeout3(info, {timeout,TRef2,Result}, _, _, {From,TRef2}) ->
-    {next_state,idle,state,
-     [{reply,From,Result}]};
+    gen_statem:reply([{reply,From,Result}]),
+    {next_state,idle,state};
 timeout3(_, _, _, State, Data) ->
     {next_state,State,Data}.
 
-- 
cgit v1.2.3


From 8cc0a419f847103199524e3d922a1087d23d8d8a Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 19 Feb 2016 10:31:03 +0100
Subject: Shorten taglists in the documentation

---
 lib/stdlib/doc/src/gen_statem.xml | 193 +++++++++++---------------------------
 1 file changed, 57 insertions(+), 136 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 5f9ec6736e..9cddce98da 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -207,19 +207,19 @@ erlang:'!'            -----> Module:StateName/5
 	  </seealso> above.
 	</p>
 	<p>It can be:</p>
-	<list type="bulleted">
-          <item>the <c>pid()</c>,</item>
-          <item><c><anno>Name</anno></c>,
-	    if the gen_statem is locally registered,
-	  </item>
-          <item><c>{<anno>Name</anno>,<anno>Node</anno>}</c>,
-	    if the gen_statem is locally registered at another node, or
+	<taglist>
+	  <tag><c>pid()</c></tag>
+	  <tag><c>LocalName</c></tag>
+	  <item>The gen_statem is locally registered.</item>
+	  <tag><c>Name, Node</c></tag>
+	  <item>The gen_statem is locally registered on another node.
 	  </item>
-          <item><c>{global,<anno>GlobalName</anno>}</c>,
-	    if the gen_statem is globally registered.
+	  <tag><c>GlobalName</c></tag>
+	  <item>The gen_statem is globally registered
+	    in <seealso marker="kernel:global"><c>global</c></seealso>.
 	  </item>
-          <item><c>{via,<anno>RegMod</anno>,<anno>ViaName</anno>}</c>,
-	    if the gen_statem is registered through
+	  <tag><c>RegMod, ViaName</c></tag>
+	  <item>The gen_statem is registered through
 	    an alternative process registry.
 	    The registry callback module <c>RegMod</c>
 	    should export the functions
@@ -230,7 +230,7 @@ erlang:'!'            -----> Module:StateName/5
 	    Thus, <c>{via,global,GlobalName}</c> is the same as
 	    <c>{global,GlobalName}</c>.
 	  </item>
-        </list>
+	</taglist>
       </desc>
     </datatype>
     <datatype>
@@ -268,9 +268,10 @@ erlang:'!'            -----> Module:StateName/5
       <name name="client" />
       <desc>
 	<p>Client address to use when replying through for example the
-	  <seealso marker="#type-state_op">state_op()</seealso>
-	  <c>{reply,Client,Reply}</c> to a client
-	  that has called the gen_statem server using
+	  <seealso marker="#type-state_op">
+	    state_op() {reply,Client,Reply}
+	  </seealso>
+	  to a client that has called the gen_statem server using
 	  <seealso marker="#call/2">call/2</seealso>.
 	</p>
       </desc>
@@ -426,7 +427,6 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<taglist>
 	  <tag><c>postpone</c></tag>
-	  <tag><c>{postpone,<anno>Postpone</anno>}</c></tag>
 	  <item>If <c><anno>Postpone</anno> =:= true</c>
 	    or plain <c>postpone</c> postpone the current event
 	    to be retried after a state change.
@@ -437,7 +437,6 @@ erlang:'!'            -----> Module:StateName/5
 	    since there is no event to postpone in those cases.
 	  </item>
 	  <tag><c>hibernate</c></tag>
-	  <tag><c>{hibernate,<anno>Hibernate</anno>}</c></tag>
 	  <item>If <c><anno>Hibernate</anno> =:= true</c>
 	    or plain <c>hibernate</c> hibernate the gen_statem by calling
 	    <seealso marker="proc_lib#hibernate/3">
@@ -447,17 +446,16 @@ erlang:'!'            -----> Module:StateName/5
 	    is ignored as if an event just arrived and awakened
 	    the gen_statem.
 	  </item>
-	  <tag>
-	    <c>{timeout,<anno>Time</anno>,<anno>Msg</anno>}</c>
+	  <tag><c>timeout</c>
 	  </tag>
 	  <item>Generate an event of
 	    <seealso marker="#type-event_type">type <c>timeout</c></seealso>
 	    after <c><anno>Time</anno></c> milliseconds unless some other
 	    event is received before that time.  Note that a retried
 	    event counts just like a new in this respect.
-	    If <c>Time =:= infinity</c> or <c>Time =:= 0</c>
-	    no timer is started but for zero time the timeout
-	    event is immediately enqueued as the newest received.
+	    If <c>Time =:= infinity</c> no timer is started.
+	    If <c>Time =:= 0</c> the timeout event
+	    is immediately enqueued as the newest received.
 	    Also note that it is not possible nor needed
 	    to cancel this timeout using the
 	    <seealso marker="#type-state_operation">
@@ -480,58 +478,45 @@ erlang:'!'            -----> Module:StateName/5
 	 and for <c>reply_operation()</c> that the order may matter.
 	</p>
 	<taglist>
-	  <tag>
-	    <c>
-	      {next_event,<anno>EventType</anno>,<anno>EventContent</anno>}
-	    </c>
-	  </tag>
-	  <item>Insert the given event as the next to process.
+	  <tag><c>next_event</c></tag>
+	  <item>Insert the given <c><anno>EventType</anno></c>
+	    and <c><anno>EventContent</anno></c> the next to process.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
 	    </seealso> should be used when you want to reliably distinguish
 	    an event inserted this way from any external event.
 	  </item>
-	  <tag>
-	    <c>
-	      {remove_event,<anno>EventType</anno>,<anno>EventContent</anno>}
-	    </c>
-	  </tag>
+	  <tag><c>remove_event</c></tag>
 	  <item>Remove the oldest queued event
-	    that matches equal to the given event.
-	  </item>
-	  <tag>
-	    <c>
-	      {remove_event,<anno>EventPredicate</anno>}
-	    </c>
-	  </tag>
-	  <item>Remove the oldest queued event for which
-	  the <c><anno>EventPredicate</anno></c> returns <c>true</c>.
+	    that matches equal to <c><anno>EventType</anno></c>
+	    and <c><anno>EventContent</anno></c> or for which
+	    <c><anno>EventPredicate</anno></c> returns <c>true</c>.
 	  </item>
-	  <tag><c>{cancel_timer,<anno>TimerRef</anno>}</c></tag>
-	  <item>Uses <c><anno>TimerRef</anno></c> when calling
+	  <tag><c>cancel_timer</c></tag>
+	  <item>Cancel the timer by calling
 	    <seealso marker="erts:erlang#cancel_timer/2">
 	      <c>erlang:cancel_timer/2</c>
-	    </seealso> to cancel a timer, cleans the gen_statem's
-	    message queue from any late timeout message from
-	    the timer, and removes any late timeout message
-	    from the queued events using
+	    </seealso> with <c><anno>TimerRef</anno></c>,
+	    clean the process message queue from any late timeout message,
+	    and removes any late timeout message
+	    from the gen_statem event queue using
 	    <c>{remove_event,<anno>EventPredicate</anno>}</c> above.
 	    This is a convenience function that saves quite some
 	    lines of code and testing time over doing it from
 	    the primitives mentioned above.
 	  </item>
-	  <tag><c>{demonitor,<anno>MonitorRef</anno>}</c></tag>
-	  <item>Like <c>{cancel_timer,_}</c> above but for
+	  <tag><c>demonitor</c></tag>
+	  <item>Like <c>cancel_timer</c> above but for
 	    <seealso marker="erts:erlang#demonitor/2">
 	      <c>demonitor/2</c>
-	    </seealso>.
+	    </seealso> with <c><anno>MonitorRef</anno></c>.
 	  </item>
 	  <tag><c>{unlink,<anno>Id</anno>}</c></tag>
 	  <item>Like <c>{cancel_timer,_}</c> above but for
 	    <seealso marker="erts:erlang#unlink/1">
 	      <c>unlink/1</c>
-	    </seealso>.
+	    </seealso> with <c><anno>Id</anno></c>.
 	  </item>
 	</taglist>
       </desc>
@@ -539,109 +524,45 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="reply_operation" />
       <desc>
-	<taglist>
-	  <tag>
-	   <c>{reply,<anno>Client</anno>,<anno>Reply</anno>}</c>
-	  </tag>
-	  <item>Reply to a client that called
-	    <seealso marker="#call/2"><c>call/2</c></seealso>.
-            <c><anno>Client</anno></c> must be the term from the
-	    <seealso marker="#type-event_type">
-	      <c>{call,<anno>Client</anno>}</c>
-	    </seealso> argument to the
-	    <seealso marker="#state_function">state function</seealso>.
-	  </item>
-	</taglist>
+	<p>Reply to a client that called
+	  <seealso marker="#call/2"><c>call/2</c></seealso>.
+          <c><anno>Client</anno></c> must be the term from the
+	  <seealso marker="#type-event_type">
+	    <c>{call,<anno>Client</anno>}</c>
+	  </seealso> argument to the
+	  <seealso marker="#state_function">state function</seealso>.
+	</p>
       </desc>
     </datatype>
     <datatype>
       <name name="state_callback_result" />
       <desc>
 	<taglist>
-	  <tag>
-	   <c>{stop,<anno>Reason</anno>}</c>
-	  </tag>
-	  <item>The same as
-	    <c>{stop,<anno>Reason</anno>,[],StateData}</c>
-	    but keeps the old <c>StateData</c>.
-	  </item>
-	  <tag>
-	   <c>{stop,<anno>Reason</anno>,<anno>NewStateData</anno>}</c>
-	  </tag>
-	  <item>The same as
-	    <c>{stop,<anno>Reason</anno>,[],<anno>NewStateData</anno>}</c>
-	  </item>
-	  <tag><c>{stop,
-	    <anno>Reason</anno>,
-	    <anno>Replies</anno>,
-	    <anno>NewStateData</anno>}</c>
-	  </tag>
-	  <item>The gen_statem will first send all
-	    <c><anno>Replies</anno></c> and then terminate by calling
+	  <tag><c>stop</c></tag>
+	  <item>Send all <c><anno>Replies</anno></c> if given,
+	    then terminate the gen_statem by calling
 	    <seealso marker="#Module:terminate/3">
 	      <c>Module:terminate/3</c>
-	    </seealso> with <c>Reason</c>.
+	    </seealso> with <c>Reason</c> and
+	    <c><anno>NewStateData</anno></c>, if given.
 	  </item>
-	  <tag>
-	    <c>
-	      {next_state,<anno>NewState</anno>,<anno>NewStateData</anno>}
-	    </c>
-	  </tag>
-	  <item>The same as
-	    <c>
-	      {next_state,<anno>NewState</anno>,<anno>NewStateData</anno>,[]}
-	    </c>
-	  </item>
-	  <tag>
-	    <c>
-	      {next_state,
-	       <anno>NewState</anno>,
-	       <anno>NewStateData</anno>,
-	       <anno>StateOps</anno>}
-	    </c>
-	  </tag>
+	  <tag><c>next_state</c></tag>
 	  <item>The gen_statem will do a state transition to
 	    <c><anno>NewState</anno></c>
-	    (which may be the same as the current state)
+	    (which may be the same as the current state),
+	    set <c><anno>NewStateData</anno></c>
 	    and execute all <c><anno>StateOps</anno></c>
 	  </item>
-	  <tag>
-	    <c>
-	      {keep_state,<anno>NewStateData</anno>}}
-	    </c>
-	  </tag>
-	  <item>The same as
-	    <c>
-	      {keep_state,<anno>NewStateData</anno>,[]}
-	    </c>
-	  </item>
-	  <tag>
-	    <c>
-	      {keep_state,<anno>NewStateData</anno>,<anno>StateOps</anno>}
-	    </c>
-	  </tag>
+	  <tag><c>keep_state</c></tag>
 	  <item>The gen_statem will keep the current state, or
 	    do a state transition to the current state if you like,
+	    set <c><anno>NewStateData</anno></c>
 	    and execute all <c><anno>StateOps</anno></c>
 	  </item>
-	  <tag>
-	    <c>
-	      {keep_state_and_data}
-	    </c>
-	  </tag>
-	  <item>The same as
-	    <c>
-	      {keep_state_and_data,[]}
-	    </c>
-	  </item>
-	  <tag>
-	    <c>
-	      {keep_state_and_data,<anno>StateOps</anno>}
-	    </c>
-	  </tag>
+	  <tag><c>keep_state_and_data</c></tag>
 	  <item>The gen_statem will keep the current state, or
 	    do a state transition to the current state if you like,
-	    also keep the current state data,
+	    keep the current state data,
 	    and execute all <c><anno>StateOps</anno></c>
 	  </item>
 	</taglist>
-- 
cgit v1.2.3


From 4d903e7e0f12d40461efda84ee169e8e65cf4c71 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 19 Feb 2016 10:47:01 +0100
Subject: Write gen_statem with code font in the docs

---
 lib/stdlib/doc/src/gen_statem.xml | 253 ++++++++++++++++++++------------------
 1 file changed, 134 insertions(+), 119 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 9cddce98da..c685d24b78 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -40,14 +40,14 @@
       callback function for all states.
     </p>
     <p>
-      A generic state machine process (gen_statem) implemented using
-      this module will have a standard set of interface functions
+      A generic state machine process (<c>gen_statem</c>) implemented
+      using this module will have a standard set of interface functions
       and include functionality for tracing and error reporting.
       It will also fit into an OTP supervision tree. Refer to
       <seealso marker="doc/design_principles:gen_server_concepts">
         OTP Design Principles</seealso> for more information.
     </p>
-    <p>A gen_statem assumes all specific parts to be located in a
+    <p>A <c>gen_statem</c> assumes all specific parts to be located in a
       callback module exporting a pre-defined set of functions.
       The relationship between the behaviour functions and the callback
       functions can be illustrated as follows:</p>
@@ -74,17 +74,17 @@ erlang:'!'            -----> Module:StateName/5
       and how to respond.
     </p>
     <p>If a callback function fails or returns a bad value,
-      the gen_statem will terminate.  An exception of class
+      the <c>gen_statem</c> will terminate.  An exception of class
       <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
       however, is not regarded as an error but as a valid return.
     </p>
     <marker id="state_function" />
     <p>The "<em>state function</em>" for a specific
       <seealso marker="#type-state">state</seealso>
-      in a gen_statem is the callback function that is called
+      in a <c>gen_statem</c> is the callback function that is called
       for all events in this state, and is selected depending on
       <seealso marker="#type-callback_mode">callback_mode</seealso>
-      that the implementation selects during gen_statem init.
+      that the implementation selects during <c>gen_statem</c> init.
     </p>
     <p>When
       <seealso marker="#type-callback_mode">callback_mode</seealso>
@@ -114,11 +114,11 @@ erlang:'!'            -----> Module:StateName/5
       <seealso marker="#type-callback_mode">callback_mode</seealso>)
       is permitted with a small gotcha regarding the state
       <c>undefined</c> that is used as the previous state when
-      the first gen_statem state function is called.
+      the first <c>gen_statem</c> state function is called.
       You might need to know about this faked state if you
       inspect the previous state argument in your state functions.
     </p>
-    <p>The gen_statem enqueues incoming events in order of arrival
+    <p>The <c>gen_statem</c> enqueues incoming events in order of arrival
       and presents these to the
       <seealso marker="#state_function">state function</seealso>
       in that order.  The state function can postpone an event
@@ -126,8 +126,8 @@ erlang:'!'            -----> Module:StateName/5
       After a state change all enqueued events (including postponed)
       are again presented to the state function.
     </p>
-    <p>The gen_statem event queue model is sufficient to emulate
-      the normal process message queue and selective receive
+    <p>The <c>gen_statem</c> event queue model is sufficient
+      to emulate the normal process message queue and selective receive
       with postponing an event corresponding to not matching
       it in a receive statement and changing states corresponding
       to entering a new receive statement.
@@ -151,23 +151,25 @@ erlang:'!'            -----> Module:StateName/5
       state handling functions that you often would have to
       resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
       to force processing a faked event before others.
-      If you for example in gen_statem postpone an event
+      If you for example in <c>gen_statem</c> postpone an event
       in one state and then call some other state function of yours,
       you have not changed states and hence the postponed event
       will not be retried, which is logical but might be confusing.
     </p>
-    <p>A gen_statem handles system messages as documented in
+    <p>A <c>gen_statem</c> handles system messages as documented in
        <seealso marker="sys">sys</seealso>.
        The <seealso marker="sys">sys</seealso> module
-       can be used for debugging a gen_statem.
+       can be used for debugging a <c>gen_statem</c>.
     </p>
-    <p>Note that a gen_statem does not trap exit signals automatically,
-      this must be explicitly initiated by the callback module.
+    <p>Note that a <c>gen_statem</c> does not trap exit signals
+      automatically, this must be explicitly initiated by
+      the callback module.
     </p>
     <p>Unless otherwise stated, all functions in this module fail if
-      the specified gen_statem does not exist or if bad arguments are given.
+      the specified <c>gen_statem</c> does not exist or
+      if bad arguments are given.
     </p>
-    <p>The gen_statem process can go into hibernation (see
+    <p>The <c>gen_statem</c> process can go into hibernation (see
       <seealso marker="erts:erlang#hibernate/3">
 	<c>erlang:hibernate/3</c>
       </seealso>) if a
@@ -187,7 +189,8 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="server_name" />
       <desc>
-	<p>Name specification to use when starting a gen_statem server.
+	<p>Name specification to use when starting
+	  a<c>gen_statem</c> server.
 	  See <seealso marker="#start_link/3">
 	    <c>start_link/3</c>
 	  </seealso> and
@@ -200,7 +203,8 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="server_ref" />
       <desc>
-	<p>Server specification to use when addressing a gen_statem server.
+	<p>Server specification to use when addressing
+	  a <c>gen_statem</c> server.
 	  See <seealso marker="#call/2">call/2</seealso> and
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
@@ -210,16 +214,17 @@ erlang:'!'            -----> Module:StateName/5
 	<taglist>
 	  <tag><c>pid()</c></tag>
 	  <tag><c>LocalName</c></tag>
-	  <item>The gen_statem is locally registered.</item>
+	  <item>The <c>gen_statem</c> is locally registered.</item>
 	  <tag><c>Name, Node</c></tag>
-	  <item>The gen_statem is locally registered on another node.
+	  <item>The <c>gen_statem</c> is locally registered
+	    on another node.
 	  </item>
 	  <tag><c>GlobalName</c></tag>
-	  <item>The gen_statem is globally registered
+	  <item>The <c>gen_statem</c> is globally registered
 	    in <seealso marker="kernel:global"><c>global</c></seealso>.
 	  </item>
 	  <tag><c>RegMod, ViaName</c></tag>
-	  <item>The gen_statem is registered through
+	  <item>The <c>gen_statem</c> is registered through
 	    an alternative process registry.
 	    The registry callback module <c>RegMod</c>
 	    should export the functions
@@ -237,7 +242,7 @@ erlang:'!'            -----> Module:StateName/5
       <name name="debug_opt" />
       <desc>
 	<p>Debug option that can be used when starting
-	  a gen_statem server through for example
+	  a <c>gen_statem</c> server through for example
 	  <seealso marker="#enter_loop/4">enter_loop/4</seealso>.
 	</p>
 	<p>For every entry in <c><anno>Dbgs</anno></c>
@@ -250,7 +255,7 @@ erlang:'!'            -----> Module:StateName/5
       <name name="start_opt" />
       <desc>
 	<p>Options that can be used when starting
-	  a gen_statem server through for example
+	  a <c>gen_statem</c> server through for example
 	  <seealso marker="#start_link/3">start_link/3</seealso>.
 	</p>
       </desc>
@@ -271,7 +276,7 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#type-state_op">
 	    state_op() {reply,Client,Reply}
 	  </seealso>
-	  to a client that has called the gen_statem server using
+	  to a client that has called the <c>gen_statem</c> server using
 	  <seealso marker="#call/2">call/2</seealso>.
 	</p>
       </desc>
@@ -316,7 +321,7 @@ erlang:'!'            -----> Module:StateName/5
 	  originate from the corresponding API functions.
 	  For calls the event contain whom to reply to.
 	  Type <c>info</c> originates from normal messages sent
-	  to the gen_statem process.
+	  to the <c>gen_statem</c> process.
 	  It is also possible for the state machine
 	  implementation to insert events to itself,
 	  in particular of types
@@ -343,8 +348,8 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="init_option" />
       <desc>
-	<p>Option that only is valid when initializing the gen_statem
-	  that is it can be returned from
+	<p>Option that only is valid when initializing
+	  the <c>gen_statem</c> that is it can be returned from
 	  <seealso marker="#Module:init/1">Module:init/1</seealso>
 	  or given to
 	  <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
@@ -408,12 +413,12 @@ erlang:'!'            -----> Module:StateName/5
 	  <item>The (possibly new)
 	    <seealso marker="#state_function">state function</seealso>
 	    is called with the oldest enqueued event if there is any,
-	    otherwise the gen_statem goes into <c>receive</c>
+	    otherwise the <c>gen_statem</c> goes into <c>receive</c>
 	    or hibernation (if the option <c>hibernate</c> is <c>true</c>)
 	    to wait for the next message.  In hibernation the next
-	    non-system event awakens the gen_statem, or rather
-	    the next incoming message awakens the gen_statem but if it
-	    is a system event it goes back into hibernation.
+	    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 back into hibernation.
 	  </item>
 	</list>
       </desc>
@@ -438,13 +443,14 @@ erlang:'!'            -----> Module:StateName/5
 	  </item>
 	  <tag><c>hibernate</c></tag>
 	  <item>If <c><anno>Hibernate</anno> =:= true</c>
-	    or plain <c>hibernate</c> hibernate the gen_statem by calling
+	    or plain <c>hibernate</c> hibernate the <c>gen_statem</c>
+	    by calling
 	    <seealso marker="proc_lib#hibernate/3">
 	      <c>proc_lib:hibernate/3</c>
 	    </seealso> before <c>receive</c> to wait for a new event.
 	    If there are enqueued events the <c>hibernate</c> operation
 	    is ignored as if an event just arrived and awakened
-	    the gen_statem.
+	    the <c>gen_statem</c>.
 	  </item>
 	  <tag><c>timeout</c>
 	  </tag>
@@ -500,7 +506,7 @@ erlang:'!'            -----> Module:StateName/5
 	    </seealso> with <c><anno>TimerRef</anno></c>,
 	    clean the process message queue from any late timeout message,
 	    and removes any late timeout message
-	    from the gen_statem event queue using
+	    from the <c>gen_statem</c> event queue using
 	    <c>{remove_event,<anno>EventPredicate</anno>}</c> above.
 	    This is a convenience function that saves quite some
 	    lines of code and testing time over doing it from
@@ -540,27 +546,27 @@ erlang:'!'            -----> Module:StateName/5
 	<taglist>
 	  <tag><c>stop</c></tag>
 	  <item>Send all <c><anno>Replies</anno></c> if given,
-	    then terminate the gen_statem by calling
+	    then terminate the <c>gen_statem</c> by calling
 	    <seealso marker="#Module:terminate/3">
 	      <c>Module:terminate/3</c>
 	    </seealso> with <c>Reason</c> and
 	    <c><anno>NewStateData</anno></c>, if given.
 	  </item>
 	  <tag><c>next_state</c></tag>
-	  <item>The gen_statem will do a state transition to
+	  <item>The <c>gen_statem</c> will do a state transition to
 	    <c><anno>NewState</anno></c>
 	    (which may be the same as the current state),
 	    set <c><anno>NewStateData</anno></c>
 	    and execute all <c><anno>StateOps</anno></c>
 	  </item>
 	  <tag><c>keep_state</c></tag>
-	  <item>The gen_statem will keep the current state, or
+	  <item>The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    set <c><anno>NewStateData</anno></c>
 	    and execute all <c><anno>StateOps</anno></c>
 	  </item>
 	  <tag><c>keep_state_and_data</c></tag>
-	  <item>The gen_statem will keep the current state, or
+	  <item>The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    keep the current state data,
 	    and execute all <c><anno>StateOps</anno></c>
@@ -575,17 +581,18 @@ erlang:'!'            -----> Module:StateName/5
     <func>
       <name name="start_link" arity="3" />
       <name name="start_link" arity="4" />
-      <fsummary>Create a linked gen_statem process</fsummary>
+      <fsummary>Create a linked <c>gen_statem</c> process</fsummary>
       <desc>
-        <p>Creates a gen_statem process according to OTP design principles
+        <p>Creates a <c>gen_statem</c> process according
+	  to OTP design principles
 	  (using
           <seealso marker="proc_lib"><c>proc_lib</c></seealso>
 	  primitives)
 	  that is linked to the calling process.
-	  This is essential when the gen_statem shall be part of
+	  This is essential when the <c>gen_statem</c> shall be part of
 	  a supervision tree so it gets linked to its supervisor.
 	</p>
-        <p>The gen_statem process calls
+        <p>The <c>gen_statem</c> process calls
 	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
 	  to initialize the server. To ensure a synchronized start-up
 	  procedure, <c>start_link/3,4</c> does not return until
@@ -595,10 +602,10 @@ erlang:'!'            -----> Module:StateName/5
 	<p><c><anno>ServerName</anno></c> specifies the
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
-	  </seealso> to register for the gen_statem.
-	  If the gen_statem is started with  <c>start_link/3</c>
+	  </seealso> 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 gen_statem is not registered.
+	  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 which is passed as
@@ -607,9 +614,9 @@ erlang:'!'            -----> Module:StateName/5
 	  </seealso>.
 	</p>
         <p>If the option <c>{timeout,Time}</c> is present in
-	  <c><anno>Options</anno></c>, the gen_statem is allowed to spend
-	  <c>Time</c> milliseconds initializing or it will be
-	  terminated and the start function will return
+	  <c><anno>Options</anno></c>, the <c>gen_statem</c>
+	  is allowed to spend <c>Time</c> milliseconds initializing
+	  or it will be terminated and the start function will return
 	  <seealso marker="#type-start_ret">
 	    <c>{error,timeout}</c>
 	  </seealso>.
@@ -624,18 +631,19 @@ erlang:'!'            -----> Module:StateName/5
 	  as option list to the <c>spawn_opt</c> BIF
 	  which is used to
           <seealso marker="erts:erlang#spawn_opt/2">spawn</seealso>
-	  the gen_statem.
+	  the <c>gen_statem</c>.
 	</p>
         <note>
           <p>Using the spawn option <c>monitor</c> is currently not
             allowed, but will cause this function to fail with reason
             <c>badarg</c>.</p>
         </note>
-        <p>If the gen_statem is successfully created and initialized
-          this function returns
+        <p>If the <c>gen_statem</c> is successfully created
+	  and initialized this function returns
 	  <seealso marker="#type-start_ret">
 	    <c>{ok,Pid}</c>,
-	  </seealso> where <c>Pid</c> is the <c>pid()</c> of the gen_statem.
+	  </seealso> where <c>Pid</c> is the <c>pid()</c>
+	  of the <c>gen_statem</c>.
 	  If there already exists a process with the specified
 	  <c><anno>ServerName</anno></c> this function returns
 	  <seealso marker="#type-start_ret">
@@ -669,9 +677,9 @@ erlang:'!'            -----> Module:StateName/5
     <func>
       <name name="start" arity="3" />
       <name name="start" arity="4" />
-      <fsummary>Create a stand-alone gen_statem process</fsummary>
+      <fsummary>Create a stand-alone <c>gen_statem</c> process</fsummary>
       <desc>
-        <p>Creates a stand-alone gen_statem process according to
+        <p>Creates a stand-alone <c>gen_statem</c> process according to
 	  OTP design principles (using
           <seealso marker="proc_lib"><c>proc_lib</c></seealso>
 	  primitives).
@@ -700,12 +708,12 @@ erlang:'!'            -----> Module:StateName/5
       <name name="stop" arity="3" />
       <fsummary>Synchronously stop a generic server</fsummary>
       <desc>
-	<p>Orders the gen_statem
+	<p>Orders the <c>gen_statem</c>
 	  <seealso marker="#type-server_ref">
 	    <c><anno>ServerRef</anno></c>
 	  </seealso> to exit with the given <c><anno>Reason</anno></c>
 	  and waits for it to terminate.
-	  The gen_statem will call
+	  The <c>gen_statem</c> will call
           <seealso marker="#Module:terminate/3">
 	    Module:terminate/3
 	  </seealso> before exiting.
@@ -735,14 +743,14 @@ erlang:'!'            -----> Module:StateName/5
     <func>
       <name name="call" arity="2" />
       <name name="call" arity="3" />
-      <fsummary>Make a synchronous call to a gen_statem</fsummary>
+      <fsummary>Make a synchronous call to a <c>gen_statem</c></fsummary>
       <desc>
-        <p>Makes a synchronous call to the gen_statem
+        <p>Makes a synchronous call to the <c>gen_statem</c>
 	  <seealso marker="#type-server_ref">
 	    <c><anno>ServerRef</anno></c>
 	  </seealso> by sending a request
 	  and waiting until its reply arrives.
-	  The gen_statem will call the
+	  The <c>gen_statem</c> will call the
 	  <seealso marker="#state_function">state function</seealso> with
 	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
 	  <c>{call,Client}</c> and event content
@@ -771,7 +779,7 @@ erlang:'!'            -----> Module:StateName/5
 	    </p>
 	  </note>
 	</p>
-        <p>The call may fail for example if the gen_statem dies
+        <p>The call may fail for example if the <c>gen_statem</c> dies
 	  before or during this function call.
 	</p>
       </desc>
@@ -779,14 +787,15 @@ erlang:'!'            -----> Module:StateName/5
 
     <func>
       <name name="cast" arity="2" />
-      <fsummary>Send an asynchronous event to a gen_statem</fsummary>
+      <fsummary>Send an asynchronous event to a <c>gen_statem</c></fsummary>
       <desc>
-	<p>Sends an asynchronous event to the gen_statem
+	<p>Sends an asynchronous event to the <c>gen_statem</c>
 	  <seealso marker="#type-server_ref">
 	    <c><anno>ServerRef</anno></c>
 	  </seealso> and returns <c>ok</c> immediately,
-	  ignoring if the destination node or gen_statem does not exist.
-	  The gen_statem will call the
+	  ignoring if the destination node or <c>gen_statem</c>
+	  does not exist.
+	  The <c>gen_statem</c> will call the
 	  <seealso marker="#state_function">state function</seealso> with
 	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
 	  <c>cast</c> and event content
@@ -800,8 +809,8 @@ erlang:'!'            -----> Module:StateName/5
       <name name="reply" arity="2" />
       <fsummary>Send a reply to a client</fsummary>
       <desc>
-        <p>This function can be used by a gen_statem to explicitly send
-          a reply to a client that called
+        <p>This function can be used by a <c>gen_statem</c>
+	  to explicitly send a reply to a client that called
 	  <seealso marker="#call/2"><c>call/2</c></seealso>
           when the reply cannot be defined in
           the return value of the
@@ -828,7 +837,7 @@ erlang:'!'            -----> Module:StateName/5
 
     <func>
       <name name="enter_loop" arity="4" />
-      <fsummary>Enter the gen_statem receive loop</fsummary>
+      <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
 	<p>The same as
 	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
@@ -841,7 +850,7 @@ erlang:'!'            -----> Module:StateName/5
     </func>
     <func>
       <name name="enter_loop" arity="5" />
-      <fsummary>Enter the gen_statem receive loop</fsummary>
+      <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
 	<p>If <c><anno>Server_or_StateOps</anno></c> is a <c>list()</c>
 	  the same as
@@ -862,25 +871,27 @@ erlang:'!'            -----> Module:StateName/5
     </func>
     <func>
       <name name="enter_loop" arity="6" />
-      <fsummary>Enter the gen_statem receive loop</fsummary>
+      <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
-        <p>Makes an the calling process become a gen_statem. Does not return,
-          instead the calling process will enter the gen_statem receive
-          loop and become a gen_statem server. The process
-          <em>must</em> have been started using one of the start
-          functions in
+        <p>Makes an the calling process become a <c>gen_statem</c>.
+	  Does not return, instead the calling process will enter
+	  the <c>gen_statem</c> receive loop and become
+	  a <c>gen_statem</c> server.
+	  The process <em>must</em> have been started
+	  using one of the start functions in
           <seealso marker="proc_lib"><c>proc_lib</c></seealso>.
 	  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 gen_statem behaviour provides.
+          procedure is needed than
+	  the <c>gen_statem</c> behaviour provides.
 	</p>
         <p><c><anno>Module</anno></c>, <c><anno>Options</anno></c> and
 	  <c><anno>Server</anno></c> have the same meanings
 	  as when calling
           <seealso marker="#start_link/3">
-	    gen_statem:start[_link]/3,4
+	    <c>gen_statem</c>:start[_link]/3,4
 	  </seealso>.
           However, the
 	  <seealso marker="#type-server_name">
@@ -912,7 +923,7 @@ erlang:'!'            -----> Module:StateName/5
   <section>
     <title>CALLBACK FUNCTIONS</title>
     <p>The following functions should be exported from a
-      <c>gen_statem</c> callback module.
+      <c><c>gen_statem</c></c> callback module.
     </p>
   </section>
   <funcs>
@@ -937,10 +948,10 @@ erlang:'!'            -----> Module:StateName/5
       </type>
       <desc>
 	<marker id="Module:init-1" />
-        <p>Whenever a gen_statem is started using
-          <seealso marker="#start_link/3">gen_statem:start_link/3,4</seealso>
+        <p>Whenever a <c>gen_statem</c> is started using
+          <seealso marker="#start_link/3">start_link/3,4</seealso>
 	  or
-          <seealso marker="#start/3">gen_statem:start/3,4</seealso>,
+          <seealso marker="#start/3">start/3,4</seealso>,
           this function is called by the new process to initialize
 	  the implementation loop data.
 	</p>
@@ -950,7 +961,7 @@ erlang:'!'            -----> Module:StateName/5
           return <c>{ok,State,StateData}</c> or
 	  <c>{ok,State,StateData,StateOps}</c>.
 	  <c>State</c> is the <seealso marker="#type-state">state</seealso>
-	  of the gen_statem.
+	  of the <c>gen_statem</c>.
 	</p>
 	<p>The <seealso marker="#type-state_op"><c>StateOps</c></seealso>
 	  are executed when entering the first
@@ -958,14 +969,14 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
 	<p>This function allows an option to select the callback mode
-	  of the gen_statem.  See
+	  of the <c>gen_statem</c>.  See
 	  <seealso marker="#type-init_option">init_option</seealso>.
 	  This option is not allowed from the state function(s).
 	</p>
         <p>If something goes wrong during the initialization
           the function should return <c>{stop,Reason}</c>
 	  or <c>ignore</c>. See
-          <seealso marker="#start_link/3">gen_statem:start_link/3,4</seealso>.
+          <seealso marker="#start_link/3">start_link/3,4</seealso>.
 	</p>
       </desc>
     </func>
@@ -1002,9 +1013,9 @@ erlang:'!'            -----> Module:StateName/5
 	</v>
       </type>
       <desc>
-        <p>Whenever a gen_statem receives an event from
-          <seealso marker="#call/2">gen_statem:call/2</seealso>,
-          <seealso marker="#cast/2">gen_statem:cast/2</seealso> or
+        <p>Whenever a <c>gen_statem</c> receives an event from
+          <seealso marker="#call/2">call/2</seealso>,
+          <seealso marker="#cast/2">cast/2</seealso> or
 	  as a normal process message this function is called.
 	  If
 	  <seealso marker="#type-callback_mode">callback_mode</seealso>
@@ -1022,7 +1033,7 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#type-reply_operation">Replies</seealso>
 	  or by calling
 	  <seealso marker="#reply/2">
-	    <c>gen_statem:reply(Client, Reply)</c>
+	    <c>reply(Client, Reply)</c>
 	  </seealso>.
 	</p>
         <p><c>StateName</c> is useful in some odd cases for example
@@ -1032,7 +1043,7 @@ erlang:'!'            -----> Module:StateName/5
 	<p><c>PrevStateName</c> and <c>PrevState</c> are useful
 	  in some odd cases for example when you want to do something
 	  only at the first event in a state.
-	  Note that when gen_statem enters its first state
+	  Note that when <c>gen_statem</c> enters its first state
 	  this is set to <c>undefined</c>.
 	</p>
 	<p>If this function returns with a new state that
@@ -1041,7 +1052,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>See <seealso marker="#type-state_op">state_op()</seealso>
 	  for options that can be set and operations that can be done
-	  by gen_statem after returning from this function.
+	  by <c>gen_statem</c> after returning from this function.
 	</p>
       </desc>
     </func>
@@ -1060,45 +1071,49 @@ erlang:'!'            -----> Module:StateName/5
 	<v>Ignored = term()</v>
       </type>
       <desc>
-        <p>This function is called by a gen_statem when it is about to
-          terminate. It should be the opposite of
+        <p>This function is called by a <c>gen_statem</c>
+	  when it is about to terminate. It should be the opposite of
 	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
           and do any necessary cleaning up. When it returns,
-          the gen_statem terminates with <c>Reason</c>. The return
+          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
           <seealso marker="#type-state">State</seealso>
-	  is the internal state of the gen_statem.
+	  is the internal state of the <c>gen_statem</c>.
 	</p>
-        <p><c>Reason</c> depends on why the gen_statem is terminating.
+        <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
 	  <seealso marker="#type-state_op">StateOps</seealso>,
 	  <c>Reason</c> will have the value specified in that tuple.
 	  If it is due to a failure, <c>Reason</c> is the error reason.
 	</p>
-        <p>If the gen_statem is part of a supervision tree and is
+        <p>If the <c>gen_statem</c> is part of a supervision tree and is
           ordered by its supervisor to terminate, this function will be
           called with <c>Reason = shutdown</c> if the following
           conditions apply:</p>
         <list type="bulleted">
-          <item>the gen_statem has been set to trap exit signals, and</item>
+          <item>the <c>gen_statem</c> has been set
+	    to trap exit signals, and
+	  </item>
           <item>the shutdown strategy as defined in the supervisor's
             child specification is an integer timeout value, not
             <c>brutal_kill</c>.
 	  </item>
         </list>
-        <p>Even if the gen_statem is <em>not</em> part of a supervision tree,
-	   this function will be called if it receives an <c>'EXIT'</c>
-	   message from its parent. <c>Reason</c> will be the same as in
-	   the <c>'EXIT'</c> message.
+        <p>Even if the <c>gen_statem</c> is <em>not</em>
+	  part of a supervision tree, this function will be called
+	  if it receives an <c>'EXIT'</c> message from its parent.
+	  <c>Reason</c> will be the same as
+	  in the <c>'EXIT'</c> message.
 	</p>
-        <p>Otherwise, the gen_statem will be immediately terminated.
+        <p>Otherwise, the <c>gen_statem</c> will be immediately terminated.
 	</p>
         <p>Note that for any other reason than <c>normal</c>,
-          <c>shutdown</c>, or <c>{shutdown,Term}</c> the gen_statem is
-	  assumed to terminate due to an error and
-	  an error report is issued using
+          <c>shutdown</c>, or <c>{shutdown,Term}</c>
+	  the <c>gen_statem</c> is assumed to terminate due to an error
+	  and an error report is issued using
           <seealso marker="kernel:error_logger#format/2">
 	    error_logger:format/2
 	  </seealso>.
@@ -1126,7 +1141,7 @@ erlang:'!'            -----> Module:StateName/5
 	<v>Reason = term()</v>
       </type>
       <desc>
-        <p>This function is called by a gen_statem when it should
+        <p>This function is called by a <c>gen_statem</c> when it should
           update its internal state during a release upgrade/downgrade,
           i.e. when the instruction <c>{update,Module,Change,...}</c>
           where <c>Change={advanced,Extra}</c> is given in
@@ -1144,7 +1159,7 @@ erlang:'!'            -----> Module:StateName/5
           is the checksum of the BEAM file.
 	</p>
         <p><c>OldState</c> and <c>OldStateData</c> is the internal state
-	  of the gen_statem.
+	  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.
@@ -1163,7 +1178,7 @@ erlang:'!'            -----> Module:StateName/5
         Status
       </name>
       <fsummary>Optional function for providing a term describing the
-        current gen_statem status</fsummary>
+        current <c>gen_statem</c> status</fsummary>
       <type>
         <v>Opt = normal | terminate</v>
         <v>PDict = [{Key, Value}]</v>
@@ -1180,43 +1195,43 @@ erlang:'!'            -----> Module:StateName/5
       <desc>
         <note>
           <p>This callback is optional, so callback modules need not
-            export it. The gen_statem module provides a default
+            export it. The <c>gen_statem</c> module provides a default
             implementation of this function that returns the callback
             module state.
 	  </p>
         </note>
-        <p>This function is called by a gen_statem process when:</p>
+        <p>This function is called by a <c>gen_statem</c> process when:</p>
         <list type="bulleted">
           <item>One of
             <seealso marker="sys#get_status/1">
 	      <c>sys:get_status/1,2</c>
 	    </seealso>
-            is invoked to get the gen_statem status. <c>Opt</c> is set
+            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 gen_statem terminates abnormally and logs an error.
+          <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 customising the form and
-          appearance of the gen_statem status for these cases. A
+          appearance of the <c>gen_statem</c> status for these cases. A
           callback module wishing to customise the
           <seealso marker="sys#get_status/1">
 	    <c>sys:get_status/1,2</c>
 	  </seealso> return value as well as how
           its status appears in termination error logs exports an
           instance of <c>format_status/2</c> that returns a term
-          describing the current status of the gen_statem.
+          describing the current status of the <c>gen_statem</c>.
 	</p>
-        <p><c>PDict</c> is the current value of the gen_statem's
+        <p><c>PDict</c> is the current value of the <c>gen_statem</c>'s
           process dictionary.
 	</p>
         <p><seealso marker="#type-state"><c>State</c></seealso>
-	  is the internal state of the gen_statem.
+	  is the internal state of the <c>gen_statem</c>.
 	</p>
         <p>The function should return <c>Status</c>, a term that
           customises the details of the current state and status of
-          the gen_statem. There are no restrictions on the
+          the <c>gen_statem</c>. There are no restrictions on the
           form <c>Status</c> can take, but for the
           <seealso marker="sys#get_status/1">
 	    <c>sys:get_status/1,2</c>
@@ -1224,7 +1239,7 @@ erlang:'!'            -----> Module:StateName/5
           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 gen_statem state. Following this recommendation isn't
+          the <c>gen_statem</c> state. Following this recommendation isn't
           required, but doing so will make the callback module status
           consistent with the rest of the
           <seealso marker="sys#get_status/1">
-- 
cgit v1.2.3


From 898e66f07dce8b7b33874255bb3ea1c6f5534d34 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 19 Feb 2016 15:26:33 +0100
Subject: Update terminology to data(), transition_op(), etc

---
 lib/stdlib/doc/src/gen_statem.xml    | 222 +++++++++++---------
 lib/stdlib/src/gen_statem.erl        | 382 ++++++++++++++++++-----------------
 lib/stdlib/test/gen_statem_SUITE.erl |  44 ++--
 3 files changed, 338 insertions(+), 310 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index c685d24b78..15e9584360 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -94,7 +94,7 @@ erlang:'!'            -----> Module:StateName/5
       <seealso marker="#Module:StateName/5">
         <c>Module:StateName/5</c>
       </seealso>.
-      This naturally collects all code for a specific state
+      This gathers all code for a specific state
       in one function and hence dispatches on state first.
     </p>
     <p>When
@@ -135,8 +135,8 @@ erlang:'!'            -----> Module:StateName/5
     <p>The
       <seealso marker="#state_function">state function</seealso>
       can insert events using the
-      <seealso marker="#type-state_operation">
-	<c>state_operation()</c> <c>next_event</c>
+      <seealso marker="#type-transition_action">
+	<c>transition_action()</c> <c>next_event</c>
       </seealso>
       and such an event is inserted as the next to present
       to the state function.  That is: as if it is
@@ -176,8 +176,8 @@ erlang:'!'            -----> Module:StateName/5
       <seealso marker="#state_function">state function</seealso> or
       <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
       specifies <c>'hibernate'</c> in the returned
-      <seealso marker="#type-state_op"><c>StateOps</c></seealso> list.
-      This might be useful if the server is expected to be idle
+      <seealso marker="#type-transition_op"><c>Ops</c></seealso>
+      list. This might be useful if the server is expected to be idle
       for a long time. However use this feature with care
       since hibernation implies at least two garbage collections
       (when hibernating and shortly after waking up) and that is not
@@ -273,8 +273,8 @@ erlang:'!'            -----> Module:StateName/5
       <name name="client" />
       <desc>
 	<p>Client address to use when replying through for example the
-	  <seealso marker="#type-state_op">
-	    state_op() {reply,Client,Reply}
+	  <seealso marker="#type-transition_op">
+	    transition_op() {reply,Client,Reply}
 	  </seealso>
 	  to a client that has called the <c>gen_statem</c> server using
 	  <seealso marker="#call/2">call/2</seealso>.
@@ -296,19 +296,21 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#type-callback_mode">
 	    callback_mode
 	  </seealso> is <c>state_functions</c>, which is the default,
-	  the state has to be of this type i.e an <c>atom()</c>.
+	  the state has to be of this type.
 	</p>
       </desc>
     </datatype>
     <datatype>
-      <name name="state_data" />
+      <name name="data" />
       <desc>
-	<p>A <c>term()</c> in which the state machine implementation
-	  should store any state data it needs.  The difference between
-	  this data and the
-	  <seealso marker="#type-state">state()</seealso>
+	<p>A term in which the state machine implementation
+	  should store any server data it needs.  The difference between
+	  this and the <seealso marker="#type-state">state()</seealso>
 	  itself is that a change in this data does not cause
-	  postponed events to be retried.
+	  postponed events to be retried.  Hence if a change
+	  in this data would change the set of events that
+	  are handled than that data item should be made
+	  a part of the state.
 	</p>
       </desc>
     </datatype>
@@ -334,8 +336,8 @@ erlang:'!'            -----> Module:StateName/5
       <desc>
 	<p>A <c>fun()</c> of arity 2 that takes an event
 	  and returns a boolean.
-	  When used in <c>{remove_event,RemoveEventPredicate}</c>
-	  from <seealso marker="#type-state_op">state_op()</seealso>.
+	  When used in <c>{remove_event,RemoveEventPredicate}</c> from
+	  <seealso marker="#type-transition_op">transition_op()</seealso>.
 	  The event for which the predicate returns <c>true</c> will
 	  be removed.
 	</p>
@@ -378,17 +380,16 @@ erlang:'!'            -----> Module:StateName/5
       </desc>
     </datatype>
     <datatype>
-      <name name="state_op" />
+      <name name="transition_op" />
       <desc>
 	<p>Either a
-	  <seealso marker="#type-state_option">
-	    <c>state_option()</c>
+	  <seealso marker="#type-transition_option">
+	    <c>transition_option()</c>
 	  </seealso> of which the last occurence
 	  in the containing list takes precedence, or a
-	  <seealso marker="#type-state_operation">
-	    <c>state_operation()</c>
-	  </seealso> that are performed in order of
-	  the containing list.
+	  <seealso marker="#type-transition_action">
+	    <c>transition_action()</c>
+	  </seealso> performed in the order of the containing list.
 	</p>
 	<p>These may be returned from the
 	  <seealso marker="#state_function">state function</seealso>,
@@ -404,7 +405,7 @@ erlang:'!'            -----> Module:StateName/5
 	  <item>If the state changes the queue of incoming events
 	    is reset to start with the oldest postponed.
 	  </item>
-	  <item>All operations are processed in order of appearance.
+	  <item>All actions are processed in order of appearance.
 	  </item>
 	  <item>The <c>timeout</c> option is processed if present,
 	    so a state timer may be started or a timeout zero event
@@ -424,9 +425,9 @@ erlang:'!'            -----> Module:StateName/5
       </desc>
     </datatype>
     <datatype>
-      <name name="state_option" />
+      <name name="transition_option" />
       <desc>
-	<p>If multiple state options of the same type are present
+	<p>If multiple state options of the same kind are present
 	  in the containing list these are set in the list order
 	  and the last value is kept.
 	</p>
@@ -448,7 +449,7 @@ erlang:'!'            -----> Module:StateName/5
 	    <seealso marker="proc_lib#hibernate/3">
 	      <c>proc_lib:hibernate/3</c>
 	    </seealso> before <c>receive</c> to wait for a new event.
-	    If there are enqueued events the <c>hibernate</c> operation
+	    If there are enqueued events the <c>hibernate</c> action
 	    is ignored as if an event just arrived and awakened
 	    the <c>gen_statem</c>.
 	  </item>
@@ -464,8 +465,8 @@ erlang:'!'            -----> Module:StateName/5
 	    is immediately enqueued as the newest received.
 	    Also note that it is not possible nor needed
 	    to cancel this timeout using the
-	    <seealso marker="#type-state_operation">
-	      <c>state_operation()</c>
+	    <seealso marker="#type-transition_action">
+	      <c>transition_action()</c>
 	    </seealso> <c>cancel_timer</c>.
 	    This timeout is cancelled automatically by any event.
 	  </item>
@@ -473,17 +474,20 @@ erlang:'!'            -----> Module:StateName/5
       </desc>
     </datatype>
     <datatype>
-      <name name="state_operation" />
+      <name name="transition_action" />
       <desc>
-	<p>The state operations are executed in the containing
-	 list order.  This matters for <c>next_event</c> where
-	 the last one in the list will become the next event to present
-	 to the state functions.  Regarding the other operations
-	 it is only for <c>remove_event</c> with
-	 <c><anno>EventPredicate</anno></c>
-	 and for <c>reply_operation()</c> that the order may matter.
+	<p>The state transition actions are executed
+	  in the containing list order.  This matters
+	  for <c>next_event</c> where the last one in the list
+	  will become the next event to present
+	  to the state functions.  Regarding the other actions
+	  it is only for <c>remove_event</c> with
+	  <c><anno>EventPredicate</anno></c>
+	  and for <c>reply_action()</c> that the order may matter.
 	</p>
 	<taglist>
+	  <tag><c>reply_action()</c></tag>
+	  <item>Reply to a calling client.</item>
 	  <tag><c>next_event</c></tag>
 	  <item>Insert the given <c><anno>EventType</anno></c>
 	    and <c><anno>EventContent</anno></c> the next to process.
@@ -518,7 +522,7 @@ erlang:'!'            -----> Module:StateName/5
 	      <c>demonitor/2</c>
 	    </seealso> with <c><anno>MonitorRef</anno></c>.
 	  </item>
-	  <tag><c>{unlink,<anno>Id</anno>}</c></tag>
+	  <tag><c>unlink</c></tag>
 	  <item>Like <c>{cancel_timer,_}</c> above but for
 	    <seealso marker="erts:erlang#unlink/1">
 	      <c>unlink/1</c>
@@ -528,7 +532,7 @@ erlang:'!'            -----> Module:StateName/5
       </desc>
     </datatype>
     <datatype>
-      <name name="reply_operation" />
+      <name name="reply_action" />
       <desc>
 	<p>Reply to a client that called
 	  <seealso marker="#call/2"><c>call/2</c></seealso>.
@@ -550,26 +554,26 @@ erlang:'!'            -----> Module:StateName/5
 	    <seealso marker="#Module:terminate/3">
 	      <c>Module:terminate/3</c>
 	    </seealso> with <c>Reason</c> and
-	    <c><anno>NewStateData</anno></c>, if given.
+	    <c><anno>NewData</anno></c>, if given.
 	  </item>
 	  <tag><c>next_state</c></tag>
 	  <item>The <c>gen_statem</c> will do a state transition to
 	    <c><anno>NewState</anno></c>
 	    (which may be the same as the current state),
-	    set <c><anno>NewStateData</anno></c>
-	    and execute all <c><anno>StateOps</anno></c>
+	    set <c><anno>NewData</anno></c>
+	    and execute all <c><anno>Ops</anno></c>
 	  </item>
 	  <tag><c>keep_state</c></tag>
 	  <item>The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
-	    set <c><anno>NewStateData</anno></c>
-	    and execute all <c><anno>StateOps</anno></c>
+	    set <c><anno>NewData</anno></c>
+	    and execute all <c><anno>Ops</anno></c>
 	  </item>
 	  <tag><c>keep_state_and_data</c></tag>
 	  <item>The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
-	    keep the current state data,
-	    and execute all <c><anno>StateOps</anno></c>
+	    keep the current server data,
+	    and execute all <c><anno>Ops</anno></c>
 	  </item>
 	</taglist>
       </desc>
@@ -614,7 +618,7 @@ erlang:'!'            -----> Module:StateName/5
 	  </seealso>.
 	</p>
         <p>If the option <c>{timeout,Time}</c> is present in
-	  <c><anno>Options</anno></c>, the <c>gen_statem</c>
+	  <c><anno>Opts</anno></c>, the <c>gen_statem</c>
 	  is allowed to spend <c>Time</c> milliseconds initializing
 	  or it will be terminated and the start function will return
 	  <seealso marker="#type-start_ret">
@@ -623,15 +627,14 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
         <p>If the option
 	  <seealso marker="#type-debug_opt"><c>{debug,Dbgs}</c></seealso>
-	  is present in <c><anno>Options</anno></c>, debugging through
+	  is present in <c><anno>Opts</anno></c>, debugging through
 	  <seealso marker="sys"><c>sys</c></seealso> is activated.
 	</p>
-        <p>If the option <c>{spawn_opt,SOpts}</c> is present in
-	  <c><anno>Options</anno></c>, <c>SOpts</c> will be passed
-	  as option list to the <c>spawn_opt</c> BIF
-	  which is used to
-          <seealso marker="erts:erlang#spawn_opt/2">spawn</seealso>
-	  the <c>gen_statem</c>.
+        <p>If the option <c>{spawn_opt,SpawnOpts}</c> is present in
+	  <c><anno>Opts</anno></c>, <c>SpawnOpts</c> will be passed
+	  as option list to
+          <seealso marker="erts:erlang#spawn_opt/2">spawn_opt/2</seealso>
+	  which is used to spawn the <c>gen_statem</c> process.
 	</p>
         <note>
           <p>Using the spawn option <c>monitor</c> is currently not
@@ -760,7 +763,9 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#state_function">state function</seealso>
 	  returns with
 	  <c>{reply,Client,<anno>Reply</anno>}</c> as one
-	  <seealso marker="#type-state_op"><c>state_op()</c></seealso>,
+	  <seealso marker="#type-transition_op">
+	    <c>transition_op()</c>
+	  </seealso>,
 	  and that <c><anno>Reply</anno></c> becomes the return value
 	  of this function.
 	</p>
@@ -823,8 +828,8 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#state_function">state function</seealso>.
 	  <c><anno>Client</anno></c> and <c><anno>Reply</anno></c>
 	  can also be specified using a
-	  <seealso marker="#type-reply_operation">
-	    <c>reply_operation()</c>
+	  <seealso marker="#type-reply_action">
+	    <c>reply_action()</c>
 	  </seealso> and multiple replies with a list of them.
 	</p>
 	<note>
@@ -852,20 +857,20 @@ erlang:'!'            -----> Module:StateName/5
       <name name="enter_loop" arity="5" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
-	<p>If <c><anno>Server_or_StateOps</anno></c> is a <c>list()</c>
+	<p>If <c><anno>Server_or_Ops</anno></c> is a <c>list()</c>
 	  the same as
 	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
 	  except that no
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
 	  </seealso> must have been registered and
-	  <c>StateOps = <anno>Server_or_StateOps</anno></c>.
+	  <c>Ops = <anno>Server_or_Ops</anno></c>.
 	</p>
 	<p>Otherwise the same as
 	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
 	  with
-	  <c>Server = <anno>Server_or_StateOps</anno></c> and
-	  <c>StateOps = []</c>.
+	  <c>Server = <anno>Server_or_Ops</anno></c> and
+	  <c>Ops = []</c>.
 	</p>
       </desc>
     </func>
@@ -887,7 +892,7 @@ erlang:'!'            -----> Module:StateName/5
           procedure is needed than
 	  the <c>gen_statem</c> behaviour provides.
 	</p>
-        <p><c><anno>Module</anno></c>, <c><anno>Options</anno></c> and
+        <p><c><anno>Module</anno></c>, <c><anno>Opts</anno></c> and
 	  <c><anno>Server</anno></c> have the same meanings
 	  as when calling
           <seealso marker="#start_link/3">
@@ -898,8 +903,8 @@ erlang:'!'            -----> Module:StateName/5
 	    <c>server_name()</c>
 	  </seealso> name must have been registered accordingly
 	  <em>before</em> this function is called.</p>
-        <p><c><anno>State</anno></c>, <c><anno>StateData</anno></c>
-	  and <c><anno>StateOps</anno></c>
+        <p><c><anno>State</anno></c>, <c><anno>Data</anno></c>
+	  and <c><anno>Ops</anno></c>
 	  have the same meanings as in the return value of
           <seealso marker="#Module:init/1">Module:init/1</seealso>.
           Also, the callback module <c><anno>Module</anno></c>
@@ -933,15 +938,14 @@ erlang:'!'            -----> Module:StateName/5
       <fsummary>Initialize process and internal state</fsummary>
       <type>
         <v>Args = term()</v>
-        <v>Result = {ok,State,StateData}</v>
-	<v>&nbsp;| {ok,State,StateData,StateOps}</v>
+        <v>Result = {ok,State,Data}</v>
+	<v>&nbsp;| {ok,State,Data,Ops}</v>
         <v>&nbsp;| {stop,Reason} | ignore</v>
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
-	<v>StateData =
-	  <seealso marker="#type-state_data">state_data()</seealso>
+	<v>Data = <seealso marker="#type-data">data()</seealso>
 	</v>
-	<v>StateOps =
-	  [<seealso marker="#type-state_op">state_op()</seealso>
+	<v>Ops =
+	  [<seealso marker="#type-transition_op">transition_op()</seealso>
 	   | <seealso marker="#type-init_option">init_option()</seealso>]
 	</v>
 	<v>Reason = term()</v>
@@ -953,17 +957,17 @@ erlang:'!'            -----> Module:StateName/5
 	  or
           <seealso marker="#start/3">start/3,4</seealso>,
           this function is called by the new process to initialize
-	  the implementation loop data.
+	  the implementation state and server data.
 	</p>
         <p><c>Args</c> is the <c>Args</c> argument provided to the start
           function.</p>
         <p>If the initialization is successful, the function should
-          return <c>{ok,State,StateData}</c> or
-	  <c>{ok,State,StateData,StateOps}</c>.
+          return <c>{ok,State,Data}</c> or
+	  <c>{ok,State,Data,Ops}</c>.
 	  <c>State</c> is the <seealso marker="#type-state">state</seealso>
 	  of the <c>gen_statem</c>.
 	</p>
-	<p>The <seealso marker="#type-state_op"><c>StateOps</c></seealso>
+	<p>The <seealso marker="#type-transition_op"><c>Ops</c></seealso>
 	  are executed when entering the first
 	  <seealso marker="#type-state">state</seealso> just as for a
 	  <seealso marker="#state_function">state function</seealso>.
@@ -978,15 +982,19 @@ erlang:'!'            -----> Module:StateName/5
 	  or <c>ignore</c>. See
           <seealso marker="#start_link/3">start_link/3,4</seealso>.
 	</p>
+	<p>This function may use
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  to return its value.
+	</p>
       </desc>
     </func>
 
     <func>
       <name>Module:StateName(EventType, EventContent,
-        PrevStateName, StateName, StateData) -> Result
+        PrevStateName, StateName, Data) -> Result
       </name>
       <name>Module:handle_event(EventType, EventContent,
-        PrevState, State, StateData) -> Result
+        PrevState, State, Data) -> Result
       </name>
       <fsummary>Handle an event</fsummary>
       <type>
@@ -1003,8 +1011,8 @@ erlang:'!'            -----> Module:StateName/5
 	<v>PrevState = State =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
-	<v>StateData = NewStateData =
-	  <seealso marker="#type-state_data">state_data()</seealso>
+	<v>Data = NewData =
+	  <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Result =
 	  <seealso marker="#type-state_callback_result">
@@ -1029,8 +1037,8 @@ erlang:'!'            -----> Module:StateName/5
 	  from this or from any other
 	  <seealso marker="#state_function">state function</seealso>
 	  by returning with <c>{reply,Client,Reply}</c> in
-	  <seealso marker="#type-state_op">StateOps</seealso>, in
-	  <seealso marker="#type-reply_operation">Replies</seealso>
+	  <seealso marker="#type-transition_op">Ops</seealso>, in
+	  <seealso marker="#type-reply_action">Replies</seealso>
 	  or by calling
 	  <seealso marker="#reply/2">
 	    <c>reply(Client, Reply)</c>
@@ -1050,23 +1058,25 @@ erlang:'!'            -----> Module:StateName/5
 	  does not match equal (<c>=/=</c>) to the current state
 	  all postponed events will be retried in the new state.
 	</p>
-	<p>See <seealso marker="#type-state_op">state_op()</seealso>
-	  for options that can be set and operations that can be done
+	<p>See
+	  <seealso marker="#type-transition_op">transition_op()</seealso>
+	  for options that can be set and actions that can be done
 	  by <c>gen_statem</c> after returning from this function.
 	</p>
+	<p>These functions may use
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  to return its value.
+	</p>
       </desc>
     </func>
 
     <func>
-      <name>Module:terminate(Reason, State, StateData) -> Ignored</name>
+      <name>Module:terminate(Reason, State, Data) -> Ignored</name>
       <fsummary>Clean up before termination</fsummary>
       <type>
         <v>Reason = normal | shutdown | {shutdown,term()} | term()</v>
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
-	<v>StateData =
-	  <seealso marker="#type-state_data">
-	    state_data()
-	  </seealso>
+	<v>Data = <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Ignored = term()</v>
       </type>
@@ -1085,7 +1095,7 @@ erlang:'!'            -----> Module:StateName/5
 	  is terminating.
           If it is because another callback function has returned a
           stop tuple <c>{stop,Reason}</c> in
-	  <seealso marker="#type-state_op">StateOps</seealso>,
+	  <seealso marker="#type-transition_op">Ops</seealso>,
 	  <c>Reason</c> will have the value specified in that tuple.
 	  If it is due to a failure, <c>Reason</c> is the error reason.
 	</p>
@@ -1118,11 +1128,15 @@ erlang:'!'            -----> Module:StateName/5
 	    error_logger:format/2
 	  </seealso>.
 	</p>
+	<p>This function may use
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  to return its value.
+	</p>
       </desc>
     </func>
 
     <func>
-      <name>Module:code_change(OldVsn, OldState, OldStateData, Extra) ->
+      <name>Module:code_change(OldVsn, OldState, OldData, Extra) ->
         Result
       </name>
       <fsummary>Update the internal state during upgrade/downgrade</fsummary>
@@ -1131,12 +1145,12 @@ erlang:'!'            -----> Module:StateName/5
         <v>&nbsp;&nbsp;Vsn = term()</v>
         <v>OldState = NewState = term()</v>
         <v>Extra = term()</v>
-	<v>Result = {ok,{NewState,NewStateData}} | Reason</v>
+	<v>Result = {ok,{NewState,NewData}} | Reason</v>
 	<v>OldState = NewState =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
-	<v>OldStateData = NewStateData =
-	  <seealso marker="#type-state_data">state_data()</seealso>
+	<v>OldData = NewData =
+	  <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Reason = term()</v>
       </type>
@@ -1158,7 +1172,7 @@ erlang:'!'            -----> Module:StateName/5
           <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>OldStateData</c> is the internal state
+        <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>
@@ -1166,15 +1180,19 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
         <p>If successful, the function shall return the updated
           internal state in an
-	  <c>{ok,{NewState,NewStateData}}</c> tuple.
+	  <c>{ok,{NewState,NewData}}</c> tuple.
 	</p>
 	<p>If the function returns <c>Reason</c>, the ongoing
 	  upgrade will fail and roll back to the old release.</p>
       </desc>
+	<p>This function may use
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  to return its value.
+	</p>
     </func>
 
     <func>
-      <name>Module:format_status(Opt, [PDict,State,StateData]) ->
+      <name>Module:format_status(Opt, [PDict,State,Data]) ->
         Status
       </name>
       <fsummary>Optional function for providing a term describing the
@@ -1185,8 +1203,8 @@ erlang:'!'            -----> Module:StateName/5
 	<v>State =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
-	<v>StateData =
-	  <seealso marker="#type-state_data">state_data()</seealso>
+	<v>Data =
+	  <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Key = term()</v>
 	<v>Value = term()</v>
@@ -1197,7 +1215,8 @@ erlang:'!'            -----> Module:StateName/5
           <p>This callback is optional, so callback modules need not
             export it. The <c>gen_statem</c> module provides a default
             implementation of this function that returns the callback
-            module state.
+            module state and data.  The default function will also
+	    be used if this callback fails.
 	  </p>
         </note>
         <p>This function is called by a <c>gen_statem</c> process when:</p>
@@ -1229,6 +1248,9 @@ erlang:'!'            -----> Module:StateName/5
         <p><seealso marker="#type-state"><c>State</c></seealso>
 	  is the internal state of the <c>gen_statem</c>.
 	</p>
+        <p><seealso marker="#type-data"><c>Data</c></seealso>
+	  is the internal server data of the <c>gen_statem</c>.
+	</p>
         <p>The function should return <c>Status</c>, a term that
           customises the details of the current state and status of
           the <c>gen_statem</c>. There are no restrictions on the
@@ -1250,6 +1272,10 @@ erlang:'!'            -----> Module:StateName/5
           state representations to avoid having large state terms
           printed in logfiles.
 	</p>
+	<p>This function may use
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  to return its value.
+	</p>
       </desc>
     </func>
 
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 8aa8afd091..1ca2e1009c 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -57,7 +57,7 @@
 	state_name() | % For state callback function StateName/5
 	term(). % For state callback function handle_event/5
 -type state_name() :: atom().
--type state_data() :: term().
+-type data() :: term().
 -type event_type() ::
 	{'call',Client :: client()} | 'cast' |
 	'info' | 'timeout' | 'internal'.
@@ -66,17 +66,18 @@
 -type init_option() ::
 	{'callback_mode', callback_mode()}.
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
--type state_op() ::
-	%% First NewState and NewStateData are set,
-	%% then all state_operations() are executed in order of
+-type transition_op() ::
+	%% First NewState and NewData are set,
+	%% then all transition_action()s are executed in order of
 	%% apperance. Postponing the current event is performed
-	%% (iff state_option() 'postpone' is 'true').
+	%% (iff transition_option() 'postpone' is 'true').
 	%% Lastly pending events are processed or if there are
 	%% no pending events the server goes into receive
-	%% or hibernate (iff state_option() 'hibernate' is 'true')
-	state_option() | state_operation().
--type state_option() ::
-	%% The first of each kind in the state_op() list takes precedence
+	%% or hibernate (iff transition_option() 'hibernate' is 'true')
+	transition_option() | transition_action().
+-type transition_option() ::
+	%% The last of each kind in the transition_op()
+	%% list takes precedence
 	'postpone' |  % Postpone the current event to a different (=/=) state
 	{'postpone', Postpone :: boolean()} |
 	'hibernate' | % Hibernate the server instead of going into receive
@@ -84,10 +85,10 @@
 	(Timeout :: timeout()) | % {timeout,Timeout}
 	{'timeout', % Generate a ('timeout', Msg, ...) event after Time
 	 Time :: timeout(), Msg :: term()}.
--type state_operation() ::
+-type transition_action() ::
 	%% These can occur multiple times and are executed in order
-	%% of appearence in the state_op() list
-	reply_operation() |
+	%% of appearence in the transition_op() list
+	reply_action() |
 	{'next_event', % Insert event as the next to handle
 	 EventType :: event_type(),
 	 EventContent :: term()} |
@@ -101,7 +102,7 @@
 	 MonitorRef :: reference()} |
 	{'unlink', % Unlink and clean up mess(ages)
 	 Id :: pid() | port()}.
--type reply_operation() ::
+-type reply_action() ::
 	{'reply', % Reply to a client
 	 Client :: client(), Reply :: term()}.
 -type state_callback_result() ::
@@ -109,34 +110,34 @@
      Reason :: term()} |
     {'stop', % Stop the server
      Reason :: term(),
-     NewStateData :: state_data()} |
+     NewData :: data()} |
     {'stop', % Stop the server
      Reason :: term(),
-     Replies :: [reply_operation()] | reply_operation(),
-     NewStateData :: state_data()} |
-    {'next_state', % {next_state,NewState,NewStateData,[]}
+     Replies :: [reply_action()] | reply_action(),
+     NewData :: data()} |
+    {'next_state', % {next_state,NewState,NewData,[]}
      NewState :: state(),
-     NewStateData :: state_data()} |
+     NewData :: data()} |
     {'next_state', % State transition, maybe to the same state
      NewState :: state(),
-     NewStateData :: state_data(),
-     StateOps :: [state_op()] | state_op()} |
-    {'keep_state', % {keep_state,NewStateData,[]}
-     NewStateData :: state_data()} |
+     NewData :: data(),
+     Ops :: [transition_op()] | transition_op()} |
+    {'keep_state', % {keep_state,NewData,[]}
+     NewData :: data()} |
     {'keep_state',
-     NewStateData :: state_data(),
-     StateOps :: [state_op()] | state_op()} |
+     NewData :: data(),
+     Ops :: [transition_op()] | transition_op()} |
     {'keep_state_and_data'} | % {keep_state_and_data,[]}
     {'keep_state_and_data',
-     StateOps :: [state_op()] | state_op()}.
+     Ops :: [transition_op()] | transition_op()}.
 
 %% The state machine init function.  It is called only once and
 %% the server is not running until this function has returned
 %% an {ok, ...} tuple.  Thereafter the state callbacks are called
 %% for all events to this server.
 -callback init(Args :: term()) ->
-    {'ok', state(), state_data()} |
-    {'ok', state(), state_data(), [state_op()|init_option()]} |
+    {'ok', state(), data()} |
+    {'ok', state(), data(), [transition_op()|init_option()]} |
     'ignore' |
     {'stop', Reason :: term()}.
 
@@ -152,7 +153,7 @@
 	    EventContent :: term(),
 	    PrevStateName :: state_name() | reference(),
 	    StateName :: state_name(), % Current state
-	    StateData :: state_data()) ->
+	    Data :: data()) ->
     state_callback_result().
 %%
 %% Callback for callback_mode =:= handle_event_function.
@@ -164,7 +165,7 @@
 	    EventContent :: term(),
 	    PrevState :: state(),
 	    State :: state(), % Current state
-	    StateData :: state_data()) ->
+	    Data :: data()) ->
     state_callback_result().
 
 %% Clean up before the server terminates.
@@ -172,7 +173,7 @@
 	    Reason :: 'normal' | 'shutdown' | {'shutdown', term()}
 		    | term(),
 	    State :: state(),
-	    StateData :: state_data()) ->
+	    Data :: data()) ->
     any().
 
 %% Note that the new code can expect to get an OldState from
@@ -181,9 +182,9 @@
 -callback code_change(
 	    OldVsn :: term() | {'down', term()},
 	    OldState :: state(),
-	    OldStateData :: state_data(),
+	    OldData :: data(),
 	    Extra :: term()) ->
-    {ok, {NewState :: state(), NewStateData :: state_data()}}.
+    {ok, {NewState :: state(), NewData :: data()}}.
 
 %% Format the callback module state in some sensible that is
 %% often condensed way.  For StatusOption =:= 'normal' the perferred
@@ -193,7 +194,7 @@
 	    StatusOption,
 	    [ [{Key :: term(), Value :: term()}] |
 	      state() |
-	      state_data()]) ->
+	      data()]) ->
     Status :: term() when
       StatusOption :: 'normal' | 'terminate'.
 
@@ -264,38 +265,38 @@ event_type(Type) ->
 -type start_opt() ::
 	debug_opt()
       | {'timeout', Time :: timeout()}
-      | {'spawn_opt', SOpts :: [proc_lib:spawn_option()]}.
+      | {'spawn_opt', [proc_lib:spawn_option()]}.
 -type start_ret() ::  {'ok', pid()} | 'ignore' | {'error', term()}.
 
 
 
 %% Start a state machine
 -spec start(
-	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+	Module :: module(), Args :: term(), Opts :: [start_opt()]) ->
 		   start_ret().
-start(Module, Args, Options) ->
-    gen:start(?MODULE, nolink, Module, Args, Options).
+start(Module, Args, Opts) ->
+    gen:start(?MODULE, nolink, Module, Args, Opts).
 %%
 -spec start(
 	ServerName :: server_name(),
-	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+	Module :: module(), Args :: term(), Opts :: [start_opt()]) ->
 		   start_ret().
-start(ServerName, Module, Args, Options) ->
-    gen:start(?MODULE, nolink, ServerName, Module, Args, Options).
+start(ServerName, Module, Args, Opts) ->
+    gen:start(?MODULE, nolink, ServerName, Module, Args, Opts).
 
 %% Start and link to a state machine
 -spec start_link(
-	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+	Module :: module(), Args :: term(), Opts :: [start_opt()]) ->
 		   start_ret().
-start_link(Module, Args, Options) ->
-    gen:start(?MODULE, link, Module, Args, Options).
+start_link(Module, Args, Opts) ->
+    gen:start(?MODULE, link, Module, Args, Opts).
 %%
 -spec start_link(
 	ServerName :: server_name(),
-	Module :: module(), Args :: term(), Options :: [start_opt()]) ->
+	Module :: module(), Args :: term(), Opts :: [start_opt()]) ->
 		   start_ret().
-start_link(ServerName, Module, Args, Options) ->
-    gen:start(?MODULE, link, ServerName, Module, Args, Options).
+start_link(ServerName, Module, Args, Opts) ->
+    gen:start(?MODULE, link, ServerName, Module, Args, Opts).
 
 %% Stop a state machine
 -spec stop(ServerRef :: server_ref()) -> ok.
@@ -389,7 +390,7 @@ call(ServerRef, Request, Timeout) ->
     end.
 
 %% Reply from a state machine callback to whom awaits in call/2
--spec reply([reply_operation()] | reply_operation()) -> ok.
+-spec reply([reply_action()] | reply_action()) -> ok.
 reply({reply,{_To,_Tag}=Client,Reply}) ->
     reply(Client, Reply);
 reply(Replies) when is_list(Replies) ->
@@ -411,39 +412,39 @@ reply({To,Tag}, Reply) ->
 %% started by proc_lib into a state machine using
 %% the same arguments as you would have returned from init/1
 -spec enter_loop(
-	Module :: module(), Options :: [debug_opt()],
-	State :: state(), StateData :: state_data()) ->
+	Module :: module(), Opts :: [debug_opt()],
+	State :: state(), Data :: data()) ->
 			no_return().
-enter_loop(Module, Options, State, StateData) ->
-    enter_loop(Module, Options, State, StateData, self()).
+enter_loop(Module, Opts, State, Data) ->
+    enter_loop(Module, Opts, State, Data, self()).
 %%
 -spec enter_loop(
-	Module :: module(), Options :: [debug_opt()],
-	State :: state(), StateData :: state_data(),
-	Server_or_StateOps ::
-	  server_name() | pid() | [state_op()|init_option()]) ->
+	Module :: module(), Opts :: [debug_opt()],
+	State :: state(), Data :: data(),
+	Server_or_Ops ::
+	  server_name() | pid() | [transition_op()|init_option()]) ->
 			no_return().
-enter_loop(Module, Options, State, StateData, Server_or_StateOps) ->
+enter_loop(Module, Opts, State, Data, Server_or_Ops) ->
     if
-	is_list(Server_or_StateOps) ->
+	is_list(Server_or_Ops) ->
 	    enter_loop(
-	      Module, Options, State, StateData,
-	      self(), Server_or_StateOps);
+	      Module, Opts, State, Data,
+	      self(), Server_or_Ops);
 	true ->
 	    enter_loop(
-	      Module, Options, State, StateData,
-	      Server_or_StateOps, [])
+	      Module, Opts, State, Data,
+	      Server_or_Ops, [])
     end.
 %%
 -spec enter_loop(
-	Module :: module(), Options :: [debug_opt()],
-	State :: state(), StateData :: state_data(),
+	Module :: module(), Opts :: [debug_opt()],
+	State :: state(), Data :: data(),
 	Server :: server_name() | pid(),
-	StateOps :: [state_op()|init_option()]) ->
+	Ops :: [transition_op()|init_option()]) ->
 			no_return().
-enter_loop(Module, Options, State, StateData, Server, StateOps) ->
+enter_loop(Module, Opts, State, Data, Server, Ops) ->
     Parent = gen:get_parent(),
-    enter(Module, Options, State, StateData, Server, StateOps, Parent).
+    enter(Module, Opts, State, Data, Server, Ops, Parent).
 
 %%---------------------------------------------------------------------------
 %% API helpers
@@ -465,29 +466,29 @@ do_send(Proc, Msg) ->
     end.
 
 %% Here init_it and all enter_loop functions converge
-enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
+enter(Module, Opts, State, Data, Server, InitOps, Parent) ->
     Name = gen:get_proc_name(Server),
-    Debug = gen:debug_options(Name, Options),
+    Debug = gen:debug_options(Name, Opts),
     PrevState = undefined,
     S = #{
       callback_mode => state_functions,
       module => Module,
       name => Name,
       prev_state => PrevState,
-      state => PrevState, % Will be discarded by loop_event_state_ops
-      state_data => StateData,
+      state => PrevState, % Will be discarded by loop_event_transition_ops
+      data => Data,
       timer => undefined,
       postponed => [],
       hibernate => false},
     case collect_init_options(InitOps) of
-	{CallbackMode,StateOps} ->
-	    loop_event_state_ops(
+	{CallbackMode,Ops} ->
+	    loop_event_transition_ops(
 	      Parent, Debug,
 	      S#{callback_mode := CallbackMode},
 	      [],
 	      {event,undefined}, % Will be discarded by {postpone,false}
-	      PrevState, State, StateData,
-	      StateOps++[{postpone,false}]);
+	      PrevState, State, Data,
+	      Ops++[{postpone,false}]);
 	[Reason] ->
 	    ?TERMINATE(Reason, Debug, S, [])
     end.
@@ -495,13 +496,13 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
 %%%==========================================================================
 %%%  gen callbacks
 
-init_it(Starter, Parent, ServerRef, Module, Args, Options) ->
+init_it(Starter, Parent, ServerRef, Module, Args, Opts) ->
     try Module:init(Args) of
 	Result ->
-	    init_result(Starter, Parent, ServerRef, Module, Result, Options)
+	    init_result(Starter, Parent, ServerRef, Module, Result, Opts)
     catch
 	Result ->
-	    init_result(Starter, Parent, ServerRef, Module, Result, Options);
+	    init_result(Starter, Parent, ServerRef, Module, Result, Opts);
 	Class:Reason ->
 	    gen:unregister_name(ServerRef),
 	    proc_lib:init_ack(Starter, {error,Reason}),
@@ -511,18 +512,14 @@ init_it(Starter, Parent, ServerRef, Module, Args, Options) ->
 %%---------------------------------------------------------------------------
 %% gen callbacks helpers
 
-init_result(Starter, Parent, ServerRef, Module, Result, Options) ->
+init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
     case Result of
-	{ok,State,StateData} ->
+	{ok,State,Data} ->
 	    proc_lib:init_ack(Starter, {ok,self()}),
-	    enter(
-	      Module, Options, State, StateData, ServerRef,
-	      [], Parent);
-	{ok,State,StateData,StateOps} ->
+	    enter(Module, Opts, State, Data, ServerRef, [], Parent);
+	{ok,State,Data,Ops} ->
 	    proc_lib:init_ack(Starter, {ok,self()}),
-	    enter(
-	      Module, Options, State, StateData, ServerRef,
-	      StateOps, Parent);
+	    enter(Module, Opts, State, Data, ServerRef, Ops, Parent);
 	{stop,Reason} ->
 	    gen:unregister_name(ServerRef),
 	    proc_lib:init_ack(Starter, {error,Reason}),
@@ -549,32 +546,32 @@ system_terminate(Reason, _Parent, Debug, S) ->
 system_code_change(
   #{module := Module,
     state := State,
-    state_data := StateData} = S,
+    data := Data} = S,
   _Mod, OldVsn, Extra) ->
     case
-	try Module:code_change(OldVsn, State, StateData, Extra)
+	try Module:code_change(OldVsn, State, Data, Extra)
 	catch
 	    Result -> Result
 	end
     of
-	{ok,{NewState,NewStateData}} ->
+	{ok,{NewState,NewData}} ->
 	    {ok,
 	     S#{
 	       state := NewState,
-	       state_data := NewStateData}};
+	       data := NewData}};
 	Error ->
 	    Error
     end.
 
-system_get_state(#{state := State, state_data := StateData}) ->
-    {ok,{State,StateData}}.
+system_get_state(#{state := State, data := Data}) ->
+    {ok,{State,Data}}.
 
 system_replace_state(
   StateFun,
   #{state := State,
-    state_data := StateData} = S) ->
-    {NewState,NewStateData} = Result = StateFun({State,StateData}),
-    {ok,Result,S#{state := NewState, state_data := NewStateData}}.
+    data := Data} = S) ->
+    {NewState,NewData} = Result = StateFun({State,Data}),
+    {ok,Result,S#{state := NewState, data := NewData}}.
 
 format_status(
   Opt,
@@ -642,7 +639,7 @@ wakeup_from_hibernate(Parent, Debug, S) ->
     loop_receive(Parent, Debug, S).
 
 %%%==========================================================================
-%%% STate Machine engine implementation of proc_lib/gen server
+%%% State Machine engine implementation of proc_lib/gen server
 
 %% Server loop, consists of all loop* functions
 %% and some detours through sys and proc_lib
@@ -717,7 +714,7 @@ loop_events(
     module := Module,
     prev_state := PrevState,
     state := State,
-    state_data := StateData} = S,
+    data := Data} = S,
   [{Type,Content} = Event|Events] = Q, Timer) ->
     _ = (Timer =/= undefined) andalso
 	cancel_timer(Timer),
@@ -728,7 +725,7 @@ loop_events(
 	    state_functions ->
 		State
 	end,
-    try Module:Func(Type, Content, PrevState, State, StateData) of
+    try Module:Func(Type, Content, PrevState, State, Data) of
 	Result ->
 	    loop_event_result(
 	      Parent, Debug, S, Events, Event, Result)
@@ -741,7 +738,7 @@ loop_events(
 	    %% of calling a nonexistent state function
 	    case erlang:get_stacktrace() of
 		[{Module,Func,
-		  [Type,Content,PrevState,State,StateData]=Args,
+		  [Type,Content,PrevState,State,Data]=Args,
 		  _}
 		 |Stacktrace] ->
 		    terminate(
@@ -760,18 +757,18 @@ loop_events(
 %% Interpret all callback return value variants
 loop_event_result(
   Parent, Debug,
-  #{state := State, state_data := StateData} = S,
+  #{state := State, data := Data} = S,
   Events, Event, Result) ->
     case Result of
 	{stop,Reason} ->
 	    ?TERMINATE(Reason, Debug, S, [Event|Events]);
-	{stop,Reason,NewStateData} ->
+	{stop,Reason,NewData} ->
 	    ?TERMINATE(
 	      Reason, Debug,
-	      S#{state_data := NewStateData},
+	      S#{data := NewData},
 	      [Event|Events]);
-	{stop,Reason,Reply,NewStateData} ->
-	    NewS = S#{state_data := NewStateData},
+	{stop,Reason,Reply,NewData} ->
+	    NewS = S#{data := NewData},
 	    Q = [Event|Events],
 	    Replies =
 		if
@@ -785,43 +782,43 @@ loop_event_result(
 		  exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
 	    %% Since we got back here Replies was bad
 	    ?TERMINATE(
-	      {bad_return_value,{stop,Reason,BadReplies,NewStateData}},
+	      {bad_return_value,{stop,Reason,BadReplies,NewData}},
 	      Debug, NewS, Q);
-	{next_state,NewState,NewStateData} ->
-	    loop_event_state_ops(
+	{next_state,NewState,NewData} ->
+	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewStateData, []);
-	{next_state,NewState,NewStateData,StateOps}
-	  when is_list(StateOps) ->
-	    loop_event_state_ops(
+	      State, NewState, NewData, []);
+	{next_state,NewState,NewData,Ops}
+	  when is_list(Ops) ->
+	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewStateData, StateOps);
-	{keep_state,NewStateData} ->
-	    loop_event_state_ops(
+	      State, NewState, NewData, Ops);
+	{keep_state,NewData} ->
+	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
-	      State, State, NewStateData, []);
-	{keep_state,NewStateData,StateOps} ->
-	    loop_event_state_ops(
+	      State, State, NewData, []);
+	{keep_state,NewData,Ops} ->
+	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
-	      State, State, NewStateData, StateOps);
+	      State, State, NewData, Ops);
 	{keep_state_and_data} ->
-	    loop_event_state_ops(
+	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
-	      State, State, StateData, []);
-	{keep_state_and_data,StateOps} ->
-	    loop_event_state_ops(
+	      State, State, Data, []);
+	{keep_state_and_data,Ops} ->
+	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
-	      State, State, StateData, StateOps);
+	      State, State, Data, Ops);
 	_ ->
 	    ?TERMINATE(
 	      {bad_return_value,Result}, Debug, S, [Event|Events])
     end.
 
-loop_event_state_ops(
+loop_event_transition_ops(
   Parent, Debug0, #{postponed := P0} = S, Events, Event,
-  State, NewState, NewStateData, StateOps) ->
-    case collect_state_options(StateOps) of
-	{Postpone,Hibernate,Timeout,Operations} ->
+  State, NewState, NewData, Ops) ->
+    case collect_transition_options(Ops) of
+	{Postpone,Hibernate,Timeout,Actions} ->
 	    P1 = % Move current event to postponed if Postpone
 		case Postpone of
 		    true ->
@@ -837,8 +834,8 @@ loop_event_state_ops(
 			{lists:reverse(P1, Events),[]}
 		end,
 	    %%
-	    case process_state_operations(
-		   Operations, Debug0, S, Q2, P2) of
+	    case process_transition_actions(
+		   Actions, Debug0, S, Q2, P2) of
 		{Debug,Q3,P} ->
 		    NewDebug =
 			sys_debug(
@@ -865,7 +862,7 @@ loop_event_state_ops(
 		      S#{
 			prev_state := State,
 			state := NewState,
-			state_data := NewStateData,
+			data := NewData,
 			timer := Timer,
 			hibernate := Hibernate,
 			postponed := P},
@@ -892,92 +889,96 @@ collect_init_options(InitOps) ->
 	    collect_init_options([InitOps], state_functions, [])
     end.
 %% Keep the last of each kind
-collect_init_options([], CallbackMode, StateOps) ->
-    {CallbackMode,lists:reverse(StateOps)};
-collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) ->
+collect_init_options([], CallbackMode, Ops) ->
+    {CallbackMode,lists:reverse(Ops)};
+collect_init_options(
+  [InitOp|InitOps] = AllInitOps, CallbackMode, Ops) ->
     case InitOp of
 	{callback_mode,Mode}
 	  when Mode =:= state_functions;
 	       Mode =:= handle_event_function ->
-	    collect_init_options(InitOps, Mode, StateOps);
+	    collect_init_options(InitOps, Mode, Ops);
 	{callback_mode,_} ->
-	    [{bad_init_ops,IOIOs}];
-	_ -> % Collect others as StateOps
+	    [{bad_init_ops,AllInitOps}];
+	_ -> % Collect others as Ops
 	    collect_init_options(
-	      InitOps, CallbackMode, [InitOp|StateOps])
+	      InitOps, CallbackMode, [InitOp|Ops])
     end.
 
-collect_state_options(StateOps) ->
+collect_transition_options(Ops) ->
     if
-	is_list(StateOps) ->
-	    collect_state_options(StateOps, false, false, undefined, []);
+	is_list(Ops) ->
+	    collect_transition_options(
+	      Ops, false, false, undefined, []);
 	true ->
-	    collect_state_options([StateOps], false, false, undefined, [])
+	    collect_transition_options(
+	      [Ops], false, false, undefined, [])
     end.
 %% Keep the last of each kind
-collect_state_options(
-  [], Postpone, Hibernate, Timeout, Operations) ->
-    {Postpone,Hibernate,Timeout,lists:reverse(Operations)};
-collect_state_options(
-  [StateOp|StateOps] = SOSOs, Postpone, Hibernate, Timeout, Operations) ->
-    case StateOp of
+collect_transition_options(
+  [], Postpone, Hibernate, Timeout, Actions) ->
+    {Postpone,Hibernate,Timeout,lists:reverse(Actions)};
+collect_transition_options(
+  [Op|Ops] = AllOps, Postpone, Hibernate, Timeout, Actions) ->
+    case Op of
 	postpone ->
-	    collect_state_options(
-	      StateOps, true, Hibernate, Timeout, Operations);
+	    collect_transition_options(
+	      Ops, true, Hibernate, Timeout, Actions);
 	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
-	    collect_state_options(
-	      StateOps, NewPostpone, Hibernate, Timeout, Operations);
+	    collect_transition_options(
+	      Ops, NewPostpone, Hibernate, Timeout, Actions);
 	{postpone,_} ->
-	    [{bad_state_ops,SOSOs}];
+	    [{bad_ops,AllOps}];
 	hibernate ->
-	    collect_state_options(
-	      StateOps, Postpone, true, Timeout, Operations);
+	    collect_transition_options(
+	      Ops, Postpone, true, Timeout, Actions);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
-	    collect_state_options(
-	      StateOps, Postpone, NewHibernate, Timeout, Operations);
+	    collect_transition_options(
+	      Ops, Postpone, NewHibernate, Timeout, Actions);
 	{hibernate,_} ->
-	    [{bad_state_ops,SOSOs}];
+	    [{bad_ops,AllOps}];
 	{timeout,infinity,_} -> % Ignore since it will never time out
-	    collect_state_options(
-	      StateOps, Postpone, Hibernate, undefined, Operations);
+	    collect_transition_options(
+	      Ops, Postpone, Hibernate, undefined, Actions);
 	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
-	    collect_state_options(
-	      StateOps, Postpone, Hibernate, NewTimeout, Operations);
+	    collect_transition_options(
+	      Ops, Postpone, Hibernate, NewTimeout, Actions);
 	{timeout,_,_} ->
-	    [{bad_state_ops,SOSOs}];
-	_ -> % Collect others as operations
-	    collect_state_options(
-	      StateOps, Postpone, Hibernate, Timeout, [StateOp|Operations])
+	    [{bad_ops,AllOps}];
+	_ -> % Collect others as actions
+	    collect_transition_options(
+	      Ops, Postpone, Hibernate, Timeout, [Op|Actions])
     end.
 
-process_state_operations([], Debug, _S, Q, P) ->
+process_transition_actions([], Debug, _S, Q, P) ->
     {Debug,Q,P};
-process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
-    case Operation of
+process_transition_actions(
+  [Action|Actions] = AllActions, Debug, S, Q, P) ->
+    case Action of
 	{reply,{_To,_Tag}=Client,Reply} ->
 	    NewDebug = do_reply(Debug, S, Client, Reply),
-	    process_state_operations(Operations, NewDebug, S, Q, P);
+	    process_transition_actions(Actions, NewDebug, S, Q, P);
 	{next_event,Type,Content} ->
 	    case event_type(Type) of
 		true ->
-		    process_state_operations(
-		      Operations, Debug, S, [{Type,Content}|Q], P);
+		    process_transition_actions(
+		      Actions, Debug, S, [{Type,Content}|Q], P);
 		false ->
-		    [{bad_state_ops,OOs},Debug]
+		    [{bad_ops,AllActions},Debug]
 	    end;
 	_ ->
-	    %% All others are remove operations
-	    case remove_fun(Operation) of
+	    %% All others are remove actions
+	    case remove_fun(Action) of
 		false ->
-		    process_state_operations(
-		      Operations, Debug, S, Q, P);
+		    process_transition_actions(
+		      Actions, Debug, S, Q, P);
 		undefined ->
-		    [{bad_state_ops,OOs},Debug];
+		    [{bad_ops,AllActions},Debug];
 		RemoveFun when is_function(RemoveFun, 2) ->
 		    case remove_event(RemoveFun, Q, P) of
 			{NewQ,NewP} ->
-			    process_state_operations(
-			      Operations, Debug, S, NewQ, NewP);
+			    process_transition_actions(
+			      Actions, Debug, S, NewQ, NewP);
 			Error ->
 			    Error ++ [Debug]
 		    end;
@@ -1023,7 +1024,8 @@ remove_event(RemoveFun, Q, P) ->
 	    [Class,Reason,erlang:get_stacktrace()]
     end.
 
-%% Do the given state operation and create an event removal predicate fun()
+%% Do the given transition action and create
+%% an event removal predicate fun()
 remove_fun({remove_event,Type,Content}) ->
     fun (T, C) when T =:= Type, C =:= Content -> true;
 	(_, _) -> false
@@ -1104,9 +1106,9 @@ cancel_timer(TimerRef) ->
 terminate(
   Class, Reason, Stacktrace, Debug,
   #{module := Module,
-    state := State, state_data := StateData} = S,
+    state := State, data := Data} = S,
   Q) ->
-    try Module:terminate(Reason, State, StateData) of
+    try Module:terminate(Reason, State, Data) of
 	_ -> ok
     catch
 	_ -> ok;
@@ -1137,7 +1139,7 @@ error_info(
   Class, Reason, Stacktrace, Debug,
   #{name := Name, callback_mode := CallbackMode,
     state := State, postponed := P},
-  Q, FmtStateData) ->
+  Q, FmtData) ->
     {FixedReason,FixedStacktrace} =
 	case Stacktrace of
 	    [{M,F,Args,_}|ST]
@@ -1190,7 +1192,7 @@ error_info(
 	   [Event|_] ->
 	       [Event]
        end] ++
-	  [FmtStateData,Class,FixedReason,
+	  [FmtData,Class,FixedReason,
 	   State,CallbackMode,length(Q),length(P)] ++
 	  case FixedStacktrace of
 	      [] ->
@@ -1205,22 +1207,22 @@ error_info(
 %% Call Module:format_status/2 or return a default value
 format_status(
   Opt, PDict,
-  #{module := Module, state := State, state_data := StateData}) ->
+  #{module := Module, state := State, data := Data}) ->
     case erlang:function_exported(Module, format_status, 2) of
 	true ->
-	    try Module:format_status(Opt, [PDict,State,StateData])
+	    try Module:format_status(Opt, [PDict,State,Data])
 	    catch
 		Result -> Result;
 		_:_ ->
-		    format_status_default(Opt, State, StateData)
+		    format_status_default(Opt, State, Data)
 	    end;
 	false ->
-	    format_status_default(Opt, State, StateData)
+	    format_status_default(Opt, State, Data)
     end.
 
 %% The default Module:format_status/2
-format_status_default(Opt, State, StateData) ->
-    SSD = {State,StateData},
+format_status_default(Opt, State, Data) ->
+    SSD = {State,Data},
     case Opt of
 	terminate ->
 	    SSD;
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 4ac4acd189..65a8d35645 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -573,10 +573,10 @@ call_format_status(Config) when is_list(Config) ->
 error_format_status(Config) when is_list(Config) ->
     error_logger_forwarder:register(),
     OldFl = process_flag(trap_exit, true),
-    StateData = "called format_status",
+    Data = "called format_status",
     {ok,Pid} =
 	gen_statem:start(
-	  ?MODULE, start_arg(Config, {state_data,StateData}), []),
+	  ?MODULE, start_arg(Config, {data,Data}), []),
     %% bad return value in the gen_statem loop
     {{bad_return_value,badreturn},_} =
 	?EXPECT_FAILURE(gen_statem:call(Pid, badreturn), Reason),
@@ -585,7 +585,7 @@ error_format_status(Config) when is_list(Config) ->
 	 {Pid,
 	  "** State machine"++_,
 	  [Pid,{{call,_},badreturn},
-	   {formatted,idle,StateData},
+	   {formatted,idle,Data},
 	   exit,{bad_return_value,badreturn}|_]}} ->
 	    ok;
 	Other when is_tuple(Other), element(1, Other) =:= error ->
@@ -609,10 +609,10 @@ error_format_status(Config) when is_list(Config) ->
 terminate_crash_format(Config) when is_list(Config) ->
     error_logger_forwarder:register(),
     OldFl = process_flag(trap_exit, true),
-    StateData = crash_terminate,
+    Data = crash_terminate,
     {ok,Pid} =
 	gen_statem:start(
-	  ?MODULE, start_arg(Config, {state_data,StateData}), []),
+	  ?MODULE, start_arg(Config, {data,Data}), []),
     stop_it(Pid),
     Self = self(),
     receive
@@ -621,7 +621,7 @@ terminate_crash_format(Config) when is_list(Config) ->
 	  "** State machine"++_,
 	  [Pid,
 	   {{call,{Self,_}},stop},
-	   {formatted,idle,StateData},
+	   {formatted,idle,Data},
 	   exit,{crash,terminate}|_]}} ->
 	    ok;
 	Other when is_tuple(Other), element(1, Other) =:= error ->
@@ -647,7 +647,7 @@ get_state(Config) when is_list(Config) ->
     State = self(),
     {ok,Pid} =
 	gen_statem:start(
-	  ?MODULE, start_arg(Config, {state_data,State}), []),
+	  ?MODULE, start_arg(Config, {data,State}), []),
     {idle,State} = sys:get_state(Pid),
     {idle,State} = sys:get_state(Pid, 5000),
     stop_it(Pid),
@@ -656,7 +656,7 @@ get_state(Config) when is_list(Config) ->
     %% already checked by the previous test)
     {ok,Pid2} =
 	gen_statem:start(
-	  {local,gstm}, ?MODULE, start_arg(Config, {state_data,State}), []),
+	  {local,gstm}, ?MODULE, start_arg(Config, {data,State}), []),
     {idle,State} = sys:get_state(gstm),
     {idle,State} = sys:get_state(gstm, 5000),
     stop_it(Pid2),
@@ -664,7 +664,7 @@ get_state(Config) when is_list(Config) ->
     %% check that get_state works when pid is sys suspended
     {ok,Pid3} =
 	gen_statem:start(
-	  ?MODULE, start_arg(Config, {state_data,State}), []),
+	  ?MODULE, start_arg(Config, {data,State}), []),
     {idle,State} = sys:get_state(Pid3),
     ok = sys:suspend(Pid3),
     {idle,State} = sys:get_state(Pid3, 5000),
@@ -676,7 +676,7 @@ replace_state(Config) when is_list(Config) ->
     State = self(),
     {ok, Pid} =
 	gen_statem:start(
-	  ?MODULE, start_arg(Config, {state_data,State}), []),
+	  ?MODULE, start_arg(Config, {data,State}), []),
     {idle,State} = sys:get_state(Pid),
     NState1 = "replaced",
     Replace1 = fun({StateName, _}) -> {StateName,NState1} end,
@@ -1124,8 +1124,8 @@ init(hiber) ->
     {ok,hiber_idle,[]};
 init(hiber_now) ->
     {ok,hiber_idle,[],[hibernate]};
-init({state_data, StateData}) ->
-    {ok,idle,StateData};
+init({data, Data}) ->
+    {ok,idle,Data};
 init({init_ops,Arg,InitOps}) ->
     case init(Arg) of
 	{ok,State,Data,Ops} ->
@@ -1136,7 +1136,7 @@ init({init_ops,Arg,InitOps}) ->
 	    Other
     end;
 init([]) ->
-    {ok,idle,state_data}.
+    {ok,idle,data}.
 
 terminate(_, _State, crash_terminate) ->
     exit({crash,terminate});
@@ -1362,20 +1362,20 @@ unwrap_state(State) ->
 
 wrap_result(Result) ->
     case Result of
-	{next_state,NewState,NewStateData} ->
-	    {next_state,[NewState],NewStateData};
-	{next_state,NewState,NewStateData,StateOps} ->
-	    {next_state,[NewState],NewStateData,StateOps};
+	{next_state,NewState,NewData} ->
+	    {next_state,[NewState],NewData};
+	{next_state,NewState,NewData,StateOps} ->
+	    {next_state,[NewState],NewData,StateOps};
 	Other ->
 	    Other
     end.
 
 
 
-code_change(_OldVsn, State, StateData, _Extra) ->
-    {ok,State,StateData}.
+code_change(_OldVsn, State, Data, _Extra) ->
+    {ok,State,Data}.
 
-format_status(terminate, [_Pdict,State,StateData]) ->
-    {formatted,State,StateData};
-format_status(normal, [_Pdict,_State,_StateData]) ->
+format_status(terminate, [_Pdict,State,Data]) ->
+    {formatted,State,Data};
+format_status(normal, [_Pdict,_State,_Data]) ->
     [format_status_called].
-- 
cgit v1.2.3


From 867c27c5b03c846aef1e5fe4b3ee63de5f3a7f32 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 19 Feb 2016 15:36:13 +0100
Subject: Hide Data in default format_status/2 if callback crashes

---
 lib/stdlib/doc/src/gen_statem.xml | 13 ++++++++-----
 lib/stdlib/src/gen_statem.erl     |  4 +++-
 2 files changed, 11 insertions(+), 6 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 15e9584360..8462f5ff5f 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -1212,11 +1212,13 @@ erlang:'!'            -----> Module:StateName/5
       </type>
       <desc>
         <note>
-          <p>This callback is optional, so callback modules need not
+          <p>This callback is optional, so a callback module need not
             export it. The <c>gen_statem</c> module provides a default
-            implementation of this function that returns the callback
-            module state and data.  The default function will also
-	    be used if this callback fails.
+            implementation of this function that returns
+            <c>{State,Data}</c>.  If this callback fails the default
+	    function will return <c>{State,Info}</c>
+	    where <c>Info</c> informs of the crash but no details,
+	    to hide possibly sensitive data.
 	  </p>
         </note>
         <p>This function is called by a <c>gen_statem</c> process when:</p>
@@ -1270,7 +1272,8 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
         <p>One use for this function is to return compact alternative
           state representations to avoid having large state terms
-          printed in logfiles.
+          printed in logfiles.  Another is to hide sensitive data from
+	  being written to the error log.
 	</p>
 	<p>This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 1ca2e1009c..b580eaab97 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -1214,7 +1214,9 @@ format_status(
 	    catch
 		Result -> Result;
 		_:_ ->
-		    format_status_default(Opt, State, Data)
+		    format_status_default(
+		      Opt, State,
+		      "Module:format_status/2 crashed")
 	    end;
 	false ->
 	    format_status_default(Opt, State, Data)
-- 
cgit v1.2.3


From 759548838fa8b27eaa574233c9897d9578540a5a Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 22 Feb 2016 14:55:52 +0100
Subject: Make callback_option() mandatory

---
 lib/stdlib/doc/src/gen_statem.xml    |  80 ++++++++++-----------
 lib/stdlib/src/gen_statem.erl        | 131 +++++++++++++++++------------------
 lib/stdlib/test/gen_statem_SUITE.erl |  53 ++++++++------
 3 files changed, 131 insertions(+), 133 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 8462f5ff5f..bd210a0d22 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -190,7 +190,7 @@ erlang:'!'            -----> Module:StateName/5
       <name name="server_name" />
       <desc>
 	<p>Name specification to use when starting
-	  a<c>gen_statem</c> server.
+	  a <c>gen_statem</c> server.
 	  See <seealso marker="#start_link/3">
 	    <c>start_link/3</c>
 	  </seealso> and
@@ -347,17 +347,6 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
       </desc>
     </datatype>
-    <datatype>
-      <name name="init_option" />
-      <desc>
-	<p>Option that only is valid when initializing
-	  the <c>gen_statem</c> that is it can be returned from
-	  <seealso marker="#Module:init/1">Module:init/1</seealso>
-	  or given to
-	  <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
-	</p>
-      </desc>
-    </datatype>
     <datatype>
       <name name="callback_mode" />
       <desc>
@@ -459,7 +448,7 @@ erlang:'!'            -----> Module:StateName/5
 	    <seealso marker="#type-event_type">type <c>timeout</c></seealso>
 	    after <c><anno>Time</anno></c> milliseconds unless some other
 	    event is received before that time.  Note that a retried
-	    event counts just like a new in this respect.
+	    or inserted event counts just like a new in this respect.
 	    If <c>Time =:= infinity</c> no timer is started.
 	    If <c>Time =:= 0</c> the timeout event
 	    is immediately enqueued as the newest received.
@@ -468,7 +457,7 @@ erlang:'!'            -----> Module:StateName/5
 	    <seealso marker="#type-transition_action">
 	      <c>transition_action()</c>
 	    </seealso> <c>cancel_timer</c>.
-	    This timeout is cancelled automatically by any event.
+	    This timeout is cancelled automatically by any other event.
 	  </item>
 	</taglist>
       </desc>
@@ -478,9 +467,9 @@ erlang:'!'            -----> Module:StateName/5
       <desc>
 	<p>The state transition actions are executed
 	  in the containing list order.  This matters
-	  for <c>next_event</c> where the last one in the list
-	  will become the next event to present
-	  to the state functions.  Regarding the other actions
+	  for <c>next_event</c> where the last such in the list
+	  will become the next event to process by
+	  the current state function.  Regarding the other actions
 	  it is only for <c>remove_event</c> with
 	  <c><anno>EventPredicate</anno></c>
 	  and for <c>reply_action()</c> that the order may matter.
@@ -490,7 +479,9 @@ erlang:'!'            -----> Module:StateName/5
 	  <item>Reply to a calling client.</item>
 	  <tag><c>next_event</c></tag>
 	  <item>Insert the given <c><anno>EventType</anno></c>
-	    and <c><anno>EventContent</anno></c> the next to process.
+	    and <c><anno>EventContent</anno></c> as the next to process.
+	    This will bypass any events in the process mailbox as well
+	    as any other queued events.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
@@ -841,11 +832,11 @@ erlang:'!'            -----> Module:StateName/5
     </func>
 
     <func>
-      <name name="enter_loop" arity="4" />
+      <name name="enter_loop" arity="5" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
 	<p>The same as
-	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
+	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  except that no
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
@@ -854,12 +845,12 @@ erlang:'!'            -----> Module:StateName/5
       </desc>
     </func>
     <func>
-      <name name="enter_loop" arity="5" />
+      <name name="enter_loop" arity="6" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
 	<p>If <c><anno>Server_or_Ops</anno></c> is a <c>list()</c>
 	  the same as
-	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
+	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  except that no
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
@@ -867,7 +858,7 @@ erlang:'!'            -----> Module:StateName/5
 	  <c>Ops = <anno>Server_or_Ops</anno></c>.
 	</p>
 	<p>Otherwise the same as
-	  <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso>
+	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  with
 	  <c>Server = <anno>Server_or_Ops</anno></c> and
 	  <c>Ops = []</c>.
@@ -875,7 +866,7 @@ erlang:'!'            -----> Module:StateName/5
       </desc>
     </func>
     <func>
-      <name name="enter_loop" arity="6" />
+      <name name="enter_loop" arity="7" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
         <p>Makes an the calling process become a <c>gen_statem</c>.
@@ -903,8 +894,8 @@ erlang:'!'            -----> Module:StateName/5
 	    <c>server_name()</c>
 	  </seealso> 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>Ops</anno></c>
+        <p><c><anno>CallbackMode</anno></c>, <c><anno>State</anno></c>,
+	  <c><anno>Data</anno></c> and <c><anno>Ops</anno></c>
 	  have the same meanings as in the return value of
           <seealso marker="#Module:init/1">Module:init/1</seealso>.
           Also, the callback module <c><anno>Module</anno></c>
@@ -938,15 +929,17 @@ erlang:'!'            -----> Module:StateName/5
       <fsummary>Initialize process and internal state</fsummary>
       <type>
         <v>Args = term()</v>
-        <v>Result = {ok,State,Data}</v>
-	<v>&nbsp;| {ok,State,Data,Ops}</v>
+        <v>Result = {CallbackMode,State,Data}</v>
+	<v>&nbsp;| {CallbackMode,State,Data,Ops}</v>
         <v>&nbsp;| {stop,Reason} | ignore</v>
+	<v>CallbackMode =
+	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	</v>
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
 	<v>Data = <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Ops =
-	  [<seealso marker="#type-transition_op">transition_op()</seealso>
-	   | <seealso marker="#type-init_option">init_option()</seealso>]
+	  [<seealso marker="#type-transition_op">transition_op()</seealso>]
 	</v>
 	<v>Reason = term()</v>
       </type>
@@ -962,21 +955,20 @@ erlang:'!'            -----> Module:StateName/5
         <p><c>Args</c> is the <c>Args</c> argument provided to the start
           function.</p>
         <p>If the initialization is successful, the function should
-          return <c>{ok,State,Data}</c> or
-	  <c>{ok,State,Data,Ops}</c>.
-	  <c>State</c> is the <seealso marker="#type-state">state</seealso>
+          return <c>{CallbackMode,State,Data}</c> or
+	  <c>{CallbackMode,State,Data,Ops}</c>.
+	  <c>CallbackMode</c> selects the
+	  <seealso marker="#type-callback_mode">callback_mode()</seealso>.
 	  of the <c>gen_statem</c>.
+	  <c>State</c> is the <seealso marker="#type-state">state()</seealso>
+	  of the <c>gen_statem</c> and
+	  <c>Data</c> the server <seealso marker="#type-data">data()</seealso>
 	</p>
 	<p>The <seealso marker="#type-transition_op"><c>Ops</c></seealso>
 	  are executed when entering the first
 	  <seealso marker="#type-state">state</seealso> just as for a
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
-	<p>This function allows an option to select the callback mode
-	  of the <c>gen_statem</c>.  See
-	  <seealso marker="#type-init_option">init_option</seealso>.
-	  This option is not allowed from the state function(s).
-	</p>
         <p>If something goes wrong during the initialization
           the function should return <c>{stop,Reason}</c>
 	  or <c>ignore</c>. See
@@ -984,7 +976,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
-	  to return its value.
+	  to return <c>Result</c>.
 	</p>
       </desc>
     </func>
@@ -1065,7 +1057,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>These functions may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
-	  to return its value.
+	  to return <c>Result</c>.
 	</p>
       </desc>
     </func>
@@ -1130,7 +1122,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
-	  to return its value.
+	  to return <c>Ignored</c>, which is ignored anyway.
 	</p>
       </desc>
     </func>
@@ -1184,11 +1176,11 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>If the function returns <c>Reason</c>, the ongoing
 	  upgrade will fail and roll back to the old release.</p>
-      </desc>
 	<p>This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
-	  to return its value.
+	  to return <c>Result</c> or <c>Reason</c>.
 	</p>
+      </desc>
     </func>
 
     <func>
@@ -1277,7 +1269,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<p>This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
-	  to return its value.
+	  to return <c>Status</c>.
 	</p>
       </desc>
     </func>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index b580eaab97..32799f5afc 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -24,7 +24,7 @@
    [start/3,start/4,start_link/3,start_link/4,
     stop/1,stop/3,
     cast/2,call/2,call/3,
-    enter_loop/4,enter_loop/5,enter_loop/6,
+    enter_loop/5,enter_loop/6,enter_loop/7,
     reply/1,reply/2]).
 
 %% gen callbacks
@@ -63,8 +63,6 @@
 	'info' | 'timeout' | 'internal'.
 -type event_predicate() :: % Return true for the event in question
 	fun((event_type(), term()) -> boolean()).
--type init_option() ::
-	{'callback_mode', callback_mode()}.
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
 -type transition_op() ::
 	%% First NewState and NewData are set,
@@ -136,12 +134,12 @@
 %% an {ok, ...} tuple.  Thereafter the state callbacks are called
 %% for all events to this server.
 -callback init(Args :: term()) ->
-    {'ok', state(), data()} |
-    {'ok', state(), data(), [transition_op()|init_option()]} |
+    {callback_mode(), state(), data()} |
+    {callback_mode(), state(), data(), [transition_op()]} |
     'ignore' |
     {'stop', Reason :: term()}.
 
-%% Example callback for callback_mode =:= state_functions
+%% Example state callback for callback_mode() =:= state_functions
 %% state name 'state_name'.
 %%
 %% In this mode all states has to be type state_name() i.e atom().
@@ -156,7 +154,7 @@
 	    Data :: data()) ->
     state_callback_result().
 %%
-%% Callback for callback_mode =:= handle_event_function.
+%% State callback for callback_mode() =:= handle_event_function.
 %%
 %% Note that state callbacks and only state callbacks have arity 5
 %% and that is intended.
@@ -199,7 +197,8 @@
       StatusOption :: 'normal' | 'terminate'.
 
 -optional_callbacks(
-   [format_status/2, % Has got a default implementation
+   [init/1, % One may use enter_loop/5,6,7 instead
+    format_status/2, % Has got a default implementation
     %%
     state_name/5, % Example for callback_mode =:= state_functions:
     %% there has to be a StateName/5 callback function for every StateName.
@@ -207,6 +206,16 @@
     handle_event/5]). % For callback_mode =:= handle_event_function
 
 %% Type validation functions
+callback_mode(CallbackMode) ->
+    case CallbackMode of
+	state_functions ->
+	    true;
+	handle_event_function ->
+	    true;
+	_ ->
+	    false
+    end.
+%%
 client({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
     true;
 client(_) ->
@@ -413,38 +422,41 @@ reply({To,Tag}, Reply) ->
 %% the same arguments as you would have returned from init/1
 -spec enter_loop(
 	Module :: module(), Opts :: [debug_opt()],
+	CallbackMode :: callback_mode(),
 	State :: state(), Data :: data()) ->
 			no_return().
-enter_loop(Module, Opts, State, Data) ->
-    enter_loop(Module, Opts, State, Data, self()).
+enter_loop(Module, Opts, CallbackMode, State, Data) ->
+    enter_loop(Module, Opts, CallbackMode, State, Data, self()).
 %%
 -spec enter_loop(
 	Module :: module(), Opts :: [debug_opt()],
+	CallbackMode :: callback_mode(),
 	State :: state(), Data :: data(),
 	Server_or_Ops ::
-	  server_name() | pid() | [transition_op()|init_option()]) ->
+	  server_name() | pid() | [transition_op()]) ->
 			no_return().
-enter_loop(Module, Opts, State, Data, Server_or_Ops) ->
+enter_loop(Module, Opts, CallbackMode, State, Data, Server_or_Ops) ->
     if
 	is_list(Server_or_Ops) ->
 	    enter_loop(
-	      Module, Opts, State, Data,
+	      Module, Opts, CallbackMode, State, Data,
 	      self(), Server_or_Ops);
 	true ->
 	    enter_loop(
-	      Module, Opts, State, Data,
+	      Module, Opts, CallbackMode, State, Data,
 	      Server_or_Ops, [])
     end.
 %%
 -spec enter_loop(
 	Module :: module(), Opts :: [debug_opt()],
+	CallbackMode :: callback_mode(),
 	State :: state(), Data :: data(),
 	Server :: server_name() | pid(),
-	Ops :: [transition_op()|init_option()]) ->
+	Ops :: [transition_op()]) ->
 			no_return().
-enter_loop(Module, Opts, State, Data, Server, Ops) ->
+enter_loop(Module, Opts, CallbackMode, State, Data, Server, Ops) ->
     Parent = gen:get_parent(),
-    enter(Module, Opts, State, Data, Server, Ops, Parent).
+    enter(Module, Opts, CallbackMode, State, Data, Server, Ops, Parent).
 
 %%---------------------------------------------------------------------------
 %% API helpers
@@ -465,37 +477,40 @@ do_send(Proc, Msg) ->
 	    ok
     end.
 
-%% Here init_it and all enter_loop functions converge
-enter(Module, Opts, State, Data, Server, InitOps, Parent) ->
-    Name = gen:get_proc_name(Server),
-    Debug = gen:debug_options(Name, Opts),
-    PrevState = undefined,
-    S = #{
-      callback_mode => state_functions,
-      module => Module,
-      name => Name,
-      prev_state => PrevState,
-      state => PrevState, % Will be discarded by loop_event_transition_ops
-      data => Data,
-      timer => undefined,
-      postponed => [],
-      hibernate => false},
-    case collect_init_options(InitOps) of
-	{CallbackMode,Ops} ->
+%% Here init_it/6 and enter_loop/5,6,7 functions converge
+enter(Module, Opts, CallbackMode, State, Data, Server, Ops, Parent)
+  when is_atom(Module), is_pid(Parent) ->
+    case callback_mode(CallbackMode) of
+	true ->
+	    Name = gen:get_proc_name(Server),
+	    Debug = gen:debug_options(Name, Opts),
+	    PrevState = undefined,
+	    S =	#{
+	      callback_mode => CallbackMode,
+	      module => Module,
+	      name => Name,
+	      prev_state => PrevState,
+	      state => PrevState, % Discarded by loop_event_transition_ops
+	      data => Data,
+	      timer => undefined,
+	      postponed => [],
+	      hibernate => false},
 	    loop_event_transition_ops(
-	      Parent, Debug,
-	      S#{callback_mode := CallbackMode},
-	      [],
-	      {event,undefined}, % Will be discarded by {postpone,false}
+	      Parent, Debug, S, [],
+	      {event,undefined}, % Discarded due to {postpone,false}
 	      PrevState, State, Data,
 	      Ops++[{postpone,false}]);
-	[Reason] ->
-	    ?TERMINATE(Reason, Debug, S, [])
+	false ->
+	    erlang:error(
+	      badarg,
+	      [Module,Opts,CallbackMode,State,Data,Server,Ops,Parent])
     end.
 
 %%%==========================================================================
 %%%  gen callbacks
 
+init_it(Starter, self, ServerRef, Module, Args, Opts) ->
+    init_it(Starter, self(), ServerRef, Module, Args, Opts);
 init_it(Starter, Parent, ServerRef, Module, Args, Opts) ->
     try Module:init(Args) of
 	Result ->
@@ -514,12 +529,16 @@ init_it(Starter, Parent, ServerRef, Module, Args, Opts) ->
 
 init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
     case Result of
-	{ok,State,Data} ->
+	{CallbackMode,State,Data} ->
 	    proc_lib:init_ack(Starter, {ok,self()}),
-	    enter(Module, Opts, State, Data, ServerRef, [], Parent);
-	{ok,State,Data,Ops} ->
+	    enter(
+	      Module, Opts, CallbackMode, State, Data,
+	      ServerRef, [], Parent);
+	{CallbackMode,State,Data,Ops} ->
 	    proc_lib:init_ack(Starter, {ok,self()}),
-	    enter(Module, Opts, State, Data, ServerRef, Ops, Parent);
+	    enter(
+	      Module, Opts, CallbackMode, State, Data,
+	      ServerRef, Ops, Parent);
 	{stop,Reason} ->
 	    gen:unregister_name(ServerRef),
 	    proc_lib:init_ack(Starter, {error,Reason}),
@@ -881,30 +900,6 @@ loop_event_transition_ops(
 %%---------------------------------------------------------------------------
 %% Server helpers
 
-collect_init_options(InitOps) ->
-    if
-	is_list(InitOps) ->
-	    collect_init_options(InitOps, state_functions, []);
-	true ->
-	    collect_init_options([InitOps], state_functions, [])
-    end.
-%% Keep the last of each kind
-collect_init_options([], CallbackMode, Ops) ->
-    {CallbackMode,lists:reverse(Ops)};
-collect_init_options(
-  [InitOp|InitOps] = AllInitOps, CallbackMode, Ops) ->
-    case InitOp of
-	{callback_mode,Mode}
-	  when Mode =:= state_functions;
-	       Mode =:= handle_event_function ->
-	    collect_init_options(InitOps, Mode, Ops);
-	{callback_mode,_} ->
-	    [{bad_init_ops,AllInitOps}];
-	_ -> % Collect others as Ops
-	    collect_init_options(
-	      InitOps, CallbackMode, [InitOp|Ops])
-    end.
-
 collect_transition_options(Ops) ->
     if
 	is_list(Ops) ->
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 65a8d35645..a8b4d16f23 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -36,7 +36,8 @@ all() ->
      {group, abnormal},
      {group, abnormal_handle_event},
      shutdown,
-     {group, sys}, hibernate, enter_loop].
+     {group, sys},
+     hibernate, enter_loop].
 
 groups() ->
     [{start, [],
@@ -73,7 +74,7 @@ init_per_group(GroupName, Config)
        GroupName =:= stop_handle_event;
        GroupName =:= abnormal_handle_event;
        GroupName =:= sys_handle_event ->
-    [{init_ops,[{callback_mode,handle_event_function}]}|Config];
+    [{callback_mode,handle_event_function}|Config];
 init_per_group(_GroupName, Config) ->
     Config.
 
@@ -86,6 +87,8 @@ init_per_testcase(_CaseName, Config) ->
 %%%    dbg:tracer(),
 %%%    dbg:p(all, c),
 %%%    dbg:tpl(gen_statem, cx),
+%%%    dbg:tpl(proc_lib, cx),
+%%%    dbg:tpl(gen, cx),
 %%%    dbg:tpl(sys, cx),
     [{watchdog, Dog} | Config].
 
@@ -901,8 +904,11 @@ enter_loop(Config) when is_list(Config) ->
     end,
 
     %% Process not started using proc_lib
+    CallbackMode = state_functions,
     Pid4 =
-	spawn_link(gen_statem, enter_loop, [?MODULE,[],state0,[]]),
+	spawn_link(
+	  gen_statem, enter_loop,
+	  [?MODULE,[],CallbackMode,state0,[]]),
     receive
 	{'EXIT',Pid4,process_was_not_started_by_proc_lib} ->
 	    ok
@@ -976,16 +982,21 @@ enter_loop(Reg1, Reg2) ->
 	anon -> ignore
     end,
     proc_lib:init_ack({ok, self()}),
+    CallbackMode = state_functions,
     case Reg2 of
 	local ->
-	    gen_statem:enter_loop(?MODULE, [], state0, [], {local,armitage});
+	    gen_statem:enter_loop(
+	      ?MODULE, [], CallbackMode, state0, [], {local,armitage});
 	global ->
-	    gen_statem:enter_loop(?MODULE, [], state0, [], {global,armitage});
+	    gen_statem:enter_loop(
+	      ?MODULE, [], CallbackMode, state0, [], {global,armitage});
 	via ->
-	    gen_statem:enter_loop(?MODULE, [], state0, [],
-			       {via, dummy_via, armitage});
+	    gen_statem:enter_loop(
+	      ?MODULE, [], CallbackMode, state0, [],
+	      {via, dummy_via, armitage});
 	anon ->
-	    gen_statem:enter_loop(?MODULE, [], state0, [])
+	    gen_statem:enter_loop(
+	      ?MODULE, [], CallbackMode, state0, [])
     end.
 
 %%
@@ -1098,9 +1109,9 @@ verify_empty_msgq() ->
     ok.
 
 start_arg(Config, Arg) ->
-    case lists:keyfind(init_ops, 1, Config) of
-	{_,Ops} ->
-	    {init_ops,Arg,Ops};
+    case lists:keyfind(callback_mode, 1, Config) of
+	{_,CallbackMode} ->
+	    {callback_mode,CallbackMode,Arg};
 	false ->
 	    Arg
     end.
@@ -1119,24 +1130,24 @@ init(stop_shutdown) ->
     {stop,shutdown};
 init(sleep) ->
     ?t:sleep(1000),
-    {ok,idle,data};
+    {state_functions,idle,data};
 init(hiber) ->
-    {ok,hiber_idle,[]};
+    {state_functions,hiber_idle,[]};
 init(hiber_now) ->
-    {ok,hiber_idle,[],[hibernate]};
+    {state_functions,hiber_idle,[],[hibernate]};
 init({data, Data}) ->
-    {ok,idle,Data};
-init({init_ops,Arg,InitOps}) ->
+    {state_functions,idle,Data};
+init({callback_mode,CallbackMode,Arg}) ->
     case init(Arg) of
-	{ok,State,Data,Ops} ->
-	    {ok,State,Data,InitOps++Ops};
-	{ok,State,Data} ->
-	    {ok,State,Data,InitOps};
+	{_,State,Data,Ops} ->
+	    {CallbackMode,State,Data,Ops};
+	{_,State,Data} ->
+	    {CallbackMode,State,Data};
 	Other ->
 	    Other
     end;
 init([]) ->
-    {ok,idle,data}.
+    {state_functions,idle,data}.
 
 terminate(_, _State, crash_terminate) ->
     exit({crash,terminate});
-- 
cgit v1.2.3


From 793fe40e3883bca7c37b71fb59616a4ec8d379b1 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 23 Feb 2016 16:55:45 +0100
Subject: Rename Client -> Caller

---
 lib/stdlib/doc/src/gen_statem.xml | 50 +++++++++++++++++++--------------------
 lib/stdlib/src/gen_statem.erl     | 42 ++++++++++++++++----------------
 2 files changed, 46 insertions(+), 46 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index bd210a0d22..5ae930f48b 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -270,13 +270,13 @@ erlang:'!'            -----> Module:StateName/5
     </datatype>
 
     <datatype>
-      <name name="client" />
+      <name name="caller" />
       <desc>
-	<p>Client address to use when replying through for example the
+	<p>Destination to use when replying through for example the
 	  <seealso marker="#type-transition_op">
-	    transition_op() {reply,Client,Reply}
+	    transition_op() {reply,Caller,Reply}
 	  </seealso>
-	  to a client that has called the <c>gen_statem</c> server using
+	  to a process that has called the <c>gen_statem</c> server using
 	  <seealso marker="#call/2">call/2</seealso>.
 	</p>
       </desc>
@@ -318,7 +318,7 @@ erlang:'!'            -----> Module:StateName/5
       <name name="event_type" />
       <desc>
 	<p>External events are of 3 different type:
-	  <c>{call,<anno>Client</anno>}</c>, <c>cast</c> or <c>info</c>.
+	  <c>{call,<anno>Caller</anno>}</c>, <c>cast</c> or <c>info</c>.
 	  Calls (synchronous) and casts (asynchronous)
 	  originate from the corresponding API functions.
 	  For calls the event contain whom to reply to.
@@ -476,7 +476,7 @@ erlang:'!'            -----> Module:StateName/5
 	</p>
 	<taglist>
 	  <tag><c>reply_action()</c></tag>
-	  <item>Reply to a calling client.</item>
+	  <item>Reply to a caller.</item>
 	  <tag><c>next_event</c></tag>
 	  <item>Insert the given <c><anno>EventType</anno></c>
 	    and <c><anno>EventContent</anno></c> as the next to process.
@@ -525,11 +525,11 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="reply_action" />
       <desc>
-	<p>Reply to a client that called
+	<p>Reply to a caller waiting for a reply in
 	  <seealso marker="#call/2"><c>call/2</c></seealso>.
-          <c><anno>Client</anno></c> must be the term from the
+          <c><anno>Caller</anno></c> must be the term from the
 	  <seealso marker="#type-event_type">
-	    <c>{call,<anno>Client</anno>}</c>
+	    <c>{call,<anno>Caller</anno>}</c>
 	  </seealso> argument to the
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
@@ -747,13 +747,13 @@ erlang:'!'            -----> Module:StateName/5
 	  The <c>gen_statem</c> will call the
 	  <seealso marker="#state_function">state function</seealso> with
 	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
-	  <c>{call,Client}</c> and event content
+	  <c>{call,Caller}</c> and event content
 	  <c><anno>Request</anno></c>.
 	</p>
 	<p>A <c><anno>Reply</anno></c> is generated when a
 	  <seealso marker="#state_function">state function</seealso>
 	  returns with
-	  <c>{reply,Client,<anno>Reply</anno>}</c> as one
+	  <c>{reply,Caller,<anno>Reply</anno>}</c> as one
 	  <seealso marker="#type-transition_op">
 	    <c>transition_op()</c>
 	  </seealso>,
@@ -803,21 +803,21 @@ erlang:'!'            -----> Module:StateName/5
     <func>
       <name name="reply" arity="1" />
       <name name="reply" arity="2" />
-      <fsummary>Send a reply to a client</fsummary>
+      <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 client that called
+	  to explicitly send a reply to a process that waits in
 	  <seealso marker="#call/2"><c>call/2</c></seealso>
           when the reply cannot be defined in
-          the return value of the
+          the return value of a
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
-        <p><c><anno>Client</anno></c> must be the term from the
+        <p><c><anno>Caller</anno></c> must be the term from the
 	  <seealso marker="#type-event_type">
-	    <c>{call,<anno>Client</anno>}</c>
+	    <c>{call,<anno>Caller</anno>}</c>
 	  </seealso> argument to the
 	  <seealso marker="#state_function">state function</seealso>.
-	  <c><anno>Client</anno></c> and <c><anno>Reply</anno></c>
+	  <c><anno>Caller</anno></c> and <c><anno>Reply</anno></c>
 	  can also be specified using a
 	  <seealso marker="#type-reply_action">
 	    <c>reply_action()</c>
@@ -975,7 +975,7 @@ erlang:'!'            -----> Module:StateName/5
           <seealso marker="#start_link/3">start_link/3,4</seealso>.
 	</p>
 	<p>This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Result</c>.
 	</p>
       </desc>
@@ -1024,16 +1024,16 @@ erlang:'!'            -----> Module:StateName/5
 	  then <c>Module:handle_event/5</c> is called.
 	</p>
 	<p>If <c>EventType</c> is
-	  <seealso marker="#type-event_type"><c>{call,Client}</c></seealso>
-	  the client is waiting for a reply.  The reply can be sent
+	  <seealso marker="#type-event_type"><c>{call,Caller}</c></seealso>
+	  the caller is waiting for a reply.  The reply can be sent
 	  from this or from any other
 	  <seealso marker="#state_function">state function</seealso>
-	  by returning with <c>{reply,Client,Reply}</c> in
+	  by returning with <c>{reply,Caller,Reply}</c> in
 	  <seealso marker="#type-transition_op">Ops</seealso>, in
 	  <seealso marker="#type-reply_action">Replies</seealso>
 	  or by calling
 	  <seealso marker="#reply/2">
-	    <c>reply(Client, Reply)</c>
+	    <c>reply(Caller, Reply)</c>
 	  </seealso>.
 	</p>
         <p><c>StateName</c> is useful in some odd cases for example
@@ -1121,7 +1121,7 @@ erlang:'!'            -----> Module:StateName/5
 	  </seealso>.
 	</p>
 	<p>This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Ignored</c>, which is ignored anyway.
 	</p>
       </desc>
@@ -1177,7 +1177,7 @@ erlang:'!'            -----> Module:StateName/5
 	<p>If the function returns <c>Reason</c>, the ongoing
 	  upgrade will fail and roll back to the old release.</p>
 	<p>This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Result</c> or <c>Reason</c>.
 	</p>
       </desc>
@@ -1268,7 +1268,7 @@ erlang:'!'            -----> Module:StateName/5
 	  being written to the error log.
 	</p>
 	<p>This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Status</c>.
 	</p>
       </desc>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 32799f5afc..48dfaec42a 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -51,7 +51,7 @@
 %%% Interface functions.
 %%%==========================================================================
 
--type client() ::
+-type caller() ::
 	{To :: pid(), Tag :: term()}. % Reply-to specifier for call
 -type state() ::
 	state_name() | % For state callback function StateName/5
@@ -59,7 +59,7 @@
 -type state_name() :: atom().
 -type data() :: term().
 -type event_type() ::
-	{'call',Client :: client()} | 'cast' |
+	{'call',Caller :: caller()} | 'cast' |
 	'info' | 'timeout' | 'internal'.
 -type event_predicate() :: % Return true for the event in question
 	fun((event_type(), term()) -> boolean()).
@@ -101,8 +101,8 @@
 	{'unlink', % Unlink and clean up mess(ages)
 	 Id :: pid() | port()}.
 -type reply_action() ::
-	{'reply', % Reply to a client
-	 Client :: client(), Reply :: term()}.
+	{'reply', % Reply to a caller
+	 Caller :: caller(), Reply :: term()}.
 -type state_callback_result() ::
     {'stop', % Stop the server
      Reason :: term()} |
@@ -216,13 +216,13 @@ callback_mode(CallbackMode) ->
 	    false
     end.
 %%
-client({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
+caller({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
     true;
-client(_) ->
+caller(_) ->
     false.
 %%
-event_type({call,Client}) ->
-    client(Client);
+event_type({call,Caller}) ->
+    caller(Caller);
 event_type(Type) ->
     case Type of
 	cast ->
@@ -341,7 +341,7 @@ cast(ServerRef, Msg) when is_pid(ServerRef) ->
     do_send(ServerRef, cast(Msg)).
 
 %% Call a state machine (synchronous; a reply is expected) that
-%% arrives with type {call,Client}
+%% arrives with type {call,Caller}
 -spec call(ServerRef :: server_ref(), Request :: term()) -> Reply :: term().
 call(ServerRef, Request) ->
     call(ServerRef, Request, infinity).
@@ -400,13 +400,13 @@ call(ServerRef, Request, Timeout) ->
 
 %% Reply from a state machine callback to whom awaits in call/2
 -spec reply([reply_action()] | reply_action()) -> ok.
-reply({reply,{_To,_Tag}=Client,Reply}) ->
-    reply(Client, Reply);
+reply({reply,{_To,_Tag}=Caller,Reply}) ->
+    reply(Caller, Reply);
 reply(Replies) when is_list(Replies) ->
     [reply(Reply) || Reply <- Replies],
     ok.
 %%
--spec reply(Client :: client(), Reply :: term()) -> ok.
+-spec reply(Caller :: caller(), Reply :: term()) -> ok.
 reply({To,Tag}, Reply) ->
     Msg = {Tag,Reply},
     try To ! Msg of
@@ -703,8 +703,8 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 		_ ->
 		    Event =
 			case Msg of
-			    {'$gen_call',Client,Request} ->
-				{{call,Client},Request};
+			    {'$gen_call',Caller,Request} ->
+				{{call,Caller},Request};
 			    {'$gen_cast',E} ->
 				{cast,E};
 			    _ ->
@@ -950,8 +950,8 @@ process_transition_actions([], Debug, _S, Q, P) ->
 process_transition_actions(
   [Action|Actions] = AllActions, Debug, S, Q, P) ->
     case Action of
-	{reply,{_To,_Tag}=Client,Reply} ->
-	    NewDebug = do_reply(Debug, S, Client, Reply),
+	{reply,{_To,_Tag}=Caller,Reply} ->
+	    NewDebug = do_reply(Debug, S, Caller, Reply),
 	    process_transition_actions(Actions, NewDebug, S, Q, P);
 	{next_event,Type,Content} ->
 	    case event_type(Type) of
@@ -987,17 +987,17 @@ reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
 reply_then_terminate(
   Class, Reason, Stacktrace, Debug, S, Q, [R|Rs] = RRs) ->
     case R of
-	{reply,{_To,_Tag}=Client,Reply} ->
-	    NewDebug = do_reply(Debug, S, Client, Reply),
+	{reply,{_To,_Tag}=Caller,Reply} ->
+	    NewDebug = do_reply(Debug, S, Caller, Reply),
 	    reply_then_terminate(
 	      Class, Reason, Stacktrace, NewDebug, S, Q, Rs);
 	_ ->
 	    RRs % bad_return_value
     end.
 
-do_reply(Debug, S, Client, Reply) ->
-    reply(Client, Reply),
-    sys_debug(Debug, S, {out,Reply,Client}).
+do_reply(Debug, S, Caller, Reply) ->
+    reply(Caller, Reply),
+    sys_debug(Debug, S, {out,Reply,Caller}).
 
 
 %% Remove oldest matching event from the queue(s)
-- 
cgit v1.2.3


From 2b3a82ae44b222ce1146badcff972abb539d40ca Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 23 Feb 2016 17:58:45 +0100
Subject: Add {stop_and_reply,Reason,Replies [,Data])

Cleanup some error handling
---
 lib/stdlib/doc/src/gen_statem.xml    |  9 +++-
 lib/stdlib/src/gen_statem.erl        | 83 ++++++++++++++++++++----------------
 lib/stdlib/test/gen_statem_SUITE.erl |  8 ++--
 3 files changed, 58 insertions(+), 42 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 5ae930f48b..096be3025e 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -540,7 +540,14 @@ erlang:'!'            -----> Module:StateName/5
       <desc>
 	<taglist>
 	  <tag><c>stop</c></tag>
-	  <item>Send all <c><anno>Replies</anno></c> if given,
+	  <item>Terminate the <c>gen_statem</c> by calling
+	    <seealso marker="#Module:terminate/3">
+	      <c>Module:terminate/3</c>
+	    </seealso> with <c>Reason</c> and
+	    <c><anno>NewData</anno></c>, if given.
+	  </item>
+	  <tag><c>stop_and_reply</c></tag>
+	  <item>Send all <c><anno>Replies</anno></c>
 	    then terminate the <c>gen_statem</c> by calling
 	    <seealso marker="#Module:terminate/3">
 	      <c>Module:terminate/3</c>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 48dfaec42a..02c8d60c61 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -109,7 +109,10 @@
     {'stop', % Stop the server
      Reason :: term(),
      NewData :: data()} |
-    {'stop', % Stop the server
+    {'stop_and_reply', % Reply then stop the server
+     Reason :: term(),
+     Replies :: [reply_action()] | reply_action()} |
+    {'stop_and_reply', % Reply then stop the server
      Reason :: term(),
      Replies :: [reply_action()] | reply_action(),
      NewData :: data()} |
@@ -244,9 +247,9 @@ event_type(Type) ->
    try throw(ok) catch _ -> erlang:get_stacktrace() end).
 
 -define(
-   TERMINATE(Reason, Debug, S, Q),
+   TERMINATE(Class, Reason, Debug, S, Q),
    terminate(
-     exit,
+     Class,
      begin Reason end,
      ?STACKTRACE(),
      begin Debug end,
@@ -560,7 +563,7 @@ system_continue(Parent, Debug, S) ->
     loop(Parent, Debug, S).
 
 system_terminate(Reason, _Parent, Debug, S) ->
-    ?TERMINATE(Reason, Debug, S, []).
+    ?TERMINATE(exit, Reason, Debug, S, []).
 
 system_code_change(
   #{module := Module,
@@ -696,7 +699,7 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 		    %% EXIT is not a 2-tuple and therefore
 		    %% not an event and has no event_type(),
 		    %% but this will stand out in the crash report...
-		    ?TERMINATE(Reason, Debug, S, [EXIT]);
+		    ?TERMINATE(exit, Reason, Debug, S, [EXIT]);
 		{timeout,Timer,Content} when Timer =/= undefined ->
 		    loop_receive(
 		      Parent, Debug, S, {timeout,Content}, undefined);
@@ -780,29 +783,26 @@ loop_event_result(
   Events, Event, Result) ->
     case Result of
 	{stop,Reason} ->
-	    ?TERMINATE(Reason, Debug, S, [Event|Events]);
+	    ?TERMINATE(exit, Reason, Debug, S, [Event|Events]);
 	{stop,Reason,NewData} ->
-	    ?TERMINATE(
-	      Reason, Debug,
-	      S#{data := NewData},
-	      [Event|Events]);
-	{stop,Reason,Reply,NewData} ->
 	    NewS = S#{data := NewData},
 	    Q = [Event|Events],
-	    Replies =
-		if
-		    is_list(Reply) ->
-			Reply;
-		    true ->
-			[Reply]
-		end,
-	    BadReplies =
+	    ?TERMINATE(exit, Reason, Debug, NewS, Q);
+	{stop_and_reply,Reason,Replies} ->
+	    Q = [Event|Events],
+	    [Class,NewReason,Stacktrace,NewDebug] =
+		reply_then_terminate(
+		  exit, Reason, ?STACKTRACE(), Debug, S, Q, Replies),
+	    %% Since we got back here Replies was bad
+	    terminate(Class, NewReason, Stacktrace, NewDebug, S, Q);
+	{stop_and_reply,Reason,Replies,NewData} ->
+	    NewS = S#{data := NewData},
+	    Q = [Event|Events],
+	    [Class,NewReason,Stacktrace,NewDebug] =
 		reply_then_terminate(
 		  exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
 	    %% Since we got back here Replies was bad
-	    ?TERMINATE(
-	      {bad_return_value,{stop,Reason,BadReplies,NewData}},
-	      Debug, NewS, Q);
+	    terminate(Class, NewReason, Stacktrace, NewDebug, NewS, Q);
 	{next_state,NewState,NewData} ->
 	    loop_event_transition_ops(
 	      Parent, Debug, S, Events, Event,
@@ -830,7 +830,7 @@ loop_event_result(
 	      State, State, Data, Ops);
 	_ ->
 	    ?TERMINATE(
-	      {bad_return_value,Result}, Debug, S, [Event|Events])
+	      error, {bad_return_value,Result}, Debug, S, [Event|Events])
     end.
 
 loop_event_transition_ops(
@@ -886,15 +886,14 @@ loop_event_transition_ops(
 			hibernate := Hibernate,
 			postponed := P},
 		      Q, Timer);
-		[Reason,Debug] ->
-		    ?TERMINATE(Reason, Debug, S, [Event|Events]);
 		[Class,Reason,Stacktrace,Debug] ->
 		    terminate(
 		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
 	    end;
 	%%
-	[Reason] ->
-	    ?TERMINATE(Reason, Debug0, S, [Event|Events])
+	[Class,Reason,Stacktrace] ->
+	    terminate(
+	      Class, Reason, Stacktrace, Debug0, S, [Event|Events])
     end.
 
 %%---------------------------------------------------------------------------
@@ -923,7 +922,7 @@ collect_transition_options(
 	    collect_transition_options(
 	      Ops, NewPostpone, Hibernate, Timeout, Actions);
 	{postpone,_} ->
-	    [{bad_ops,AllOps}];
+	    [error,{bad_ops,AllOps},?STACKTRACE()];
 	hibernate ->
 	    collect_transition_options(
 	      Ops, Postpone, true, Timeout, Actions);
@@ -931,7 +930,7 @@ collect_transition_options(
 	    collect_transition_options(
 	      Ops, Postpone, NewHibernate, Timeout, Actions);
 	{hibernate,_} ->
-	    [{bad_ops,AllOps}];
+	    [error,{bad_ops,AllOps},?STACKTRACE()];
 	{timeout,infinity,_} -> % Ignore since it will never time out
 	    collect_transition_options(
 	      Ops, Postpone, Hibernate, undefined, Actions);
@@ -939,7 +938,7 @@ collect_transition_options(
 	    collect_transition_options(
 	      Ops, Postpone, Hibernate, NewTimeout, Actions);
 	{timeout,_,_} ->
-	    [{bad_ops,AllOps}];
+	    [error,{bad_ops,AllOps},?STACKTRACE()];
 	_ -> % Collect others as actions
 	    collect_transition_options(
 	      Ops, Postpone, Hibernate, Timeout, [Op|Actions])
@@ -959,7 +958,7 @@ process_transition_actions(
 		    process_transition_actions(
 		      Actions, Debug, S, [{Type,Content}|Q], P);
 		false ->
-		    [{bad_ops,AllActions},Debug]
+		    [error,{bad_ops,AllActions},?STACKTRACE(),Debug]
 	    end;
 	_ ->
 	    %% All others are remove actions
@@ -968,7 +967,7 @@ process_transition_actions(
 		    process_transition_actions(
 		      Actions, Debug, S, Q, P);
 		undefined ->
-		    [{bad_ops,AllActions},Debug];
+		    [error,{bad_ops,AllActions},?STACKTRACE(),Debug];
 		RemoveFun when is_function(RemoveFun, 2) ->
 		    case remove_event(RemoveFun, Q, P) of
 			{NewQ,NewP} ->
@@ -982,17 +981,27 @@ process_transition_actions(
 	    end
     end.
 
-reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
+reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, Replies) ->
+    if
+	is_list(Replies) ->
+	    do_reply_then_terminate(
+	      Class, Reason, Stacktrace, Debug, S, Q, Replies);
+	true ->
+	    do_reply_then_terminate(
+	      Class, Reason, Stacktrace, Debug, S, Q, [Replies])
+    end.
+%%
+do_reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
     terminate(Class, Reason, Stacktrace, Debug, S, Q);
-reply_then_terminate(
-  Class, Reason, Stacktrace, Debug, S, Q, [R|Rs] = RRs) ->
+do_reply_then_terminate(
+  Class, Reason, Stacktrace, Debug, S, Q, [R|Rs] = Replies) ->
     case R of
 	{reply,{_To,_Tag}=Caller,Reply} ->
 	    NewDebug = do_reply(Debug, S, Caller, Reply),
-	    reply_then_terminate(
+	    do_reply_then_terminate(
 	      Class, Reason, Stacktrace, NewDebug, S, Q, Rs);
 	_ ->
-	    RRs % bad_return_value
+	    [error,{bad_replies,Replies},?STACKTRACE(),Debug]
     end.
 
 do_reply(Debug, S, Caller, Reply) ->
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index a8b4d16f23..81182eff71 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -589,7 +589,7 @@ error_format_status(Config) when is_list(Config) ->
 	  "** State machine"++_,
 	  [Pid,{{call,_},badreturn},
 	   {formatted,idle,Data},
-	   exit,{bad_return_value,badreturn}|_]}} ->
+	   error,{bad_return_value,badreturn}|_]}} ->
 	    ok;
 	Other when is_tuple(Other), element(1, Other) =:= error ->
 	    error_logger_forwarder:unregister(),
@@ -1268,7 +1268,7 @@ connected(Type, Content, PrevState, State, Data) ->
     end.
 
 state0({call,From}, stop, _, _, Data) ->
-    {stop,normal,[{reply,From,stopped}],Data};
+    {stop_and_reply,normal,[{reply,From,stopped}],Data};
 state0(Type, Content, PrevState, State, Data) ->
     case handle_common_events(Type, Content, PrevState, State, Data) of
 	undefined ->
@@ -1332,11 +1332,11 @@ handle_common_events(cast, {get,Pid}, _, State, Data) ->
     Pid ! {state,State,Data},
     {next_state,State,Data};
 handle_common_events({call,From}, stop, _, _, Data) ->
-    {stop,normal,[{reply,From,stopped}],Data};
+    {stop_and_reply,normal,[{reply,From,stopped}],Data};
 handle_common_events(cast, stop, _, _, _) ->
     {stop,normal};
 handle_common_events({call,From}, {stop,Reason}, _, _, Data) ->
-    {stop,Reason,{reply,From,stopped},Data};
+    {stop_and_reply,Reason,{reply,From,stopped},Data};
 handle_common_events(cast, {stop,Reason}, _, _, _) ->
      {stop,Reason};
 handle_common_events({call,From}, 'alive?', _, State, Data) ->
-- 
cgit v1.2.3


From 1958b93b4aa90883be5102d465f67f167549dea9 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 24 Feb 2016 09:41:34 +0100
Subject: Ditch State so StateName/5 -> StateName/4

---
 lib/stdlib/doc/src/gen_statem.xml    |  64 ++++++++-------
 lib/stdlib/src/gen_statem.erl        |  36 +++++---
 lib/stdlib/test/gen_statem_SUITE.erl | 155 +++++++++++++++++------------------
 3 files changed, 136 insertions(+), 119 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 096be3025e..8934d912c6 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -62,7 +62,7 @@ gen_statem:stop       -----> Module:terminate/2
 gen_statem:call
 gen_statem:cast
 erlang:send
-erlang:'!'            -----> Module:StateName/5
+erlang:'!'            -----> Module:StateName/4
                              Module:handle_event/5
 
 -                     -----> Module:terminate/3
@@ -84,18 +84,28 @@ erlang:'!'            -----> Module:StateName/5
       in a <c>gen_statem</c> is the callback function that is called
       for all events in this state, and is selected depending on
       <seealso marker="#type-callback_mode">callback_mode</seealso>
-      that the implementation selects during <c>gen_statem</c> init.
+      that the implementation specifies during <c>gen_statem</c> init.
     </p>
     <p>When
       <seealso marker="#type-callback_mode">callback_mode</seealso>
       is <c>state_functions</c> the state has to be an atom and
       is used as the state function name.
       See
-      <seealso marker="#Module:StateName/5">
-        <c>Module:StateName/5</c>
+      <seealso marker="#Module:StateName/4">
+        <c>Module:StateName/4</c>
       </seealso>.
       This gathers all code for a specific state
       in one function and hence dispatches on state first.
+      Note that in this mode the callback function
+      <seealso marker="#Module:code_change/4">
+        <c>Module:code_change/4</c>
+      </seealso> makes the state name <c>code_change</c>
+      unusable.  Actually you might get away with using it
+      as a state name but you will have to find a way to separate
+      the two callback roles e.g by observing that you can force
+      argument 3 into having different types for the different roles.
+      This is a slippery slope, though.  It is easier
+      to simply not use <c>code_change</c> as a state name.
     </p>
     <p>When
       <seealso marker="#type-callback_mode">callback_mode</seealso>
@@ -110,13 +120,11 @@ erlang:'!'            -----> Module:StateName/5
       states so you do not accidentally postpone one event
       forever creating an infinite busy loop.
     </p>
-    <p>Any state name or any state value (depending on
-      <seealso marker="#type-callback_mode">callback_mode</seealso>)
-      is permitted with a small gotcha regarding the state
-      <c>undefined</c> that is used as the previous state when
-      the first <c>gen_statem</c> state function is called.
-      You might need to know about this faked state if you
-      inspect the previous state argument in your state functions.
+    <p>There is a small gotcha in both callback modes regarding
+      the state <c>undefined</c> that is used as the previous state
+      when the first state function is called.  So either do not
+      use <c>undefined</c> as a state, or figure out
+      the implications yourself.
     </p>
     <p>The <c>gen_statem</c> enqueues incoming events in order of arrival
       and presents these to the
@@ -181,7 +189,7 @@ erlang:'!'            -----> Module:StateName/5
       for a long time. However use this feature with care
       since hibernation implies at least two garbage collections
       (when hibernating and shortly after waking up) and that is not
-      something you'd want to do between each event on a busy server.
+      something you would want to do between each event on a busy server.
     </p>
   </description>
 
@@ -350,13 +358,20 @@ erlang:'!'            -----> Module:StateName/5
     <datatype>
       <name name="callback_mode" />
       <desc>
+	<p>
+	  The <c>callback_mode</c> is selected when starting the
+	  <c>gen_statem</c> using the return value from
+	  <seealso marker="#Module:init/1">Module:init/1</seealso>
+	  or when calling
+	  <seealso marker="#enter_loop/5">enter_loop/5-7</seealso>.
+	</p>
 	<taglist>
 	  <tag><c>state_functions</c></tag>
 	  <item>The state has to be of type
 	    <seealso marker="#type-state_name"><c>state_name()</c></seealso>
 	    and one callback function per state that is
-	    <seealso marker="#Module:StateName/5">
-	      <c>Module:StateName/5</c>
+	    <seealso marker="#Module:StateName/4">
+	      <c>Module:StateName/4</c>
 	    </seealso> is used.  This is the default.
 	  </item>
 	  <tag><c>handle_event_function</c></tag>
@@ -384,7 +399,7 @@ erlang:'!'            -----> Module:StateName/5
 	  <seealso marker="#state_function">state function</seealso>,
 	  from <seealso marker="#Module:init/1">Module:init/1</seealso>
 	  or given to
-	  <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
+	  <seealso marker="#enter_loop/6">enter_loop/6,7</seealso>.
 	</p>
 	<p>The processing order for a state change is:</p>
 	<list type="ordered">
@@ -990,7 +1005,7 @@ erlang:'!'            -----> Module:StateName/5
 
     <func>
       <name>Module:StateName(EventType, EventContent,
-        PrevStateName, StateName, Data) -> Result
+      PrevStateName, Data) -> Result
       </name>
       <name>Module:handle_event(EventType, EventContent,
         PrevState, State, Data) -> Result
@@ -1004,9 +1019,6 @@ erlang:'!'            -----> Module:StateName/5
 	<v>PrevStateName =
 	  <seealso marker="#type-state_name">state_name()</seealso>
 	</v>
-	<v>StateName =
-	  <seealso marker="#type-state_name">state_name()</seealso>
-	</v>
 	<v>PrevState = State =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
@@ -1023,10 +1035,9 @@ erlang:'!'            -----> Module:StateName/5
         <p>Whenever a <c>gen_statem</c> receives an event from
           <seealso marker="#call/2">call/2</seealso>,
           <seealso marker="#cast/2">cast/2</seealso> or
-	  as a normal process message this function is called.
-	  If
-	  <seealso marker="#type-callback_mode">callback_mode</seealso>
-	  is <c>state_functions</c> then <c>Module:StateName/5</c> is called,
+	  as a normal process message one of these functions is called.
+	  If <seealso marker="#type-callback_mode">callback_mode</seealso>
+	  is <c>state_functions</c> then <c>Module:StateName/4</c> is called,
 	  and if it is <c>handle_event_function</c>
 	  then <c>Module:handle_event/5</c> is called.
 	</p>
@@ -1043,13 +1054,10 @@ erlang:'!'            -----> Module:StateName/5
 	    <c>reply(Caller, Reply)</c>
 	  </seealso>.
 	</p>
-        <p><c>StateName</c> is useful in some odd cases for example
-	  if you call a common event handling function from your state
-	  function then you might want to pass <c>StateName</c>.
-	</p>
 	<p><c>PrevStateName</c> and <c>PrevState</c> are useful
 	  in some odd cases for example when you want to do something
-	  only at the first event in a state.
+	  only at the first event in a state, or when you need to
+	  handle events differently depending on the previous state.
 	  Note that when <c>gen_statem</c> enters its first state
 	  this is set to <c>undefined</c>.
 	</p>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 02c8d60c61..fe84a428f6 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -152,8 +152,7 @@
 -callback state_name(
 	    event_type(),
 	    EventContent :: term(),
-	    PrevStateName :: state_name() | reference(),
-	    StateName :: state_name(), % Current state
+	    PrevStateName :: state_name(), % Previous state name
 	    Data :: data()) ->
     state_callback_result().
 %%
@@ -164,7 +163,7 @@
 -callback handle_event(
 	    event_type(),
 	    EventContent :: term(),
-	    PrevState :: state(),
+	    PrevState :: state(), % Previous state
 	    State :: state(), % Current state
 	    Data :: data()) ->
     state_callback_result().
@@ -203,7 +202,7 @@
    [init/1, % One may use enter_loop/5,6,7 instead
     format_status/2, % Has got a default implementation
     %%
-    state_name/5, % Example for callback_mode =:= state_functions:
+    state_name/4, % Example for callback_mode =:= state_functions:
     %% there has to be a StateName/5 callback function for every StateName.
     %%
     handle_event/5]). % For callback_mode =:= handle_event_function
@@ -740,14 +739,13 @@ loop_events(
   [{Type,Content} = Event|Events] = Q, Timer) ->
     _ = (Timer =/= undefined) andalso
 	cancel_timer(Timer),
-    Func =
+    try
 	case CallbackMode of
-	    handle_event_function ->
-		handle_event;
 	    state_functions ->
-		State
-	end,
-    try Module:Func(Type, Content, PrevState, State, Data) of
+		Module:State(Type, Content, PrevState, Data);
+	    handle_event_function ->
+		Module:handle_event(Type, Content, PrevState, State, Data)
+	end of
 	Result ->
 	    loop_event_result(
 	      Parent, Debug, S, Events, Event, Result)
@@ -759,15 +757,27 @@ loop_events(
 	    %% Process an undef to check for the simple mistake
 	    %% of calling a nonexistent state function
 	    case erlang:get_stacktrace() of
-		[{Module,Func,
-		  [Type,Content,PrevState,State,Data]=Args,
+		[{Module,State,
+		  [Type,Content,PrevState,Data]=Args,
 		  _}
-		 |Stacktrace] ->
+		 |Stacktrace]
+		when CallbackMode =:= state_functions ->
 		    terminate(
 		      error,
 		      {undef_state_function,{Module,State,Args}},
 		      Stacktrace,
 		      Debug, S, Q);
+		[{Module,handle_event,
+		  [Type,Content,PrevState,State,Data]=Args,
+		  _}
+		 |Stacktrace]
+		when CallbackMode =:= handle_event_function ->
+		    terminate(
+		      error,
+		      {undef_state_function,
+		       {Module,handle_event,Args}},
+		      Stacktrace,
+		      Debug, S, Q);
 		Stacktrace ->
 		    terminate(error, undef, Stacktrace, Debug, S, Q)
 	    end;
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 81182eff71..3302171329 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1160,73 +1160,73 @@ terminate(_Reason, _State, _Data) ->
 
 %% State functions
 
-idle(cast, {connect,Pid}, _, _, Data) ->
+idle(cast, {connect,Pid}, _, Data) ->
     Pid ! accept,
     {next_state,wfor_conf,Data};
-idle({call,From}, connect, _, _, Data) ->
+idle({call,From}, connect, _, Data) ->
     gen_statem:reply(From, accept),
     {next_state,wfor_conf,Data};
-idle(cast, badreturn, _, _, _Data) ->
+idle(cast, badreturn, _, _Data) ->
     badreturn;
-idle({call,_From}, badreturn, _, _, _Data) ->
+idle({call,_From}, badreturn, _, _Data) ->
     badreturn;
-idle({call,From}, {delayed_answer,T}, _, _, Data) ->
+idle({call,From}, {delayed_answer,T}, _, Data) ->
     receive
     after T ->
 	    gen_statem:reply({reply,From,delayed}),
 	    throw({keep_state,Data})
     end;
-idle({call,From}, {timeout,Time}, _, State, _Data) ->
+idle({call,From}, {timeout,Time}, _, _Data) ->
     {next_state,timeout,{From,Time},
-     [{timeout,Time,State}]};
-idle(Type, Content, PrevState, State, Data) ->
-    case handle_common_events(Type, Content, PrevState, State, Data) of
+     [{timeout,Time,idle}]};
+idle(Type, Content, PrevState, Data) ->
+    case handle_common_events(Type, Content, idle, Data) of
 	undefined ->
 	    case Type of
 		{call,From} ->
 		    throw({keep_state,Data,[{reply,From,'eh?'}]});
 		_ ->
 		    throw(
-		      {stop,{unexpected,State,PrevState,Type,Content}})
+		      {stop,{unexpected,idle,Type,Content,PrevState}})
 	    end;
 	Result ->
 	    Result
     end.
 
-timeout(timeout, idle, idle, timeout, {From,Time}) ->
+timeout(timeout, idle, idle, {From,Time}) ->
     TRef2 = erlang:start_timer(Time, self(), ok),
     TRefC1 = erlang:start_timer(Time, self(), cancel1),
     TRefC2 = erlang:start_timer(Time, self(), cancel2),
     {next_state,timeout2,{From,Time,TRef2},
      [{cancel_timer, TRefC1},
       {next_event,internal,{cancel_timer,TRefC2}}]};
-timeout(_, _, _, State, Data) ->
-    {next_state,State,Data}.
+timeout(_, _, _, Data) ->
+    {keep_state,Data}.
 
 timeout2(
-  internal, {cancel_timer,TRefC2}, timeout, _, {From,Time,TRef2}) ->
+  internal, {cancel_timer,TRefC2}, timeout, {From,Time,TRef2}) ->
     Time4 = Time * 4,
     receive after Time4 -> ok end,
     {next_state,timeout3,{From,TRef2},
      [{cancel_timer,TRefC2}]};
-timeout2(_, _, _, State, Data) ->
-    {next_state,State,Data}.
+timeout2(_, _, _, Data) ->
+    {keep_state,Data}.
 
-timeout3(info, {timeout,TRef2,Result}, _, _, {From,TRef2}) ->
+timeout3(info, {timeout,TRef2,Result}, _, {From,TRef2}) ->
     gen_statem:reply([{reply,From,Result}]),
     {next_state,idle,state};
-timeout3(_, _, _, State, Data) ->
-    {next_state,State,Data}.
+timeout3(_, _, _, Data) ->
+    {keep_state,Data}.
 
-wfor_conf({call,From}, confirm, _, _, Data) ->
+wfor_conf({call,From}, confirm, _, Data) ->
     {next_state,connected,Data,
      [{reply,From,yes}]};
-wfor_conf(cast, {ping,_,_}, _, _, _) ->
+wfor_conf(cast, {ping,_,_}, _, _) ->
     {keep_state_and_data,[postpone]};
-wfor_conf(cast, confirm, _, _, Data) ->
+wfor_conf(cast, confirm, _, Data) ->
     {next_state,connected,Data};
-wfor_conf(Type, Content, PrevState, State, Data) ->
-    case handle_common_events(Type, Content, PrevState, State, Data) of
+wfor_conf(Type, Content, _, Data) ->
+    case handle_common_events(Type, Content, wfor_conf, Data) of
 	undefined ->
 	    case Type of
 		{call,From} ->
@@ -1239,113 +1239,113 @@ wfor_conf(Type, Content, PrevState, State, Data) ->
 	    Result
     end.
 
-connected({call,From}, {msg,Ref}, _, State, Data) ->
-    {next_state,State,Data,
+connected({call,From}, {msg,Ref}, _, Data) ->
+    {keep_state,Data,
      [{reply,From,{ack,Ref}}]};
-connected(cast, {msg,From,Ref}, _, State, Data) ->
+connected(cast, {msg,From,Ref}, _, Data) ->
     From ! {ack,Ref},
-    {next_state,State,Data};
-connected({call,From}, disconnect, _, _, Data) ->
+    {keep_state,Data};
+connected({call,From}, disconnect, _, Data) ->
     {next_state,idle,Data,
      [{reply,From,yes}]};
-connected(cast, disconnect, _, _, Data) ->
+connected(cast, disconnect, _, Data) ->
     {next_state,idle,Data};
-connected(cast, {ping,Pid,Tag}, _, State, Data) ->
+connected(cast, {ping,Pid,Tag}, _, Data) ->
     Pid ! {pong,Tag},
-    {next_state,State,Data};
-connected(Type, Content, PrevState, State, Data) ->
-    case handle_common_events(Type, Content, PrevState, State, Data) of
+    {keep_state,Data};
+connected(Type, Content, _, Data) ->
+    case handle_common_events(Type, Content, connected, Data) of
 	undefined ->
 	    case Type of
 		{call,From} ->
-		    {next_state,State,Data,
+		    {keep_state,Data,
 		     [{reply,From,'eh?'}]};
 		_ ->
-		    {next_state,State,Data}
+		    {keep_state,Data}
 	    end;
 	Result ->
 	    Result
     end.
 
-state0({call,From}, stop, _, _, Data) ->
+state0({call,From}, stop, _, Data) ->
     {stop_and_reply,normal,[{reply,From,stopped}],Data};
-state0(Type, Content, PrevState, State, Data) ->
-    case handle_common_events(Type, Content, PrevState, State, Data) of
+state0(Type, Content, _, Data) ->
+    case handle_common_events(Type, Content, state0, Data) of
 	undefined ->
-	    {next_state,State,Data};
+	    {keep_state,Data};
 	Result ->
 	    Result
     end.
 
-hiber_idle({call,From}, 'alive?', _, State, Data) ->
-    {next_state,State,Data,
+hiber_idle({call,From}, 'alive?', _, Data) ->
+    {keep_state,Data,
      [{reply,From,'alive!'}]};
-hiber_idle({call,From}, hibernate_sync, _, _, Data) ->
+hiber_idle({call,From}, hibernate_sync, _, Data) ->
     {next_state,hiber_wakeup,Data,
      [{reply,From,hibernating},
       hibernate]};
-hiber_idle(info, hibernate_later, _, State, _) ->
+hiber_idle(info, hibernate_later, _, _) ->
     Tref = erlang:start_timer(1000, self(), hibernate),
-    {next_state,State,Tref};
-hiber_idle(info, hibernate_now, _, State, Data) ->
-    {next_state,State,Data,
+    {keep_state,Tref};
+hiber_idle(info, hibernate_now, _, Data) ->
+    {keep_state,Data,
      [hibernate]};
-hiber_idle(info, {timeout,Tref,hibernate}, _, State, Tref) ->
-    {next_state,State,[],
+hiber_idle(info, {timeout,Tref,hibernate}, _, Tref) ->
+    {keep_state,[],
      [hibernate]};
-hiber_idle(cast, hibernate_async, _, _, Data) ->
+hiber_idle(cast, hibernate_async, _, Data) ->
     {next_state,hiber_wakeup,Data,
      [hibernate]};
-hiber_idle(Type, Content, PrevState, State, Data) ->
-    case handle_common_events(Type, Content, PrevState, State, Data) of
+hiber_idle(Type, Content, _, Data) ->
+    case handle_common_events(Type, Content, hiber_idle, Data) of
 	undefined ->
-	    {next_state,State,Data};
+	    {keep_state,Data};
 	Result ->
 	    Result
     end.
 
-hiber_wakeup({call,From}, wakeup_sync, _, _, Data) ->
+hiber_wakeup({call,From}, wakeup_sync, _, Data) ->
     {next_state,hiber_idle,Data,
      [{reply,From,good_morning}]};
-hiber_wakeup({call,From}, snooze_sync, _, State, Data) ->
-    {next_state,State,Data,
+hiber_wakeup({call,From}, snooze_sync, _, Data) ->
+    {keep_state,Data,
      [{reply,From,please_just_five_more},
       hibernate]};
-hiber_wakeup(cast, wakeup_async, _, _, Data) ->
+hiber_wakeup(cast, wakeup_async, _, Data) ->
     {next_state,hiber_idle,Data};
-hiber_wakeup(cast, snooze_async, _, State, Data) ->
-    {next_state,State,Data,
+hiber_wakeup(cast, snooze_async, _, Data) ->
+    {keep_state,Data,
      [hibernate]};
-hiber_wakeup(Type, Content, PrevState, State, Data) ->
-    case handle_common_events(Type, Content, PrevState, State, Data) of
+hiber_wakeup(Type, Content, _, Data) ->
+    case handle_common_events(Type, Content, hiber_wakeup, Data) of
 	undefined ->
-	    {next_state,State,Data};
+	    {keep_state,Data};
 	Result ->
 	    Result
     end.
 
 
-handle_common_events({call,From}, get, _, State, Data) ->
-    {next_state,State,Data,
+handle_common_events({call,From}, get, State, Data) ->
+    {keep_state,Data,
      [{reply,From,{state,State,Data}}]};
-handle_common_events(cast, {get,Pid}, _, State, Data) ->
+handle_common_events(cast, {get,Pid}, State, Data) ->
     Pid ! {state,State,Data},
-    {next_state,State,Data};
-handle_common_events({call,From}, stop, _, _, Data) ->
+    {keep_state,Data};
+handle_common_events({call,From}, stop, _, Data) ->
     {stop_and_reply,normal,[{reply,From,stopped}],Data};
-handle_common_events(cast, stop, _, _, _) ->
+handle_common_events(cast, stop, _, _) ->
     {stop,normal};
-handle_common_events({call,From}, {stop,Reason}, _, _, Data) ->
+handle_common_events({call,From}, {stop,Reason}, _, Data) ->
     {stop_and_reply,Reason,{reply,From,stopped},Data};
-handle_common_events(cast, {stop,Reason}, _, _, _) ->
-     {stop,Reason};
-handle_common_events({call,From}, 'alive?', _, State, Data) ->
-    {next_state,State,Data,
+handle_common_events(cast, {stop,Reason}, _, _) ->
+    {stop,Reason};
+handle_common_events({call,From}, 'alive?', _, Data) ->
+    {keep_state,Data,
      [{reply,From,yes}]};
-handle_common_events(cast, {'alive?',Pid}, _, State, Data) ->
+handle_common_events(cast, {'alive?',Pid}, _, Data) ->
     Pid ! yes,
-    {next_state,State,Data};
-handle_common_events(_, _, _, _, _) ->
+    {keep_state,Data};
+handle_common_events(_, _, _, _) ->
     undefined.
 
 %% Dispatcher to test callback_mode handle_event_function
@@ -1356,8 +1356,7 @@ handle_common_events(_, _, _, _, _) ->
 handle_event(Type, Event, PrevState, State, Data) ->
     PrevStateName = unwrap_state(PrevState),
     StateName = unwrap_state(State),
-    try ?MODULE:StateName(
-	   Type, Event, PrevStateName, StateName, Data) of
+    try ?MODULE:StateName(Type, Event, PrevStateName, Data) of
 	Result ->
 	    wrap_result(Result)
     catch
-- 
cgit v1.2.3


From 8b16506b0763d13b69aef3baeabef4729c708fe5 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 24 Feb 2016 15:50:29 +0100
Subject: Make first next_event in list arrive first

Define options as actions that set options,
rework the documentation about this.
---
 lib/stdlib/doc/src/gen_statem.xml | 298 ++++++++++++++++----------
 lib/stdlib/src/gen_statem.erl     | 439 ++++++++++++++++++++++----------------
 2 files changed, 436 insertions(+), 301 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 8934d912c6..1e41d616e9 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -143,8 +143,8 @@ erlang:'!'            -----> Module:StateName/4
     <p>The
       <seealso marker="#state_function">state function</seealso>
       can insert events using the
-      <seealso marker="#type-transition_action">
-	<c>transition_action()</c> <c>next_event</c>
+      <seealso marker="#type-action">
+	<c>action()</c> <c>next_event</c>
       </seealso>
       and such an event is inserted as the next to present
       to the state function.  That is: as if it is
@@ -158,12 +158,19 @@ erlang:'!'            -----> Module:StateName/4
     <p>Inserting an event replaces the trick of calling your own
       state handling functions that you often would have to
       resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
-      to force processing a faked event before others.
+      to force processing an inserted event before others.
       If you for example in <c>gen_statem</c> postpone an event
       in one state and then call some other state function of yours,
       you have not changed states and hence the postponed event
       will not be retried, which is logical but might be confusing.
     </p>
+    <p>
+      See the type
+      <seealso marker="#type-transition_option">
+	<c>transition_option()</c>.
+      </seealso>
+      for the details of a state transition.
+    </p>
     <p>A <c>gen_statem</c> handles system messages as documented in
        <seealso marker="sys">sys</seealso>.
        The <seealso marker="sys">sys</seealso> module
@@ -184,7 +191,7 @@ erlang:'!'            -----> Module:StateName/4
       <seealso marker="#state_function">state function</seealso> or
       <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
       specifies <c>'hibernate'</c> in the returned
-      <seealso marker="#type-transition_op"><c>Ops</c></seealso>
+      <seealso marker="#type-action"><c>Actions</c></seealso>
       list. This might be useful if the server is expected to be idle
       for a long time. However use this feature with care
       since hibernation implies at least two garbage collections
@@ -281,8 +288,8 @@ erlang:'!'            -----> Module:StateName/4
       <name name="caller" />
       <desc>
 	<p>Destination to use when replying through for example the
-	  <seealso marker="#type-transition_op">
-	    transition_op() {reply,Caller,Reply}
+	  <seealso marker="#type-action">
+	    action() {reply,Caller,Reply}
 	  </seealso>
 	  to a process that has called the <c>gen_statem</c> server using
 	  <seealso marker="#call/2">call/2</seealso>.
@@ -344,10 +351,11 @@ erlang:'!'            -----> Module:StateName/4
       <desc>
 	<p>A <c>fun()</c> of arity 2 that takes an event
 	  and returns a boolean.
-	  When used in <c>{remove_event,RemoveEventPredicate}</c> from
-	  <seealso marker="#type-transition_op">transition_op()</seealso>.
-	  The event for which the predicate returns <c>true</c> will
-	  be removed.
+	  When used in the
+	  <seealso marker="#type-action">action()</seealso>
+	  <c>{remove_event,RemoveEventPredicate}</c>,
+	  the event for which the predicate returns <c>true</c>
+	  will be removed.
 	</p>
 	<p>
 	  The predicate may <em>not</em> use a throw exception
@@ -384,40 +392,45 @@ erlang:'!'            -----> Module:StateName/4
       </desc>
     </datatype>
     <datatype>
-      <name name="transition_op" />
+      <name name="transition_option" />
       <desc>
-	<p>Either a
-	  <seealso marker="#type-transition_option">
-	    <c>transition_option()</c>
-	  </seealso> of which the last occurence
-	  in the containing list takes precedence, or a
-	  <seealso marker="#type-transition_action">
-	    <c>transition_action()</c>
-	  </seealso> performed in the order of the containing list.
-	</p>
-	<p>These may be returned from the
-	  <seealso marker="#state_function">state function</seealso>,
-	  from <seealso marker="#Module:init/1">Module:init/1</seealso>
-	  or given to
-	  <seealso marker="#enter_loop/6">enter_loop/6,7</seealso>.
+	<p>
+	  Transition options may be set by
+	  <seealso marker="#type-action">actions</seealso>
+	  and they modify how the state transition is done:
 	</p>
-	<p>The processing order for a state change is:</p>
 	<list type="ordered">
-	  <item>If the option <c>postpone</c> is <c>true</c>
-	    the current event is postponed.
+	  <item>All
+          <seealso marker="#type-action"><c>actions</c></seealso>
+	  are processed in order of appearance.
 	  </item>
-	  <item>If the state changes the queue of incoming events
-	    is reset to start with the oldest postponed.
+	  <item>
+	    If the
+            <seealso marker="#type-postpone">
+	      <c>transition_option()</c>
+	    </seealso>
+            <seealso marker="#type-postpone"><c>postpone</c></seealso>
+	    is <c>true</c> the current event is postponed.
 	  </item>
-	  <item>All actions are processed in order of appearance.
+	  <item>
+	    If the state changes the queue of incoming events
+            is reset to start with the oldest postponed.
 	  </item>
-	  <item>The <c>timeout</c> option is processed if present,
-	    so a state timer may be started or a timeout zero event
+	  <item>
+	    If the
+            <seealso marker="#type-postpone">
+	      <c>transition_option()</c>
+	    </seealso>
+            <seealso marker="#type-state_timeout">
+	      <c>timeout</c>
+	    </seealso>
+	    is set a state timer may be started or a timeout zero event
 	    may be enqueued as the newest incoming.
 	  </item>
-	  <item>The (possibly new)
-	    <seealso marker="#state_function">state function</seealso>
-	    is called with the oldest enqueued event if there is any,
+	  <item>
+	    The (possibly new)
+            <seealso marker="#state_function">state function</seealso>
+            is called with the oldest enqueued event if there is any,
 	    otherwise the <c>gen_statem</c> goes into <c>receive</c>
 	    or hibernation (if the option <c>hibernate</c> is <c>true</c>)
 	    to wait for the next message.  In hibernation the next
@@ -429,91 +442,145 @@ erlang:'!'            -----> Module:StateName/4
       </desc>
     </datatype>
     <datatype>
-      <name name="transition_option" />
+      <name name="postpone" />
+      <desc>
+	<p>
+	  If <c>true</c> postpone the current event and retry
+	  it when the state changes that is:
+	  <c>NewState =/= State</c>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="hibernate" />
+      <desc>
+	<p>
+	  If <c>true</c> hibernate the <c>gen_statem</c>
+	  by calling
+	  <seealso marker="proc_lib#hibernate/3">
+	    <c>proc_lib:hibernate/3</c>
+	  </seealso>
+	  before going into <c>receive</c>
+	  to wait for a new external event.
+	  If there are enqueued events the <c>hibernate</c>
+	  is ignored as if an event just arrived and awakened
+	  the <c>gen_statem</c>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="state_timeout" />
       <desc>
-	<p>If multiple state options of the same kind are present
-	  in the containing list these are set in the list order
-	  and the last value is kept.
+	<p>
+	  Generate an event of
+	  <seealso marker="#type-event_type">type <c>timeout</c></seealso>
+	  after this time (in milliseconds) unless some other
+	  event arrives in which case this timeout is cancelled.
+	  Note that a retried or inserted event
+	  counts just like a new in this respect.
+	  If the value is <c>infinity</c> no timer is started.
+	  If it is <c>0</c> the timeout event
+	  is immediately enqueued as the newest received.
+	  Also note that it is not possible nor needed
+	  to cancel this timeout using the
+	  <seealso marker="#type-action">
+	    <c>action() cancel_timer</c>.
+	  </seealso>
+	  since this timeout is cancelled automatically by any other event.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="action" />
+      <desc>
+	<p>These state transition actions may be invoked by
+	  returning them from the
+	  <seealso marker="#state_function">state function</seealso>,
+	  from <seealso marker="#Module:init/1">Module:init/1</seealso>
+	  or by giving them to
+	  <seealso marker="#enter_loop/6">enter_loop/6,7</seealso>.
+	</p>
+	<p>Actions are executed in the containing list order.
+	  The order matters for some actions such as <c>next_event</c>
+	  and <c>reply_action()</c>.  The order can in peculiar cases
+	  matter for <c>remove_event</c> with
+	  <c><anno>EventPredicate</anno></c> versus other
+	  event removal actions.
+	</p>
+	<p>
+	  The order also matters for actions that set
+	  <seealso marker="#type-transition_option">
+	    transition options
+	  </seealso>
+	  since setting an option overrides any previous
+	  of the same kind, so the last in the containing list wins.
 	</p>
 	<taglist>
 	  <tag><c>postpone</c></tag>
-	  <item>If <c><anno>Postpone</anno> =:= true</c>
-	    or plain <c>postpone</c> postpone the current event
-	    to be retried after a state change.
-	    This option is ignored when returned from
+	  <item>
+	    Set the
+	    <seealso marker="#type-transition_option">
+	      <c>transition_option() postpone</c>
+	    </seealso>
+	    for this state transition.
+	    This action is ignored when returned from
 	    <seealso marker="#Module:init/1">Module:init/1</seealso>
 	    or given to
 	    <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>
 	    since there is no event to postpone in those cases.
 	  </item>
 	  <tag><c>hibernate</c></tag>
-	  <item>If <c><anno>Hibernate</anno> =:= true</c>
-	    or plain <c>hibernate</c> hibernate the <c>gen_statem</c>
-	    by calling
-	    <seealso marker="proc_lib#hibernate/3">
-	      <c>proc_lib:hibernate/3</c>
-	    </seealso> before <c>receive</c> to wait for a new event.
-	    If there are enqueued events the <c>hibernate</c> action
-	    is ignored as if an event just arrived and awakened
-	    the <c>gen_statem</c>.
+	  <item>
+	    Set the
+	    <seealso marker="#type-transition_option">
+	      <c>transition_option() hibernate</c>
+	    </seealso>
+	    for this state transition.
 	  </item>
-	  <tag><c>timeout</c>
-	  </tag>
-	  <item>Generate an event of
-	    <seealso marker="#type-event_type">type <c>timeout</c></seealso>
-	    after <c><anno>Time</anno></c> milliseconds unless some other
-	    event is received before that time.  Note that a retried
-	    or inserted event counts just like a new in this respect.
-	    If <c>Time =:= infinity</c> no timer is started.
-	    If <c>Time =:= 0</c> the timeout event
-	    is immediately enqueued as the newest received.
-	    Also note that it is not possible nor needed
-	    to cancel this timeout using the
-	    <seealso marker="#type-transition_action">
-	      <c>transition_action()</c>
-	    </seealso> <c>cancel_timer</c>.
-	    This timeout is cancelled automatically by any other event.
+	  <tag><c>timeout</c></tag>
+	  <item>
+	    Set the
+	    <seealso marker="#type-transition_option">
+	      <c>transition_option() timeout</c>
+	    </seealso>
+	    to <c><anno>Time</anno></c> with the
+	    <c>EventContent</c> as <c><anno>Msg</anno></c>
+	    for the next state.
 	  </item>
-	</taglist>
-      </desc>
-    </datatype>
-    <datatype>
-      <name name="transition_action" />
-      <desc>
-	<p>The state transition actions are executed
-	  in the containing list order.  This matters
-	  for <c>next_event</c> where the last such in the list
-	  will become the next event to process by
-	  the current state function.  Regarding the other actions
-	  it is only for <c>remove_event</c> with
-	  <c><anno>EventPredicate</anno></c>
-	  and for <c>reply_action()</c> that the order may matter.
-	</p>
-	<taglist>
 	  <tag><c>reply_action()</c></tag>
 	  <item>Reply to a caller.</item>
 	  <tag><c>next_event</c></tag>
-	  <item>Insert the given <c><anno>EventType</anno></c>
+	  <item>
+	    Insert the given <c><anno>EventType</anno></c>
 	    and <c><anno>EventContent</anno></c> as the next to process.
 	    This will bypass any events in the process mailbox as well
 	    as any other queued events.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
-	    </seealso> should be used when you want to reliably distinguish
+	    </seealso>
+	    should be used when you want to reliably distinguish
 	    an event inserted this way from any external event.
+	    If there are multiple <c>next_event</c> actions
+	    in the containing list they are buffered and all are
+	    inserted so the first in the list will be the
+	    first to process.
 	  </item>
 	  <tag><c>remove_event</c></tag>
-	  <item>Remove the oldest queued event
+	  <item>
+	    Remove the oldest queued event
 	    that matches equal to <c><anno>EventType</anno></c>
 	    and <c><anno>EventContent</anno></c> or for which
-	    <c><anno>EventPredicate</anno></c> returns <c>true</c>.
+	    <c><anno>EventPredicate</anno></c>
+	    returns <c>true</c>.
 	  </item>
 	  <tag><c>cancel_timer</c></tag>
-	  <item>Cancel the timer by calling
+	  <item>
+	    Cancel the timer by calling
 	    <seealso marker="erts:erlang#cancel_timer/2">
 	      <c>erlang:cancel_timer/2</c>
-	    </seealso> with <c><anno>TimerRef</anno></c>,
+	    </seealso>
+	    with <c><anno>TimerRef</anno></c>,
 	    clean the process message queue from any late timeout message,
 	    and removes any late timeout message
 	    from the <c>gen_statem</c> event queue using
@@ -523,16 +590,20 @@ erlang:'!'            -----> Module:StateName/4
 	    the primitives mentioned above.
 	  </item>
 	  <tag><c>demonitor</c></tag>
-	  <item>Like <c>cancel_timer</c> above but for
+	  <item>
+	    Like <c>cancel_timer</c> above but for
 	    <seealso marker="erts:erlang#demonitor/2">
 	      <c>demonitor/2</c>
-	    </seealso> with <c><anno>MonitorRef</anno></c>.
+	    </seealso>
+	    with <c><anno>MonitorRef</anno></c>.
 	  </item>
 	  <tag><c>unlink</c></tag>
-	  <item>Like <c>{cancel_timer,_}</c> above but for
+	  <item>
+	    Like <c>{cancel_timer,_}</c> above but for
 	    <seealso marker="erts:erlang#unlink/1">
 	      <c>unlink/1</c>
-	    </seealso> with <c><anno>Id</anno></c>.
+	    </seealso>
+	    with <c><anno>Id</anno></c>.
 	  </item>
 	</taglist>
       </desc>
@@ -574,19 +645,19 @@ erlang:'!'            -----> Module:StateName/4
 	    <c><anno>NewState</anno></c>
 	    (which may be the same as the current state),
 	    set <c><anno>NewData</anno></c>
-	    and execute all <c><anno>Ops</anno></c>
+	    and execute all <c><anno>Actions</anno></c>
 	  </item>
 	  <tag><c>keep_state</c></tag>
 	  <item>The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    set <c><anno>NewData</anno></c>
-	    and execute all <c><anno>Ops</anno></c>
+	    and execute all <c><anno>Actions</anno></c>
 	  </item>
 	  <tag><c>keep_state_and_data</c></tag>
 	  <item>The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    keep the current server data,
-	    and execute all <c><anno>Ops</anno></c>
+	    and execute all <c><anno>Actions</anno></c>
 	  </item>
 	</taglist>
       </desc>
@@ -776,8 +847,8 @@ erlang:'!'            -----> Module:StateName/4
 	  <seealso marker="#state_function">state function</seealso>
 	  returns with
 	  <c>{reply,Caller,<anno>Reply</anno>}</c> as one
-	  <seealso marker="#type-transition_op">
-	    <c>transition_op()</c>
+	  <seealso marker="#type-action">
+	    <c>action()</c>
 	  </seealso>,
 	  and that <c><anno>Reply</anno></c> becomes the return value
 	  of this function.
@@ -870,20 +941,20 @@ erlang:'!'            -----> Module:StateName/4
       <name name="enter_loop" arity="6" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
-	<p>If <c><anno>Server_or_Ops</anno></c> is a <c>list()</c>
+	<p>If <c><anno>Server_or_Actions</anno></c> is a <c>list()</c>
 	  the same as
 	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  except that no
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
 	  </seealso> must have been registered and
-	  <c>Ops = <anno>Server_or_Ops</anno></c>.
+	  <c>Actions = <anno>Server_or_Actions</anno></c>.
 	</p>
 	<p>Otherwise the same as
 	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  with
-	  <c>Server = <anno>Server_or_Ops</anno></c> and
-	  <c>Ops = []</c>.
+	  <c>Server = <anno>Server_or_Actions</anno></c> and
+	  <c>Actions = []</c>.
 	</p>
       </desc>
     </func>
@@ -917,7 +988,7 @@ erlang:'!'            -----> Module:StateName/4
 	  </seealso> name must have been registered accordingly
 	  <em>before</em> this function is called.</p>
         <p><c><anno>CallbackMode</anno></c>, <c><anno>State</anno></c>,
-	  <c><anno>Data</anno></c> and <c><anno>Ops</anno></c>
+	  <c><anno>Data</anno></c> and <c><anno>Actions</anno></c>
 	  have the same meanings as in the return value of
           <seealso marker="#Module:init/1">Module:init/1</seealso>.
           Also, the callback module <c><anno>Module</anno></c>
@@ -952,7 +1023,7 @@ erlang:'!'            -----> Module:StateName/4
       <type>
         <v>Args = term()</v>
         <v>Result = {CallbackMode,State,Data}</v>
-	<v>&nbsp;| {CallbackMode,State,Data,Ops}</v>
+	<v>&nbsp;| {CallbackMode,State,Data,Actions}</v>
         <v>&nbsp;| {stop,Reason} | ignore</v>
 	<v>CallbackMode =
 	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
@@ -960,8 +1031,9 @@ erlang:'!'            -----> Module:StateName/4
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
 	<v>Data = <seealso marker="#type-data">data()</seealso>
 	</v>
-	<v>Ops =
-	  [<seealso marker="#type-transition_op">transition_op()</seealso>]
+	<v>Actions =
+	  [<seealso marker="#type-action">action()</seealso>] |
+	  <seealso marker="#type-action">action()</seealso>
 	</v>
 	<v>Reason = term()</v>
       </type>
@@ -978,7 +1050,7 @@ erlang:'!'            -----> Module:StateName/4
           function.</p>
         <p>If the initialization is successful, the function should
           return <c>{CallbackMode,State,Data}</c> or
-	  <c>{CallbackMode,State,Data,Ops}</c>.
+	  <c>{CallbackMode,State,Data,Actions}</c>.
 	  <c>CallbackMode</c> selects the
 	  <seealso marker="#type-callback_mode">callback_mode()</seealso>.
 	  of the <c>gen_statem</c>.
@@ -986,7 +1058,7 @@ erlang:'!'            -----> Module:StateName/4
 	  of the <c>gen_statem</c> and
 	  <c>Data</c> the server <seealso marker="#type-data">data()</seealso>
 	</p>
-	<p>The <seealso marker="#type-transition_op"><c>Ops</c></seealso>
+	<p>The <seealso marker="#type-action"><c>Actions</c></seealso>
 	  are executed when entering the first
 	  <seealso marker="#type-state">state</seealso> just as for a
 	  <seealso marker="#state_function">state function</seealso>.
@@ -1047,7 +1119,7 @@ erlang:'!'            -----> Module:StateName/4
 	  from this or from any other
 	  <seealso marker="#state_function">state function</seealso>
 	  by returning with <c>{reply,Caller,Reply}</c> in
-	  <seealso marker="#type-transition_op">Ops</seealso>, in
+	  <seealso marker="#type-action">Actions</seealso>, in
 	  <seealso marker="#type-reply_action">Replies</seealso>
 	  or by calling
 	  <seealso marker="#reply/2">
@@ -1066,7 +1138,7 @@ erlang:'!'            -----> Module:StateName/4
 	  all postponed events will be retried in the new state.
 	</p>
 	<p>See
-	  <seealso marker="#type-transition_op">transition_op()</seealso>
+	  <seealso marker="#type-action">action()</seealso>
 	  for options that can be set and actions that can be done
 	  by <c>gen_statem</c> after returning from this function.
 	</p>
@@ -1102,7 +1174,7 @@ erlang:'!'            -----> Module:StateName/4
 	  is terminating.
           If it is because another callback function has returned a
           stop tuple <c>{stop,Reason}</c> in
-	  <seealso marker="#type-transition_op">Ops</seealso>,
+	  <seealso marker="#type-action">Actions</seealso>,
 	  <c>Reason</c> will have the value specified in that tuple.
 	  If it is due to a failure, <c>Reason</c> is the error reason.
 	</p>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index fe84a428f6..7fbc1e0f0d 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -45,7 +45,7 @@
    [wakeup_from_hibernate/3]).
 
 %% Fix problem for doc build
--export_type([state_callback_result/0]).
+-export_type([transition_option/0,state_callback_result/0]).
 
 %%%==========================================================================
 %%% Interface functions.
@@ -53,47 +53,77 @@
 
 -type caller() ::
 	{To :: pid(), Tag :: term()}. % Reply-to specifier for call
+
 -type state() ::
 	state_name() | % For state callback function StateName/5
 	term(). % For state callback function handle_event/5
+
 -type state_name() :: atom().
+
 -type data() :: term().
+
 -type event_type() ::
 	{'call',Caller :: caller()} | 'cast' |
 	'info' | 'timeout' | 'internal'.
+
 -type event_predicate() :: % Return true for the event in question
 	fun((event_type(), term()) -> boolean()).
+
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
--type transition_op() ::
-	%% First NewState and NewData are set,
-	%% then all transition_action()s are executed in order of
-	%% apperance. Postponing the current event is performed
-	%% (iff transition_option() 'postpone' is 'true').
-	%% Lastly pending events are processed or if there are
-	%% no pending events the server goes into receive
-	%% or hibernate (iff transition_option() 'hibernate' is 'true')
-	transition_option() | transition_action().
+
 -type transition_option() ::
-	%% The last of each kind in the transition_op()
-	%% list takes precedence
-	'postpone' |  % Postpone the current event to a different (=/=) state
-	{'postpone', Postpone :: boolean()} |
-	'hibernate' | % Hibernate the server instead of going into receive
-	{'hibernate', Hibernate :: boolean()} |
-	(Timeout :: timeout()) | % {timeout,Timeout}
-	{'timeout', % Generate a ('timeout', Msg, ...) event after Time
-	 Time :: timeout(), Msg :: term()}.
--type transition_action() ::
-	%% These can occur multiple times and are executed in order
-	%% of appearence in the transition_op() list
+	postpone() | hibernate() | state_timeout().
+-type postpone() ::
+	%% If 'true' postpone the current event
+	%% and retry it when the state changes (=/=)
+	boolean().
+-type hibernate() ::
+	%% If 'true' hibernate the server instead of going into receive
+	boolean().
+-type state_timeout() ::
+	%% Generate a ('timeout', Msg, ...) event after Time
+	%% unless some other event is delivered
+	Time :: timeout().
+
+-type action() ::
+	%% During a state change:
+	%% * NewState and NewData are set.
+	%% * All action()s are executed in order of apperance.
+	%% * Postponing the current event is performed
+	%%   iff 'postpone' is 'true'.
+	%% * A state timer is started iff 'timeout' is set.
+	%% * Pending events are processed or if there are
+	%%   no pending events the server goes into receive
+	%%   or hibernate (iff 'hibernate' is 'true')
+	%%
+	%% These action()s are executed in order of appearence
+	%% in the containing list. The ones that set options
+	%% will override any previous so the last of each kind wins.
+	%%
+	'postpone' |  % Set the postpone option
+	{'postpone', Postpone :: postpone()} |
+	%%
+	'hibernate' | % Set the hibernate option
+	{'hibernate', Hibernate :: hibernate()} |
+	%%
+	(Timeout :: state_timeout()) | % {timeout,Timeout}
+	{'timeout', % Set the timeout option
+	 Time :: state_timeout(), Msg :: term()} |
+	%%
 	reply_action() |
+	%%
+	%% All 'next_event' events are kept in a list and then
+	%% inserted at state changes so the first in the
+	%% action() list is the first to be delivered.
 	{'next_event', % Insert event as the next to handle
 	 EventType :: event_type(),
 	 EventContent :: term()} |
+	%%
 	{'remove_event', % Remove the oldest matching (=:=) event
 	 EventType :: event_type(), EventContent :: term()} |
 	{'remove_event', % Remove the oldest event satisfying predicate
 	 EventPredicate :: event_predicate()} |
+	%%
 	{'cancel_timer', % Cancel timer and clean up mess(ages)
 	 TimerRef :: reference()} |
 	{'demonitor', % Demonitor and clean up mess(ages)
@@ -103,6 +133,7 @@
 -type reply_action() ::
 	{'reply', % Reply to a caller
 	 Caller :: caller(), Reply :: term()}.
+
 -type state_callback_result() ::
     {'stop', % Stop the server
      Reason :: term()} |
@@ -122,15 +153,16 @@
     {'next_state', % State transition, maybe to the same state
      NewState :: state(),
      NewData :: data(),
-     Ops :: [transition_op()] | transition_op()} |
+     Actions :: [action()] | action()} |
     {'keep_state', % {keep_state,NewData,[]}
      NewData :: data()} |
     {'keep_state',
      NewData :: data(),
-     Ops :: [transition_op()] | transition_op()} |
+     Actions :: [action()] | action()} |
     {'keep_state_and_data'} | % {keep_state_and_data,[]}
     {'keep_state_and_data',
-     Ops :: [transition_op()] | transition_op()}.
+     Actions :: [action()] | action()}.
+
 
 %% The state machine init function.  It is called only once and
 %% the server is not running until this function has returned
@@ -138,7 +170,7 @@
 %% for all events to this server.
 -callback init(Args :: term()) ->
     {callback_mode(), state(), data()} |
-    {callback_mode(), state(), data(), [transition_op()]} |
+    {callback_mode(), state(), data(), [action()] | action()} |
     'ignore' |
     {'stop', Reason :: term()}.
 
@@ -434,19 +466,19 @@ enter_loop(Module, Opts, CallbackMode, State, Data) ->
 	Module :: module(), Opts :: [debug_opt()],
 	CallbackMode :: callback_mode(),
 	State :: state(), Data :: data(),
-	Server_or_Ops ::
-	  server_name() | pid() | [transition_op()]) ->
+	Server_or_Actions ::
+	  server_name() | pid() | [action()]) ->
 			no_return().
-enter_loop(Module, Opts, CallbackMode, State, Data, Server_or_Ops) ->
+enter_loop(Module, Opts, CallbackMode, State, Data, Server_or_Actions) ->
     if
-	is_list(Server_or_Ops) ->
+	is_list(Server_or_Actions) ->
 	    enter_loop(
 	      Module, Opts, CallbackMode, State, Data,
-	      self(), Server_or_Ops);
+	      self(), Server_or_Actions);
 	true ->
 	    enter_loop(
 	      Module, Opts, CallbackMode, State, Data,
-	      Server_or_Ops, [])
+	      Server_or_Actions, [])
     end.
 %%
 -spec enter_loop(
@@ -454,11 +486,11 @@ enter_loop(Module, Opts, CallbackMode, State, Data, Server_or_Ops) ->
 	CallbackMode :: callback_mode(),
 	State :: state(), Data :: data(),
 	Server :: server_name() | pid(),
-	Ops :: [transition_op()]) ->
+	Actions :: [action()] | action()) ->
 			no_return().
-enter_loop(Module, Opts, CallbackMode, State, Data, Server, Ops) ->
+enter_loop(Module, Opts, CallbackMode, State, Data, Server, Actions) ->
     Parent = gen:get_parent(),
-    enter(Module, Opts, CallbackMode, State, Data, Server, Ops, Parent).
+    enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent).
 
 %%---------------------------------------------------------------------------
 %% API helpers
@@ -480,32 +512,38 @@ do_send(Proc, Msg) ->
     end.
 
 %% Here init_it/6 and enter_loop/5,6,7 functions converge
-enter(Module, Opts, CallbackMode, State, Data, Server, Ops, Parent)
+enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent)
   when is_atom(Module), is_pid(Parent) ->
     case callback_mode(CallbackMode) of
 	true ->
 	    Name = gen:get_proc_name(Server),
 	    Debug = gen:debug_options(Name, Opts),
 	    PrevState = undefined,
+	    NewActions =
+		if
+		    is_list(Actions) ->
+			Actions ++ [{postpone,false}];
+		    true ->
+			[Actions,{postpone,false}]
+		end,
 	    S =	#{
 	      callback_mode => CallbackMode,
 	      module => Module,
 	      name => Name,
 	      prev_state => PrevState,
-	      state => PrevState, % Discarded by loop_event_transition_ops
+	      state => PrevState, % Discarded by loop_event_actions
 	      data => Data,
 	      timer => undefined,
 	      postponed => [],
 	      hibernate => false},
-	    loop_event_transition_ops(
+	    loop_event_actions(
 	      Parent, Debug, S, [],
 	      {event,undefined}, % Discarded due to {postpone,false}
-	      PrevState, State, Data,
-	      Ops++[{postpone,false}]);
+	      PrevState, State, Data, NewActions);
 	false ->
 	    erlang:error(
 	      badarg,
-	      [Module,Opts,CallbackMode,State,Data,Server,Ops,Parent])
+	      [Module,Opts,CallbackMode,State,Data,Server,Actions,Parent])
     end.
 
 %%%==========================================================================
@@ -536,11 +574,11 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
 	    enter(
 	      Module, Opts, CallbackMode, State, Data,
 	      ServerRef, [], Parent);
-	{CallbackMode,State,Data,Ops} ->
+	{CallbackMode,State,Data,Actions} ->
 	    proc_lib:init_ack(Starter, {ok,self()}),
 	    enter(
 	      Module, Opts, CallbackMode, State, Data,
-	      ServerRef, Ops, Parent);
+	      ServerRef, Actions, Parent);
 	{stop,Reason} ->
 	    gen:unregister_name(ServerRef),
 	    proc_lib:init_ack(Starter, {error,Reason}),
@@ -814,183 +852,209 @@ loop_event_result(
 	    %% Since we got back here Replies was bad
 	    terminate(Class, NewReason, Stacktrace, NewDebug, NewS, Q);
 	{next_state,NewState,NewData} ->
-	    loop_event_transition_ops(
+	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, []);
-	{next_state,NewState,NewData,Ops}
-	  when is_list(Ops) ->
-	    loop_event_transition_ops(
+	{next_state,NewState,NewData,Actions}
+	  when is_list(Actions) ->
+	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Ops);
+	      State, NewState, NewData, Actions);
 	{keep_state,NewData} ->
-	    loop_event_transition_ops(
+	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, State, NewData, []);
-	{keep_state,NewData,Ops} ->
-	    loop_event_transition_ops(
+	{keep_state,NewData,Actions} ->
+	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, State, NewData, Ops);
+	      State, State, NewData, Actions);
 	{keep_state_and_data} ->
-	    loop_event_transition_ops(
+	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, State, Data, []);
-	{keep_state_and_data,Ops} ->
-	    loop_event_transition_ops(
+	{keep_state_and_data,Actions} ->
+	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, State, Data, Ops);
+	      State, State, Data, Actions);
 	_ ->
 	    ?TERMINATE(
 	      error, {bad_return_value,Result}, Debug, S, [Event|Events])
     end.
 
-loop_event_transition_ops(
-  Parent, Debug0, #{postponed := P0} = S, Events, Event,
-  State, NewState, NewData, Ops) ->
-    case collect_transition_options(Ops) of
-	{Postpone,Hibernate,Timeout,Actions} ->
-	    P1 = % Move current event to postponed if Postpone
-		case Postpone of
-		    true ->
-			[Event|P0];
-		    false ->
-			P0
-		end,
-	    {Q2,P2} = % Move all postponed events to queue if state change
-		if
-		    NewState =:= State ->
-			{Events,P1};
-		    true ->
-			{lists:reverse(P1, Events),[]}
-		end,
-	    %%
-	    case process_transition_actions(
-		   Actions, Debug0, S, Q2, P2) of
-		{Debug,Q3,P} ->
-		    NewDebug =
-			sys_debug(
-			  Debug, S,
-			  case Postpone of
-			      true ->
-				  {postpone,Event,NewState};
-			      false ->
-				  {consume,Event,NewState}
-			  end),
-		    {Timer,Q} =
-			case Timeout of
-			    undefined ->
-				{undefined,Q3};
-			    {timeout,0,Msg} ->
-				%% Pretend the timeout has just been received
-				{undefined,Q3 ++ [{timeout,Msg}]};
-			    {timeout,Time,Msg} ->
-				{erlang:start_timer(Time, self(), Msg),
-				 Q3}
-			end,
-		    loop_events(
-		      Parent, NewDebug,
-		      S#{
-			prev_state := State,
-			state := NewState,
-			data := NewData,
-			timer := Timer,
-			hibernate := Hibernate,
-			postponed := P},
-		      Q, Timer);
-		[Class,Reason,Stacktrace,Debug] ->
-		    terminate(
-		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
-	    end;
-	%%
-	[Class,Reason,Stacktrace] ->
-	    terminate(
-	      Class, Reason, Stacktrace, Debug0, S, [Event|Events])
-    end.
-
-%%---------------------------------------------------------------------------
-%% Server helpers
-
-collect_transition_options(Ops) ->
-    if
-	is_list(Ops) ->
-	    collect_transition_options(
-	      Ops, false, false, undefined, []);
-	true ->
-	    collect_transition_options(
-	      [Ops], false, false, undefined, [])
-    end.
-%% Keep the last of each kind
-collect_transition_options(
-  [], Postpone, Hibernate, Timeout, Actions) ->
-    {Postpone,Hibernate,Timeout,lists:reverse(Actions)};
-collect_transition_options(
-  [Op|Ops] = AllOps, Postpone, Hibernate, Timeout, Actions) ->
-    case Op of
+loop_event_actions(
+  Parent, Debug, S, Events, Event, State, NewState, NewData, Actions) ->
+    loop_event_actions(
+      Parent, Debug, S, Events, Event, State, NewState, NewData,
+      false, false, undefined, [], Actions).
+%%
+loop_event_actions(
+  Parent, Debug, #{postponed := P0} = S, Events, Event,
+  State, NewState, NewData,
+  Postpone, Hibernate, Timeout, NextEvents, []) ->
+    P1 = % Move current event to postponed if Postpone
+	case Postpone of
+	    true ->
+		[Event|P0];
+	    false ->
+		P0
+	end,
+    {Timer,Q1} =
+	case Timeout of
+	    undefined ->
+		{undefined,Events};
+	    {timeout,0,Msg} ->
+		%% Pretend the timeout has just been received
+		{undefined,Events ++ [{timeout,Msg}]};
+	    {timeout,Time,Msg} ->
+		{erlang:start_timer(Time, self(), Msg),
+		Events}
+	end,
+    {Q2,P} = % Move all postponed events to queue if state change
+	if
+	    NewState =:= State ->
+		{Q1,P1};
+	    true ->
+		{lists:reverse(P1, Q1),[]}
+	end,
+    %% Place next events first in queue
+    Q = lists:reverse(NextEvents, Q2),
+    %%
+    NewDebug =
+	sys_debug(
+	  Debug, S,
+	  case Postpone of
+	      true ->
+		  {postpone,Event,NewState};
+	      false ->
+		  {consume,Event,NewState}
+	  end),
+    %% Loop to top; process next event
+    loop_events(
+      Parent, NewDebug,
+      S#{
+	prev_state := State,
+	state := NewState,
+	data := NewData,
+	timer := Timer,
+	hibernate := Hibernate,
+	postponed := P},
+      Q, Timer);
+loop_event_actions(
+  Parent, Debug, S, Events, Event, State, NewState, NewData,
+  Postpone, Hibernate, Timeout, NextEvents, [Action|Actions]) ->
+    case Action of
+	%% Set options
 	postpone ->
-	    collect_transition_options(
-	      Ops, true, Hibernate, Timeout, Actions);
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NewState, NewData,
+	      true, Hibernate, Timeout, NextEvents, Actions);
 	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
-	    collect_transition_options(
-	      Ops, NewPostpone, Hibernate, Timeout, Actions);
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NewState, NewData,
+	      NewPostpone, Hibernate, Timeout, NextEvents, Actions);
 	{postpone,_} ->
-	    [error,{bad_ops,AllOps},?STACKTRACE()];
+	    ?TERMINATE(
+	       error, {bad_action,Action}, Debug, S, [Event|Events]);
 	hibernate ->
-	    collect_transition_options(
-	      Ops, Postpone, true, Timeout, Actions);
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NewState, NewData,
+	      Postpone, true, Timeout, NextEvents, Actions);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
-	    collect_transition_options(
-	      Ops, Postpone, NewHibernate, Timeout, Actions);
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NewState, NewData,
+	      Postpone, NewHibernate, Timeout, NextEvents, Actions);
 	{hibernate,_} ->
-	    [error,{bad_ops,AllOps},?STACKTRACE()];
-	{timeout,infinity,_} -> % Ignore since it will never time out
-	    collect_transition_options(
-	      Ops, Postpone, Hibernate, undefined, Actions);
+	    ?TERMINATE(
+	       error, {bad_action,Action}, Debug, S, [Event|Events]);
+	{timeout,infinity,_} -> % Clear timer - it will never trigger
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NewState, NewData,
+	      Postpone, Hibernate, undefined, NextEvents, Actions);
 	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
-	    collect_transition_options(
-	      Ops, Postpone, Hibernate, NewTimeout, Actions);
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NewState, NewData,
+	      Postpone, Hibernate, NewTimeout, NextEvents, Actions);
 	{timeout,_,_} ->
-	    [error,{bad_ops,AllOps},?STACKTRACE()];
-	_ -> % Collect others as actions
-	    collect_transition_options(
-	      Ops, Postpone, Hibernate, Timeout, [Op|Actions])
-    end.
-
-process_transition_actions([], Debug, _S, Q, P) ->
-    {Debug,Q,P};
-process_transition_actions(
-  [Action|Actions] = AllActions, Debug, S, Q, P) ->
-    case Action of
-	{reply,{_To,_Tag}=Caller,Reply} ->
-	    NewDebug = do_reply(Debug, S, Caller, Reply),
-	    process_transition_actions(Actions, NewDebug, S, Q, P);
+	    ?TERMINATE(
+	       error, {bad_action,Action}, Debug, S, [Event|Events]);
+	%% Actual actions
+	{reply,Caller,Reply} ->
+	    case caller(Caller) of
+		true ->
+		    NewDebug = do_reply(Debug, S, Caller, Reply),
+		    loop_event_actions(
+		      Parent, NewDebug, S, Events, Event,
+		      State, NewState, NewData,
+		      Postpone, Hibernate, Timeout, NextEvents, Actions);
+		false ->
+		    ?TERMINATE(
+		       error, {bad_action,Action}, Debug, S, [Event|Events])
+	    end;
 	{next_event,Type,Content} ->
 	    case event_type(Type) of
 		true ->
-		    process_transition_actions(
-		      Actions, Debug, S, [{Type,Content}|Q], P);
+		    loop_event_actions(
+		      Parent, Debug, S, Events, Event,
+		      State, NewState, NewData,
+		      Postpone, Hibernate, Timeout,
+		      [{Type,Content}|NextEvents], Actions);
 		false ->
-		    [error,{bad_ops,AllActions},?STACKTRACE(),Debug]
+		    ?TERMINATE(
+		       error, {bad_action,Action}, Debug, S, [Event|Events])
 	    end;
 	_ ->
 	    %% All others are remove actions
 	    case remove_fun(Action) of
 		false ->
-		    process_transition_actions(
-		      Actions, Debug, S, Q, P);
+		    loop_event_actions(
+		      Parent, Debug, S, Events, Event,
+		      State, NewState, NewData,
+		      Postpone, Hibernate, Timeout, NextEvents, Actions);
 		undefined ->
-		    [error,{bad_ops,AllActions},?STACKTRACE(),Debug];
+		    ?TERMINATE(
+		       error, {bad_action,Action}, Debug, S, [Event|Events]);
 		RemoveFun when is_function(RemoveFun, 2) ->
-		    case remove_event(RemoveFun, Q, P) of
-			{NewQ,NewP} ->
-			    process_transition_actions(
-			      Actions, Debug, S, NewQ, NewP);
-			Error ->
-			    Error ++ [Debug]
+		    #{postponed := P} = S,
+		    case remove_event(RemoveFun, Events, P) of
+			false ->
+			    loop_event_actions(
+			      Parent, Debug, S, Events, Event,
+			      State, NewState, NewData,
+			      Postpone, Hibernate, Timeout, NextEvents,
+			      Actions);
+			{NewEvents,false} ->
+			    loop_event_actions(
+			      Parent, Debug, S, NewEvents, Event,
+			      State, NewState, NewData,
+			      Postpone, Hibernate, Timeout, NextEvents,
+			      Actions);
+			{false,NewP} ->
+			    NewS = S#{postponed := NewP},
+			    loop_event_actions(
+			      Parent, Debug, NewS, Events, Event,
+			      State, NewState, NewData,
+			      Postpone, Hibernate, Timeout, NextEvents,
+			      Actions);
+			[Class,Reason,Stacktrace] ->
+			    terminate(
+			      Class, Reason, Stacktrace,
+			      Debug, S, [Event|Events])
 		    end;
-		Error ->
-		    Error ++ [Debug]
+		[Class,Reason,Stacktrace] ->
+		    terminate(
+		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
 	    end
     end.
 
+%%---------------------------------------------------------------------------
+%% Server helpers
+
 reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, Replies) ->
     if
 	is_list(Replies) ->
@@ -1004,14 +1068,14 @@ reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, Replies) ->
 do_reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
     terminate(Class, Reason, Stacktrace, Debug, S, Q);
 do_reply_then_terminate(
-  Class, Reason, Stacktrace, Debug, S, Q, [R|Rs] = Replies) ->
+  Class, Reason, Stacktrace, Debug, S, Q, [R|Rs]) ->
     case R of
 	{reply,{_To,_Tag}=Caller,Reply} ->
 	    NewDebug = do_reply(Debug, S, Caller, Reply),
 	    do_reply_then_terminate(
 	      Class, Reason, Stacktrace, NewDebug, S, Q, Rs);
 	_ ->
-	    [error,{bad_replies,Replies},?STACKTRACE(),Debug]
+	    [error,{bad_action,R},?STACKTRACE(),Debug]
     end.
 
 do_reply(Debug, S, Caller, Reply) ->
@@ -1026,20 +1090,19 @@ remove_event(RemoveFun, Q, P) ->
 	    false ->
 		case remove_head_event(RemoveFun, Q) of
 		    false ->
-			{P,Q};
+			false;
 		    NewQ ->
-			{P,NewQ}
+			{false,NewQ}
 		end;
 	    NewP ->
-		{NewP,Q}
+		{NewP,false}
 	end
     catch
 	Class:Reason ->
 	    [Class,Reason,erlang:get_stacktrace()]
     end.
 
-%% Do the given transition action and create
-%% an event removal predicate fun()
+%% Do the given action and create an event removal predicate fun()
 remove_fun({remove_event,Type,Content}) ->
     fun (T, C) when T =:= Type, C =:= Content -> true;
 	(_, _) -> false
-- 
cgit v1.2.3


From 14028aee428c135211e33df77c1bee2fdc128f6e Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 24 Feb 2016 16:36:24 +0100
Subject: Ditch PrevState

StateName/4 -> StateName/3
handle_event/5 -> handle_event/4
---
 lib/stdlib/doc/src/gen_statem.xml    | 70 +++++++++++--------------------
 lib/stdlib/src/gen_statem.erl        | 23 ++++------
 lib/stdlib/test/gen_statem_SUITE.erl | 81 ++++++++++++++++++------------------
 3 files changed, 73 insertions(+), 101 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 1e41d616e9..f21610d14c 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -62,12 +62,12 @@ gen_statem:stop       -----> Module:terminate/2
 gen_statem:call
 gen_statem:cast
 erlang:send
-erlang:'!'            -----> Module:StateName/4
-                             Module:handle_event/5
+erlang:'!'            -----> Module:StateName/3
+                             Module:handle_event/4
 
 -                     -----> Module:terminate/3
 
--                     -----> Module:code_change/3</pre>
+-                     -----> Module:code_change/4</pre>
     <p>Events are of different
       <seealso marker="#type-event_type">types</seealso>
       so the callback functions can know the origin of an event
@@ -91,28 +91,22 @@ erlang:'!'            -----> Module:StateName/4
       is <c>state_functions</c> the state has to be an atom and
       is used as the state function name.
       See
-      <seealso marker="#Module:StateName/4">
-        <c>Module:StateName/4</c>
+      <seealso marker="#Module:StateName/3">
+        <c>Module:StateName/3</c>
       </seealso>.
       This gathers all code for a specific state
       in one function and hence dispatches on state first.
       Note that in this mode the callback function
-      <seealso marker="#Module:code_change/4">
-        <c>Module:code_change/4</c>
-      </seealso> makes the state name <c>code_change</c>
-      unusable.  Actually you might get away with using it
-      as a state name but you will have to find a way to separate
-      the two callback roles e.g by observing that you can force
-      argument 3 into having different types for the different roles.
-      This is a slippery slope, though.  It is easier
-      to simply not use <c>code_change</c> as a state name.
+      <seealso marker="#Module:terminate/3">
+        <c>Module:terminate/3</c>
+      </seealso> makes the state name <c>terminate</c> unusable.
     </p>
     <p>When
       <seealso marker="#type-callback_mode">callback_mode</seealso>
       is <c>handle_event_function</c> the state can be any term
       and the state function name is
-      <seealso marker="#Module:handle_event/5">
-        <c>Module:handle_event/5</c>
+      <seealso marker="#Module:handle_event/4">
+        <c>Module:handle_event/4</c>
       </seealso>.
       This makes it easy to dispatch on state or on event as
       you like but you will have to implement it.
@@ -120,12 +114,6 @@ erlang:'!'            -----> Module:StateName/4
       states so you do not accidentally postpone one event
       forever creating an infinite busy loop.
     </p>
-    <p>There is a small gotcha in both callback modes regarding
-      the state <c>undefined</c> that is used as the previous state
-      when the first state function is called.  So either do not
-      use <c>undefined</c> as a state, or figure out
-      the implications yourself.
-    </p>
     <p>The <c>gen_statem</c> enqueues incoming events in order of arrival
       and presents these to the
       <seealso marker="#state_function">state function</seealso>
@@ -378,14 +366,14 @@ erlang:'!'            -----> Module:StateName/4
 	  <item>The state has to be of type
 	    <seealso marker="#type-state_name"><c>state_name()</c></seealso>
 	    and one callback function per state that is
-	    <seealso marker="#Module:StateName/4">
-	      <c>Module:StateName/4</c>
-	    </seealso> is used.  This is the default.
+	    <seealso marker="#Module:StateName/3">
+	      <c>Module:StateName/3</c>
+	    </seealso> is used.
 	  </item>
 	  <tag><c>handle_event_function</c></tag>
 	  <item>The state can be any term and the callback function
-	    <seealso marker="#Module:handle_event/5">
-	      <c>Module:handle_event/5</c>
+	    <seealso marker="#Module:handle_event/4">
+	      <c>Module:handle_event/4</c>
 	    </seealso> is used for all states.
 	  </item>
 	</taglist>
@@ -1054,9 +1042,10 @@ erlang:'!'            -----> Module:StateName/4
 	  <c>CallbackMode</c> selects the
 	  <seealso marker="#type-callback_mode">callback_mode()</seealso>.
 	  of the <c>gen_statem</c>.
-	  <c>State</c> is the <seealso marker="#type-state">state()</seealso>
-	  of the <c>gen_statem</c> and
-	  <c>Data</c> the server <seealso marker="#type-data">data()</seealso>
+	  <c>State</c> is the initial
+	  <seealso marker="#type-state">state()</seealso>
+	  and <c>Data</c> the initial server
+	  <seealso marker="#type-data">data()</seealso>
 	</p>
 	<p>The <seealso marker="#type-action"><c>Actions</c></seealso>
 	  are executed when entering the first
@@ -1076,11 +1065,10 @@ erlang:'!'            -----> Module:StateName/4
     </func>
 
     <func>
-      <name>Module:StateName(EventType, EventContent,
-      PrevStateName, Data) -> Result
+      <name>Module:StateName(EventType, EventContent, Data) -> Result
       </name>
       <name>Module:handle_event(EventType, EventContent,
-        PrevState, State, Data) -> Result
+      State, Data) -> Result
       </name>
       <fsummary>Handle an event</fsummary>
       <type>
@@ -1088,10 +1076,7 @@ erlang:'!'            -----> Module:StateName/4
 	  <seealso marker="#type-event_type">event_type()</seealso>
 	</v>
 	<v>EventContent = term()</v>
-	<v>PrevStateName =
-	  <seealso marker="#type-state_name">state_name()</seealso>
-	</v>
-	<v>PrevState = State =
+	<v>State = NewState =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
 	<v>Data = NewData =
@@ -1109,9 +1094,9 @@ erlang:'!'            -----> Module:StateName/4
           <seealso marker="#cast/2">cast/2</seealso> or
 	  as a normal process message one of these functions is called.
 	  If <seealso marker="#type-callback_mode">callback_mode</seealso>
-	  is <c>state_functions</c> then <c>Module:StateName/4</c> is called,
+	  is <c>state_functions</c> then <c>Module:StateName/3</c> is called,
 	  and if it is <c>handle_event_function</c>
-	  then <c>Module:handle_event/5</c> is called.
+	  then <c>Module:handle_event/4</c> is called.
 	</p>
 	<p>If <c>EventType</c> is
 	  <seealso marker="#type-event_type"><c>{call,Caller}</c></seealso>
@@ -1126,13 +1111,6 @@ erlang:'!'            -----> Module:StateName/4
 	    <c>reply(Caller, Reply)</c>
 	  </seealso>.
 	</p>
-	<p><c>PrevStateName</c> and <c>PrevState</c> are useful
-	  in some odd cases for example when you want to do something
-	  only at the first event in a state, or when you need to
-	  handle events differently depending on the previous state.
-	  Note that when <c>gen_statem</c> enters its first state
-	  this is set to <c>undefined</c>.
-	</p>
 	<p>If this function returns with a new state that
 	  does not match equal (<c>=/=</c>) to the current state
 	  all postponed events will be retried in the new state.
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 7fbc1e0f0d..c844b76653 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -184,7 +184,6 @@
 -callback state_name(
 	    event_type(),
 	    EventContent :: term(),
-	    PrevStateName :: state_name(), % Previous state name
 	    Data :: data()) ->
     state_callback_result().
 %%
@@ -195,7 +194,6 @@
 -callback handle_event(
 	    event_type(),
 	    EventContent :: term(),
-	    PrevState :: state(), % Previous state
 	    State :: state(), % Current state
 	    Data :: data()) ->
     state_callback_result().
@@ -234,10 +232,10 @@
    [init/1, % One may use enter_loop/5,6,7 instead
     format_status/2, % Has got a default implementation
     %%
-    state_name/4, % Example for callback_mode =:= state_functions:
+    state_name/3, % Example for callback_mode =:= state_functions:
     %% there has to be a StateName/5 callback function for every StateName.
     %%
-    handle_event/5]). % For callback_mode =:= handle_event_function
+    handle_event/4]). % For callback_mode =:= handle_event_function
 
 %% Type validation functions
 callback_mode(CallbackMode) ->
@@ -518,7 +516,7 @@ enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent)
 	true ->
 	    Name = gen:get_proc_name(Server),
 	    Debug = gen:debug_options(Name, Opts),
-	    PrevState = undefined,
+	    OldState = make_ref(),
 	    NewActions =
 		if
 		    is_list(Actions) ->
@@ -530,8 +528,7 @@ enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent)
 	      callback_mode => CallbackMode,
 	      module => Module,
 	      name => Name,
-	      prev_state => PrevState,
-	      state => PrevState, % Discarded by loop_event_actions
+	      state => OldState, % Discarded by loop_event_actions
 	      data => Data,
 	      timer => undefined,
 	      postponed => [],
@@ -539,7 +536,7 @@ enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent)
 	    loop_event_actions(
 	      Parent, Debug, S, [],
 	      {event,undefined}, % Discarded due to {postpone,false}
-	      PrevState, State, Data, NewActions);
+	      OldState, State, Data, NewActions);
 	false ->
 	    erlang:error(
 	      badarg,
@@ -771,7 +768,6 @@ loop_events(
   Parent, Debug,
   #{callback_mode := CallbackMode,
     module := Module,
-    prev_state := PrevState,
     state := State,
     data := Data} = S,
   [{Type,Content} = Event|Events] = Q, Timer) ->
@@ -780,9 +776,9 @@ loop_events(
     try
 	case CallbackMode of
 	    state_functions ->
-		Module:State(Type, Content, PrevState, Data);
+		Module:State(Type, Content, Data);
 	    handle_event_function ->
-		Module:handle_event(Type, Content, PrevState, State, Data)
+		Module:handle_event(Type, Content, State, Data)
 	end of
 	Result ->
 	    loop_event_result(
@@ -796,7 +792,7 @@ loop_events(
 	    %% of calling a nonexistent state function
 	    case erlang:get_stacktrace() of
 		[{Module,State,
-		  [Type,Content,PrevState,Data]=Args,
+		  [Type,Content,Data]=Args,
 		  _}
 		 |Stacktrace]
 		when CallbackMode =:= state_functions ->
@@ -806,7 +802,7 @@ loop_events(
 		      Stacktrace,
 		      Debug, S, Q);
 		[{Module,handle_event,
-		  [Type,Content,PrevState,State,Data]=Args,
+		  [Type,Content,State,Data]=Args,
 		  _}
 		 |Stacktrace]
 		when CallbackMode =:= handle_event_function ->
@@ -932,7 +928,6 @@ loop_event_actions(
     loop_events(
       Parent, NewDebug,
       S#{
-	prev_state := State,
 	state := NewState,
 	data := NewData,
 	timer := Timer,
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 3302171329..27b042c0d8 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1160,26 +1160,26 @@ terminate(_Reason, _State, _Data) ->
 
 %% State functions
 
-idle(cast, {connect,Pid}, _, Data) ->
+idle(cast, {connect,Pid}, Data) ->
     Pid ! accept,
     {next_state,wfor_conf,Data};
-idle({call,From}, connect, _, Data) ->
+idle({call,From}, connect, Data) ->
     gen_statem:reply(From, accept),
     {next_state,wfor_conf,Data};
-idle(cast, badreturn, _, _Data) ->
+idle(cast, badreturn, _Data) ->
     badreturn;
-idle({call,_From}, badreturn, _, _Data) ->
+idle({call,_From}, badreturn, _Data) ->
     badreturn;
-idle({call,From}, {delayed_answer,T}, _, Data) ->
+idle({call,From}, {delayed_answer,T}, Data) ->
     receive
     after T ->
 	    gen_statem:reply({reply,From,delayed}),
 	    throw({keep_state,Data})
     end;
-idle({call,From}, {timeout,Time}, _, _Data) ->
+idle({call,From}, {timeout,Time}, _Data) ->
     {next_state,timeout,{From,Time},
      [{timeout,Time,idle}]};
-idle(Type, Content, PrevState, Data) ->
+idle(Type, Content, Data) ->
     case handle_common_events(Type, Content, idle, Data) of
 	undefined ->
 	    case Type of
@@ -1187,45 +1187,45 @@ idle(Type, Content, PrevState, Data) ->
 		    throw({keep_state,Data,[{reply,From,'eh?'}]});
 		_ ->
 		    throw(
-		      {stop,{unexpected,idle,Type,Content,PrevState}})
+		      {stop,{unexpected,idle,Type,Content}})
 	    end;
 	Result ->
 	    Result
     end.
 
-timeout(timeout, idle, idle, {From,Time}) ->
+timeout(timeout, idle, {From,Time}) ->
     TRef2 = erlang:start_timer(Time, self(), ok),
     TRefC1 = erlang:start_timer(Time, self(), cancel1),
     TRefC2 = erlang:start_timer(Time, self(), cancel2),
     {next_state,timeout2,{From,Time,TRef2},
      [{cancel_timer, TRefC1},
       {next_event,internal,{cancel_timer,TRefC2}}]};
-timeout(_, _, _, Data) ->
+timeout(_, _, Data) ->
     {keep_state,Data}.
 
 timeout2(
-  internal, {cancel_timer,TRefC2}, timeout, {From,Time,TRef2}) ->
+  internal, {cancel_timer,TRefC2}, {From,Time,TRef2}) ->
     Time4 = Time * 4,
     receive after Time4 -> ok end,
     {next_state,timeout3,{From,TRef2},
      [{cancel_timer,TRefC2}]};
-timeout2(_, _, _, Data) ->
+timeout2(_, _, Data) ->
     {keep_state,Data}.
 
-timeout3(info, {timeout,TRef2,Result}, _, {From,TRef2}) ->
+timeout3(info, {timeout,TRef2,Result}, {From,TRef2}) ->
     gen_statem:reply([{reply,From,Result}]),
     {next_state,idle,state};
-timeout3(_, _, _, Data) ->
+timeout3(_, _, Data) ->
     {keep_state,Data}.
 
-wfor_conf({call,From}, confirm, _, Data) ->
+wfor_conf({call,From}, confirm, Data) ->
     {next_state,connected,Data,
      [{reply,From,yes}]};
-wfor_conf(cast, {ping,_,_}, _, _) ->
+wfor_conf(cast, {ping,_,_}, _) ->
     {keep_state_and_data,[postpone]};
-wfor_conf(cast, confirm, _, Data) ->
+wfor_conf(cast, confirm, Data) ->
     {next_state,connected,Data};
-wfor_conf(Type, Content, _, Data) ->
+wfor_conf(Type, Content, Data) ->
     case handle_common_events(Type, Content, wfor_conf, Data) of
 	undefined ->
 	    case Type of
@@ -1239,21 +1239,21 @@ wfor_conf(Type, Content, _, Data) ->
 	    Result
     end.
 
-connected({call,From}, {msg,Ref}, _, Data) ->
+connected({call,From}, {msg,Ref}, Data) ->
     {keep_state,Data,
      [{reply,From,{ack,Ref}}]};
-connected(cast, {msg,From,Ref}, _, Data) ->
+connected(cast, {msg,From,Ref}, Data) ->
     From ! {ack,Ref},
     {keep_state,Data};
-connected({call,From}, disconnect, _, Data) ->
+connected({call,From}, disconnect, Data) ->
     {next_state,idle,Data,
      [{reply,From,yes}]};
-connected(cast, disconnect, _, Data) ->
+connected(cast, disconnect, Data) ->
     {next_state,idle,Data};
-connected(cast, {ping,Pid,Tag}, _, Data) ->
+connected(cast, {ping,Pid,Tag}, Data) ->
     Pid ! {pong,Tag},
     {keep_state,Data};
-connected(Type, Content, _, Data) ->
+connected(Type, Content, Data) ->
     case handle_common_events(Type, Content, connected, Data) of
 	undefined ->
 	    case Type of
@@ -1267,9 +1267,9 @@ connected(Type, Content, _, Data) ->
 	    Result
     end.
 
-state0({call,From}, stop, _, Data) ->
+state0({call,From}, stop, Data) ->
     {stop_and_reply,normal,[{reply,From,stopped}],Data};
-state0(Type, Content, _, Data) ->
+state0(Type, Content, Data) ->
     case handle_common_events(Type, Content, state0, Data) of
 	undefined ->
 	    {keep_state,Data};
@@ -1277,26 +1277,26 @@ state0(Type, Content, _, Data) ->
 	    Result
     end.
 
-hiber_idle({call,From}, 'alive?', _, Data) ->
+hiber_idle({call,From}, 'alive?', Data) ->
     {keep_state,Data,
      [{reply,From,'alive!'}]};
-hiber_idle({call,From}, hibernate_sync, _, Data) ->
+hiber_idle({call,From}, hibernate_sync, Data) ->
     {next_state,hiber_wakeup,Data,
      [{reply,From,hibernating},
       hibernate]};
-hiber_idle(info, hibernate_later, _, _) ->
+hiber_idle(info, hibernate_later, _) ->
     Tref = erlang:start_timer(1000, self(), hibernate),
     {keep_state,Tref};
-hiber_idle(info, hibernate_now, _, Data) ->
+hiber_idle(info, hibernate_now, Data) ->
     {keep_state,Data,
      [hibernate]};
-hiber_idle(info, {timeout,Tref,hibernate}, _, Tref) ->
+hiber_idle(info, {timeout,Tref,hibernate}, Tref) ->
     {keep_state,[],
      [hibernate]};
-hiber_idle(cast, hibernate_async, _, Data) ->
+hiber_idle(cast, hibernate_async, Data) ->
     {next_state,hiber_wakeup,Data,
      [hibernate]};
-hiber_idle(Type, Content, _, Data) ->
+hiber_idle(Type, Content, Data) ->
     case handle_common_events(Type, Content, hiber_idle, Data) of
 	undefined ->
 	    {keep_state,Data};
@@ -1304,19 +1304,19 @@ hiber_idle(Type, Content, _, Data) ->
 	    Result
     end.
 
-hiber_wakeup({call,From}, wakeup_sync, _, Data) ->
+hiber_wakeup({call,From}, wakeup_sync, Data) ->
     {next_state,hiber_idle,Data,
      [{reply,From,good_morning}]};
-hiber_wakeup({call,From}, snooze_sync, _, Data) ->
+hiber_wakeup({call,From}, snooze_sync, Data) ->
     {keep_state,Data,
      [{reply,From,please_just_five_more},
       hibernate]};
-hiber_wakeup(cast, wakeup_async, _, Data) ->
+hiber_wakeup(cast, wakeup_async, Data) ->
     {next_state,hiber_idle,Data};
-hiber_wakeup(cast, snooze_async, _, Data) ->
+hiber_wakeup(cast, snooze_async, Data) ->
     {keep_state,Data,
      [hibernate]};
-hiber_wakeup(Type, Content, _, Data) ->
+hiber_wakeup(Type, Content, Data) ->
     case handle_common_events(Type, Content, hiber_wakeup, Data) of
 	undefined ->
 	    {keep_state,Data};
@@ -1353,10 +1353,9 @@ handle_common_events(_, _, _, _) ->
 %% Wrap the state in a 1 element list just to test non-atom
 %% states.  Note that the state from init/1 is not wrapped
 %% so both atom and non-atom states are tested.
-handle_event(Type, Event, PrevState, State, Data) ->
-    PrevStateName = unwrap_state(PrevState),
+handle_event(Type, Event, State, Data) ->
     StateName = unwrap_state(State),
-    try ?MODULE:StateName(Type, Event, PrevStateName, Data) of
+    try ?MODULE:StateName(Type, Event, Data) of
 	Result ->
 	    wrap_result(Result)
     catch
-- 
cgit v1.2.3


From 7a731535a3c4eebac00bd56ae7862c2dac25284c Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 24 Feb 2016 16:52:01 +0100
Subject: Unify whitespace in XML doc

---
 lib/stdlib/doc/src/gen_statem.xml | 534 +++++++++++++++++++++++---------------
 1 file changed, 330 insertions(+), 204 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index f21610d14c..da88bedf6b 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -31,7 +31,8 @@
   <module>gen_statem</module>
   <modulesummary>Generic State Machine Behaviour</modulesummary>
   <description>
-    <p>A behaviour module for implementing a state machine.
+    <p>
+      A behaviour module for implementing a state machine.
       Two callback modes are supported.  One for a finite state
       machine like <seealso marker="gen_fsm">gen_fsm</seealso>
       that require the state to be an atom and use that state as
@@ -45,9 +46,12 @@
       and include functionality for tracing and error reporting.
       It will also fit into an OTP supervision tree. Refer to
       <seealso marker="doc/design_principles:gen_server_concepts">
-        OTP Design Principles</seealso> for more information.
+        OTP Design Principles
+      </seealso>
+      for more information.
     </p>
-    <p>A <c>gen_statem</c> assumes all specific parts to be located in a
+    <p>
+      A <c>gen_statem</c> assumes all specific parts to be located in a
       callback module exporting a pre-defined set of functions.
       The relationship between the behaviour functions and the callback
       functions can be illustrated as follows:</p>
@@ -68,29 +72,32 @@ erlang:'!'            -----> Module:StateName/3
 -                     -----> Module:terminate/3
 
 -                     -----> Module:code_change/4</pre>
-    <p>Events are of different
+    <p>
+      Events are of different
       <seealso marker="#type-event_type">types</seealso>
       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,
+    <p>
+      If a callback function fails or returns a bad value,
       the <c>gen_statem</c> will terminate.  An exception of class
       <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
       however, is not regarded as an error but as a valid return.
     </p>
     <marker id="state_function" />
-    <p>The "<em>state function</em>" for a specific
+    <p>
+      The "<em>state function</em>" for a specific
       <seealso marker="#type-state">state</seealso>
       in a <c>gen_statem</c> is the callback function that is called
       for all events in this state, and is selected depending on
       <seealso marker="#type-callback_mode">callback_mode</seealso>
       that the implementation specifies during <c>gen_statem</c> init.
     </p>
-    <p>When
+    <p>
+      When
       <seealso marker="#type-callback_mode">callback_mode</seealso>
       is <c>state_functions</c> the state has to be an atom and
-      is used as the state function name.
-      See
+      is used as the state function name.  See
       <seealso marker="#Module:StateName/3">
         <c>Module:StateName/3</c>
       </seealso>.
@@ -101,8 +108,8 @@ erlang:'!'            -----> Module:StateName/3
         <c>Module:terminate/3</c>
       </seealso> makes the state name <c>terminate</c> unusable.
     </p>
-    <p>When
-      <seealso marker="#type-callback_mode">callback_mode</seealso>
+    <p>
+      When <seealso marker="#type-callback_mode">callback_mode</seealso>
       is <c>handle_event_function</c> the state can be any term
       and the state function name is
       <seealso marker="#Module:handle_event/4">
@@ -114,7 +121,8 @@ erlang:'!'            -----> Module:StateName/3
       states so you do not accidentally postpone one event
       forever creating an infinite busy loop.
     </p>
-    <p>The <c>gen_statem</c> enqueues incoming events in order of arrival
+    <p>
+      The <c>gen_statem</c> enqueues incoming events in order of arrival
       and presents these to the
       <seealso marker="#state_function">state function</seealso>
       in that order.  The state function can postpone an event
@@ -122,14 +130,15 @@ erlang:'!'            -----> Module:StateName/3
       After a state change all enqueued events (including postponed)
       are again presented to the state function.
     </p>
-    <p>The <c>gen_statem</c> event queue model is sufficient
+    <p>
+      The <c>gen_statem</c> event queue model is sufficient
       to emulate the normal process message queue and selective receive
       with postponing an event corresponding to not matching
       it in a receive statement and changing states corresponding
       to entering a new receive statement.
     </p>
-    <p>The
-      <seealso marker="#state_function">state function</seealso>
+    <p>
+      The <seealso marker="#state_function">state function</seealso>
       can insert events using the
       <seealso marker="#type-action">
 	<c>action()</c> <c>next_event</c>
@@ -143,7 +152,8 @@ erlang:'!'            -----> Module:StateName/3
       that can be used for such events making it impossible
       to mistake for an external event.
     </p>
-    <p>Inserting an event replaces the trick of calling your own
+    <p>
+      Inserting an event replaces the trick of calling your own
       state handling functions that you often would have to
       resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
       to force processing an inserted event before others.
@@ -159,20 +169,24 @@ erlang:'!'            -----> Module:StateName/3
       </seealso>
       for the details of a state transition.
     </p>
-    <p>A <c>gen_statem</c> handles system messages as documented in
-       <seealso marker="sys">sys</seealso>.
-       The <seealso marker="sys">sys</seealso> module
-       can be used for debugging a <c>gen_statem</c>.
+    <p>
+      A <c>gen_statem</c> handles system messages as documented in
+      <seealso marker="sys">sys</seealso>.
+      The <seealso marker="sys">sys</seealso> module
+      can be used for debugging a <c>gen_statem</c>.
     </p>
-    <p>Note that a <c>gen_statem</c> does not trap exit signals
+    <p>
+      Note that a <c>gen_statem</c> does not trap exit signals
       automatically, this must be explicitly initiated by
       the callback module.
     </p>
-    <p>Unless otherwise stated, all functions in this module fail if
+    <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 given.
     </p>
-    <p>The <c>gen_statem</c> process can go into hibernation (see
+    <p>
+      The <c>gen_statem</c> process can go into hibernation (see
       <seealso marker="erts:erlang#hibernate/3">
 	<c>erlang:hibernate/3</c>
       </seealso>) if a
@@ -192,11 +206,13 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="server_name" />
       <desc>
-	<p>Name specification to use when starting
-	  a <c>gen_statem</c> server.
-	  See <seealso marker="#start_link/3">
+	<p>
+	  Name specification to use when starting
+	  a <c>gen_statem</c> server.  See
+	  <seealso marker="#start_link/3">
 	    <c>start_link/3</c>
-	  </seealso> and
+	  </seealso>
+	  and
 	  <seealso marker="#type-server_ref">
 	    <c>server_ref()</c>
 	  </seealso> below.
@@ -206,12 +222,14 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="server_ref" />
       <desc>
-	<p>Server specification to use when addressing
+	<p>
+	  Server specification to use when addressing
 	  a <c>gen_statem</c> server.
 	  See <seealso marker="#call/2">call/2</seealso> and
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
-	  </seealso> above.
+	  </seealso>
+	  above.
 	</p>
 	<p>It can be:</p>
 	<taglist>
@@ -219,15 +237,18 @@ erlang:'!'            -----> Module:StateName/3
 	  <tag><c>LocalName</c></tag>
 	  <item>The <c>gen_statem</c> is locally registered.</item>
 	  <tag><c>Name, Node</c></tag>
-	  <item>The <c>gen_statem</c> is locally registered
+	  <item>
+	    The <c>gen_statem</c> is locally registered
 	    on another node.
 	  </item>
 	  <tag><c>GlobalName</c></tag>
-	  <item>The <c>gen_statem</c> is globally registered
+	  <item>
+	    The <c>gen_statem</c> is globally registered
 	    in <seealso marker="kernel:global"><c>global</c></seealso>.
 	  </item>
 	  <tag><c>RegMod, ViaName</c></tag>
-	  <item>The <c>gen_statem</c> is registered through
+	  <item>
+	    The <c>gen_statem</c> is registered through
 	    an alternative process registry.
 	    The registry callback module <c>RegMod</c>
 	    should export the functions
@@ -244,11 +265,13 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="debug_opt" />
       <desc>
-	<p>Debug option that can be used when starting
+	<p>
+	  Debug option that can be used when starting
 	  a <c>gen_statem</c> server through for example
 	  <seealso marker="#enter_loop/4">enter_loop/4</seealso>.
 	</p>
-	<p>For every entry in <c><anno>Dbgs</anno></c>
+	<p>
+	  For every entry in <c><anno>Dbgs</anno></c>
 	  the corresponding function in
 	  <seealso marker="sys"><c>sys</c></seealso> will be called.
 	</p>
@@ -257,7 +280,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="start_opt" />
       <desc>
-	<p>Options that can be used when starting
+	<p>
+	  Options that can be used when starting
 	  a <c>gen_statem</c> server through for example
 	  <seealso marker="#start_link/3">start_link/3</seealso>.
 	</p>
@@ -266,7 +290,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="start_ret" />
       <desc>
-	<p>Return value from the start functions for_example
+	<p>
+	  Return value from the start functions for_example
 	  <seealso marker="#start_link/3">start_link/3</seealso>.
 	</p>
       </desc>
@@ -275,7 +300,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="caller" />
       <desc>
-	<p>Destination to use when replying through for example the
+	<p>
+	  Destination to use when replying through for example the
 	  <seealso marker="#type-action">
 	    action() {reply,Caller,Reply}
 	  </seealso>
@@ -287,7 +313,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="state" />
       <desc>
-	<p>After a state change (<c>NewState =/= State</c>)
+	<p>
+	  After a state change (<c>NewState =/= State</c>)
 	  all postponed events are retried.
 	</p>
       </desc>
@@ -295,10 +322,12 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="state_name" />
       <desc>
-	<p>If
+	<p>
+	  If
 	  <seealso marker="#type-callback_mode">
 	    callback_mode
-	  </seealso> is <c>state_functions</c>, which is the default,
+	  </seealso>
+	  is <c>state_functions</c>, which is the default,
 	  the state has to be of this type.
 	</p>
       </desc>
@@ -306,7 +335,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="data" />
       <desc>
-	<p>A term in which the state machine implementation
+	<p>
+	  A term in which the state machine implementation
 	  should store any server data it needs.  The difference between
 	  this and the <seealso marker="#type-state">state()</seealso>
 	  itself is that a change in this data does not cause
@@ -320,7 +350,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="event_type" />
       <desc>
-	<p>External events are of 3 different type:
+	<p>
+	  External events are of 3 different type:
 	  <c>{call,<anno>Caller</anno>}</c>, <c>cast</c> or <c>info</c>.
 	  Calls (synchronous) and casts (asynchronous)
 	  originate from the corresponding API functions.
@@ -337,7 +368,8 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="event_predicate" />
       <desc>
-	<p>A <c>fun()</c> of arity 2 that takes an event
+	<p>
+	  A <c>fun()</c> of arity 2 that takes an event
 	  and returns a boolean.
 	  When used in the
 	  <seealso marker="#type-action">action()</seealso>
@@ -363,18 +395,22 @@ erlang:'!'            -----> Module:StateName/3
 	</p>
 	<taglist>
 	  <tag><c>state_functions</c></tag>
-	  <item>The state has to be of type
+	  <item>
+	    The state has to be of type
 	    <seealso marker="#type-state_name"><c>state_name()</c></seealso>
 	    and one callback function per state that is
 	    <seealso marker="#Module:StateName/3">
 	      <c>Module:StateName/3</c>
-	    </seealso> is used.
+	    </seealso>
+	    is used.
 	  </item>
 	  <tag><c>handle_event_function</c></tag>
-	  <item>The state can be any term and the callback function
+	  <item>
+	    The state can be any term and the callback function
 	    <seealso marker="#Module:handle_event/4">
 	      <c>Module:handle_event/4</c>
-	    </seealso> is used for all states.
+	    </seealso>
+	    is used for all states.
 	  </item>
 	</taglist>
       </desc>
@@ -388,9 +424,10 @@ erlang:'!'            -----> Module:StateName/3
 	  and they modify how the state transition is done:
 	</p>
 	<list type="ordered">
-	  <item>All
-          <seealso marker="#type-action"><c>actions</c></seealso>
-	  are processed in order of appearance.
+	  <item>
+	    All
+            <seealso marker="#type-action"><c>actions</c></seealso>
+	    are processed in order of appearance.
 	  </item>
 	  <item>
 	    If the
@@ -481,14 +518,16 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="action" />
       <desc>
-	<p>These state transition actions may be invoked by
+	<p>
+	  These state transition actions may be invoked by
 	  returning them from the
 	  <seealso marker="#state_function">state function</seealso>,
 	  from <seealso marker="#Module:init/1">Module:init/1</seealso>
 	  or by giving them to
 	  <seealso marker="#enter_loop/6">enter_loop/6,7</seealso>.
 	</p>
-	<p>Actions are executed in the containing list order.
+	<p>
+	  Actions are executed in the containing list order.
 	  The order matters for some actions such as <c>next_event</c>
 	  and <c>reply_action()</c>.  The order can in peculiar cases
 	  matter for <c>remove_event</c> with
@@ -599,12 +638,14 @@ erlang:'!'            -----> Module:StateName/3
     <datatype>
       <name name="reply_action" />
       <desc>
-	<p>Reply to a caller waiting for a reply in
+	<p>
+	  Reply to a caller waiting for a reply in
 	  <seealso marker="#call/2"><c>call/2</c></seealso>.
           <c><anno>Caller</anno></c> must be the term from the
 	  <seealso marker="#type-event_type">
 	    <c>{call,<anno>Caller</anno>}</c>
-	  </seealso> argument to the
+	  </seealso>
+	  argument to the
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
       </desc>
@@ -614,35 +655,42 @@ erlang:'!'            -----> Module:StateName/3
       <desc>
 	<taglist>
 	  <tag><c>stop</c></tag>
-	  <item>Terminate the <c>gen_statem</c> by calling
+	  <item>
+	    Terminate the <c>gen_statem</c> by calling
 	    <seealso marker="#Module:terminate/3">
 	      <c>Module:terminate/3</c>
-	    </seealso> with <c>Reason</c> and
+	    </seealso>
+	    with <c>Reason</c> and
 	    <c><anno>NewData</anno></c>, if given.
 	  </item>
 	  <tag><c>stop_and_reply</c></tag>
-	  <item>Send all <c><anno>Replies</anno></c>
+	  <item>
+	    Send all <c><anno>Replies</anno></c>
 	    then terminate the <c>gen_statem</c> by calling
 	    <seealso marker="#Module:terminate/3">
 	      <c>Module:terminate/3</c>
-	    </seealso> with <c>Reason</c> and
+	    </seealso>
+	    with <c>Reason</c> and
 	    <c><anno>NewData</anno></c>, if given.
 	  </item>
 	  <tag><c>next_state</c></tag>
-	  <item>The <c>gen_statem</c> will do a state transition to
+	  <item>
+	    The <c>gen_statem</c> will do a state transition to
 	    <c><anno>NewState</anno></c>
 	    (which may be the same as the current state),
 	    set <c><anno>NewData</anno></c>
 	    and execute all <c><anno>Actions</anno></c>
 	  </item>
 	  <tag><c>keep_state</c></tag>
-	  <item>The <c>gen_statem</c> will keep the current state, or
+	  <item>
+	    The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    set <c><anno>NewData</anno></c>
 	    and execute all <c><anno>Actions</anno></c>
 	  </item>
 	  <tag><c>keep_state_and_data</c></tag>
-	  <item>The <c>gen_statem</c> will keep the current state, or
+	  <item>
+	    The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    keep the current server data,
 	    and execute all <c><anno>Actions</anno></c>
@@ -659,7 +707,8 @@ erlang:'!'            -----> Module:StateName/3
       <name name="start_link" arity="4" />
       <fsummary>Create a linked <c>gen_statem</c> process</fsummary>
       <desc>
-        <p>Creates a <c>gen_statem</c> process according
+        <p>
+	  Creates a <c>gen_statem</c> process according
 	  to OTP design principles
 	  (using
           <seealso marker="proc_lib"><c>proc_lib</c></seealso>
@@ -668,82 +717,88 @@ erlang:'!'            -----> Module:StateName/3
 	  This is essential when the <c>gen_statem</c> shall be part of
 	  a supervision tree so it gets linked to its supervisor.
 	</p>
-        <p>The <c>gen_statem</c> process calls
+        <p>
+	  The <c>gen_statem</c> process calls
 	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
 	  to initialize the server. To ensure a synchronized start-up
 	  procedure, <c>start_link/3,4</c> does not return until
 	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
           has returned.
 	</p>
-	<p><c><anno>ServerName</anno></c> specifies the
+	<p>
+	  <c><anno>ServerName</anno></c> specifies the
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
-	  </seealso> to register for the <c>gen_statem</c>.
+	  </seealso>
+	  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 which is passed as
+        <p>
+	  <c><anno>Args</anno></c> is an arbitrary term which is passed as
           the argument to
-	  <seealso marker="#Module:init/1"><c>Module:init/1</c>
-	  </seealso>.
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>.
 	</p>
-        <p>If the option <c>{timeout,Time}</c> is present in
+        <p>
+	  If the option <c>{timeout,Time}</c> is present in
 	  <c><anno>Opts</anno></c>, the <c>gen_statem</c>
 	  is allowed to spend <c>Time</c> milliseconds initializing
 	  or it will be terminated and the start function will return
-	  <seealso marker="#type-start_ret">
-	    <c>{error,timeout}</c>
-	  </seealso>.
+	  <seealso marker="#type-start_ret"><c>{error,timeout}</c></seealso>.
 	</p>
-        <p>If the option
+        <p>
+	  If the option
 	  <seealso marker="#type-debug_opt"><c>{debug,Dbgs}</c></seealso>
 	  is present in <c><anno>Opts</anno></c>, debugging through
 	  <seealso marker="sys"><c>sys</c></seealso> is activated.
 	</p>
-        <p>If the option <c>{spawn_opt,SpawnOpts}</c> is present in
+        <p>
+	  If the option <c>{spawn_opt,SpawnOpts}</c> is present in
 	  <c><anno>Opts</anno></c>, <c>SpawnOpts</c> will be passed
 	  as option list to
           <seealso marker="erts:erlang#spawn_opt/2">spawn_opt/2</seealso>
 	  which is used to spawn the <c>gen_statem</c> process.
 	</p>
         <note>
-          <p>Using the spawn option <c>monitor</c> is currently not
+          <p>
+	    Using the spawn option <c>monitor</c> is currently not
             allowed, but will cause this function to fail with reason
-            <c>badarg</c>.</p>
+            <c>badarg</c>.
+	  </p>
         </note>
-        <p>If the <c>gen_statem</c> is successfully created
+        <p>
+	  If the <c>gen_statem</c> is successfully created
 	  and initialized this function returns
 	  <seealso marker="#type-start_ret">
 	    <c>{ok,Pid}</c>,
-	  </seealso> where <c>Pid</c> is the <c>pid()</c>
+	  </seealso>
+	  where <c>Pid</c> is the <c>pid()</c>
 	  of the <c>gen_statem</c>.
 	  If there already exists a process with the specified
 	  <c><anno>ServerName</anno></c> this function returns
-	  <seealso marker="#type-start_ret">
-            <c>{error,{already_started,Pid}}</c>
-	  </seealso>, where <c>Pid</c> is the <c>pid()</c> of that process.
+	  <seealso marker="#type-start_ret"><c>{error,{already_started,Pid}}</c></seealso>,
+	  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>,
+        <p>
+	  If <c>Module:init/1</c> fails with <c>Reason</c>,
           this function returns
-	  <seealso marker="#type-start_ret">
-	    <c>{error,Reason}</c>
-	  </seealso>. If <c>Module:init/1</c> returns
+	  <seealso marker="#type-start_ret"><c>{error,Reason}</c></seealso>.
+	  If <c>Module:init/1</c> returns
 	  <seealso marker="#type-start_ret">
 	    <c>{stop,Reason}</c>
 	  </seealso>
 	  or
-	  <seealso marker="#type-start_ret">
-            <c>ignore</c>
-	  </seealso>, the process is terminated and this function
+	  <seealso marker="#type-start_ret"><c>ignore</c></seealso>,
+	  the process is terminated and this function
           returns
 	  <seealso marker="#type-start_ret">
 	    <c>{error,Reason}</c>
-	  </seealso> or
-	  <seealso marker="#type-start_ret">
-	  <c>ignore</c>
-	  </seealso>, respectively.
+	  </seealso>
+	  or
+	  <seealso marker="#type-start_ret"><c>ignore</c></seealso>,
+	  respectively.
 	</p>
       </desc>
     </func>
@@ -754,7 +809,8 @@ erlang:'!'            -----> Module:StateName/3
       <name name="start" arity="4" />
       <fsummary>Create a stand-alone <c>gen_statem</c> process</fsummary>
       <desc>
-        <p>Creates a stand-alone <c>gen_statem</c> process according to
+        <p>
+	  Creates a stand-alone <c>gen_statem</c> process according to
 	  OTP design principles (using
           <seealso marker="proc_lib"><c>proc_lib</c></seealso>
 	  primitives).
@@ -762,7 +818,8 @@ erlang:'!'            -----> Module:StateName/3
 	  this start function can not be used by a supervisor
 	  to start a child.
 	</p>
-        <p>See <seealso marker="#start_link/3">start_link/3,4</seealso>
+        <p>
+	  See <seealso marker="#start_link/3">start_link/3,4</seealso>
           for a description of arguments and return values.
 	</p>
       </desc>
@@ -772,10 +829,9 @@ erlang:'!'            -----> Module:StateName/3
       <name name="stop" arity="1" />
       <fsummary>Synchronously stop a generic server</fsummary>
       <desc>
-	<p>The same as
-	  <seealso marker="#stop/3">
-	    <c>stop(<anno>ServerRef</anno>, normal, infinity)</c>
-	  </seealso>.
+	<p>
+	  The same as
+	  <seealso marker="#stop/3"><c>stop(<anno>ServerRef</anno>, normal, infinity)</c></seealso>.
 	</p>
       </desc>
     </func>
@@ -783,33 +839,37 @@ erlang:'!'            -----> Module:StateName/3
       <name name="stop" arity="3" />
       <fsummary>Synchronously stop a generic server</fsummary>
       <desc>
-	<p>Orders the <c>gen_statem</c>
+	<p>
+	  Orders the <c>gen_statem</c>
 	  <seealso marker="#type-server_ref">
 	    <c><anno>ServerRef</anno></c>
-	  </seealso> to exit with the given <c><anno>Reason</anno></c>
+	  </seealso>
+	  to exit with the given <c><anno>Reason</anno></c>
 	  and waits for it to terminate.
 	  The <c>gen_statem</c> will call
           <seealso marker="#Module:terminate/3">
 	    Module:terminate/3
-	  </seealso> before exiting.
+	  </seealso>
+	  before exiting.
 	</p>
-	<p>This function returns <c>ok</c> if the server terminates
+	<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> will cause an
           error report to be issued through
-          <seealso marker="kernel:error_logger#format/2">
-	    error_logger:format/2
-	  </seealso>.
+          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.
 	  The default <c><anno>Reason</anno></c> is <c>normal</c>.
 	</p>
-	<p><c><anno>Timeout</anno></c> is an integer greater than zero
+	<p>
+	  <c><anno>Timeout</anno></c> is an integer greater than zero
 	  which specifies how many milliseconds to wait for the server to
           terminate, or the atom <c>infinity</c> to wait indefinitely.
 	  The default value is <c>infinity</c>.
 	  If the server has not terminated within the specified time,
 	  a <c>timeout</c> exception is raised.
 	</p>
-	<p>If the process does not exist, a <c>noproc</c> exception
+	<p>
+	  If the process does not exist, a <c>noproc</c> exception
 	  is raised.
 	</p>
       </desc>
@@ -820,10 +880,12 @@ erlang:'!'            -----> Module:StateName/3
       <name name="call" arity="3" />
       <fsummary>Make a synchronous call to a <c>gen_statem</c></fsummary>
       <desc>
-        <p>Makes a synchronous call to the <c>gen_statem</c>
+        <p>
+	  Makes a synchronous call to the <c>gen_statem</c>
 	  <seealso marker="#type-server_ref">
 	    <c><anno>ServerRef</anno></c>
-	  </seealso> by sending a request
+	  </seealso>
+	  by sending a request
 	  and waiting until its reply arrives.
 	  The <c>gen_statem</c> will call the
 	  <seealso marker="#state_function">state function</seealso> with
@@ -831,23 +893,24 @@ erlang:'!'            -----> Module:StateName/3
 	  <c>{call,Caller}</c> and event content
 	  <c><anno>Request</anno></c>.
 	</p>
-	<p>A <c><anno>Reply</anno></c> is generated when a
+	<p>
+	  A <c><anno>Reply</anno></c> is generated when a
 	  <seealso marker="#state_function">state function</seealso>
 	  returns with
 	  <c>{reply,Caller,<anno>Reply</anno>}</c> as one
-	  <seealso marker="#type-action">
-	    <c>action()</c>
-	  </seealso>,
+	  <seealso marker="#type-action"><c>action()</c></seealso>,
 	  and that <c><anno>Reply</anno></c> becomes the return value
 	  of this function.
 	</p>
-        <p><c><anno>Timeout</anno></c> is an integer greater than zero
+        <p>
+	  <c><anno>Timeout</anno></c> is an integer greater than zero
 	  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.
 	  <note>
-	    <p>To avoid getting a late reply in the caller's
+	    <p>
+	      To avoid getting a late reply in the caller's
 	      inbox this function spawns a proxy process that
 	      does the call.  A late reply gets delivered to the
 	      dead proxy process hence gets discarded.  This is
@@ -856,7 +919,8 @@ erlang:'!'            -----> Module:StateName/3
 	    </p>
 	  </note>
 	</p>
-        <p>The call may fail for example if the <c>gen_statem</c> dies
+        <p>
+	  The call may fail for example if the <c>gen_statem</c> dies
 	  before or during this function call.
 	</p>
       </desc>
@@ -866,10 +930,12 @@ erlang:'!'            -----> Module:StateName/3
       <name name="cast" arity="2" />
       <fsummary>Send an asynchronous event to a <c>gen_statem</c></fsummary>
       <desc>
-	<p>Sends an asynchronous event to the <c>gen_statem</c>
+	<p>
+	  Sends an asynchronous event to the <c>gen_statem</c>
 	  <seealso marker="#type-server_ref">
 	    <c><anno>ServerRef</anno></c>
-	  </seealso> and returns <c>ok</c> immediately,
+	  </seealso>
+	  and returns <c>ok</c> immediately,
 	  ignoring if the destination node or <c>gen_statem</c>
 	  does not exist.
 	  The <c>gen_statem</c> will call the
@@ -886,26 +952,31 @@ erlang:'!'            -----> Module:StateName/3
       <name name="reply" arity="2" />
       <fsummary>Reply to a caller</fsummary>
       <desc>
-        <p>This function can be used by a <c>gen_statem</c>
+        <p>
+	  This function can be used by a <c>gen_statem</c>
 	  to explicitly send a reply to a process that waits in
 	  <seealso marker="#call/2"><c>call/2</c></seealso>
           when the reply cannot be defined in
           the return value of a
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
-        <p><c><anno>Caller</anno></c> must be the term from the
+        <p>
+	  <c><anno>Caller</anno></c> must be the term from the
 	  <seealso marker="#type-event_type">
 	    <c>{call,<anno>Caller</anno>}</c>
-	  </seealso> argument to the
+	  </seealso>
+	  argument to the
 	  <seealso marker="#state_function">state function</seealso>.
 	  <c><anno>Caller</anno></c> and <c><anno>Reply</anno></c>
 	  can also be specified using a
 	  <seealso marker="#type-reply_action">
 	    <c>reply_action()</c>
-	  </seealso> and multiple replies with a list of them.
+	  </seealso>
+	  and multiple replies with a list of them.
 	</p>
 	<note>
-	  <p>A reply sent with this function will not be visible
+	  <p>
+	    A reply sent with this function will not be visible
 	    in <seealso marker="sys">sys</seealso> debug output.
 	  </p>
 	</note>
@@ -916,12 +987,14 @@ erlang:'!'            -----> Module:StateName/3
       <name name="enter_loop" arity="5" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
-	<p>The same as
+	<p>
+	  The same as
 	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  except that no
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
-	  </seealso> must have been registered.
+	  </seealso>
+	  must have been registered.
 	</p>
       </desc>
     </func>
@@ -929,16 +1002,19 @@ erlang:'!'            -----> Module:StateName/3
       <name name="enter_loop" arity="6" />
       <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>
+	<p>
+	  If <c><anno>Server_or_Actions</anno></c> is a <c>list()</c>
 	  the same as
 	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  except that no
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
-	  </seealso> must have been registered and
+	  </seealso>
+	  must have been registered and
 	  <c>Actions = <anno>Server_or_Actions</anno></c>.
 	</p>
-	<p>Otherwise the same as
+	<p>
+	  Otherwise the same as
 	  <seealso marker="#enter_loop/7"><c>enter_loop/7</c></seealso>
 	  with
 	  <c>Server = <anno>Server_or_Actions</anno></c> and
@@ -950,7 +1026,8 @@ erlang:'!'            -----> Module:StateName/3
       <name name="enter_loop" arity="7" />
       <fsummary>Enter the <c>gen_statem</c> receive loop</fsummary>
       <desc>
-        <p>Makes an the calling process become a <c>gen_statem</c>.
+        <p>
+	  Makes an the calling process become a <c>gen_statem</c>.
 	  Does not return, instead the calling process will enter
 	  the <c>gen_statem</c> receive loop and become
 	  a <c>gen_statem</c> server.
@@ -960,35 +1037,36 @@ erlang:'!'            -----> Module:StateName/3
 	  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
+        <p>
+	  This function is useful when a more complex initialization
           procedure is needed than
 	  the <c>gen_statem</c> behaviour provides.
 	</p>
-        <p><c><anno>Module</anno></c>, <c><anno>Opts</anno></c> and
+        <p>
+	  <c><anno>Module</anno></c>, <c><anno>Opts</anno></c> and
 	  <c><anno>Server</anno></c> have the same meanings
 	  as when calling
-          <seealso marker="#start_link/3">
-	    <c>gen_statem</c>:start[_link]/3,4
-	  </seealso>.
+          <seealso marker="#start_link/3"><c>gen_statem</c>:start[_link]/3,4</seealso>.
           However, the
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
-	  </seealso> name must have been registered accordingly
+	  </seealso>
+	  name must have been registered accordingly
 	  <em>before</em> this function is called.</p>
-        <p><c><anno>CallbackMode</anno></c>, <c><anno>State</anno></c>,
+        <p>
+	  <c><anno>CallbackMode</anno></c>, <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
           <seealso marker="#Module:init/1">Module:init/1</seealso>.
           Also, the callback module <c><anno>Module</anno></c>
 	  does not need to export an <c>init/1</c> function.
 	</p>
-        <p>Failure: If the calling process was not started by a
+        <p>
+	  Failure: If the calling process was not started by a
           <seealso marker="proc_lib"><c>proc_lib</c></seealso>
 	  start function, or if it is not registered
           according to
-	  <seealso marker="#type-server_name">
-	    <c>server_name()</c>
-	  </seealso>.
+	  <seealso marker="#type-server_name"><c>server_name()</c></seealso>.
 	</p>
       </desc>
     </func>
@@ -999,7 +1077,8 @@ erlang:'!'            -----> Module:StateName/3
 
   <section>
     <title>CALLBACK FUNCTIONS</title>
-    <p>The following functions should be exported from a
+    <p>
+      The following functions should be exported from a
       <c><c>gen_statem</c></c> callback module.
     </p>
   </section>
@@ -1013,13 +1092,16 @@ erlang:'!'            -----> Module:StateName/3
         <v>Result = {CallbackMode,State,Data}</v>
 	<v>&nbsp;| {CallbackMode,State,Data,Actions}</v>
         <v>&nbsp;| {stop,Reason} | ignore</v>
-	<v>CallbackMode =
+	<v>
+	  CallbackMode =
 	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
 	</v>
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
-	<v>Data = <seealso marker="#type-data">data()</seealso>
+	<v>
+	  Data = <seealso marker="#type-data">data()</seealso>
 	</v>
-	<v>Actions =
+	<v>
+	  Actions =
 	  [<seealso marker="#type-action">action()</seealso>] |
 	  <seealso marker="#type-action">action()</seealso>
 	</v>
@@ -1027,16 +1109,20 @@ erlang:'!'            -----> Module:StateName/3
       </type>
       <desc>
 	<marker id="Module:init-1" />
-        <p>Whenever a <c>gen_statem</c> is started using
+        <p>
+	  Whenever a <c>gen_statem</c> is started using
           <seealso marker="#start_link/3">start_link/3,4</seealso>
 	  or
           <seealso marker="#start/3">start/3,4</seealso>,
           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 the start
-          function.</p>
-        <p>If the initialization is successful, the function should
+        <p>
+	  <c>Args</c> is the <c>Args</c> argument provided to the start
+          function.
+	</p>
+        <p>
+	  If the initialization is successful, the function should
           return <c>{CallbackMode,State,Data}</c> or
 	  <c>{CallbackMode,State,Data,Actions}</c>.
 	  <c>CallbackMode</c> selects the
@@ -1045,19 +1131,22 @@ erlang:'!'            -----> Module:StateName/3
 	  <c>State</c> is the initial
 	  <seealso marker="#type-state">state()</seealso>
 	  and <c>Data</c> the initial server
-	  <seealso marker="#type-data">data()</seealso>
+	  <seealso marker="#type-data">data()</seealso>.
 	</p>
-	<p>The <seealso marker="#type-action"><c>Actions</c></seealso>
+	<p>
+	  The <seealso marker="#type-action"><c>Actions</c></seealso>
 	  are executed when entering the first
 	  <seealso marker="#type-state">state</seealso> just as for a
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
-        <p>If something goes wrong during the initialization
+        <p>
+	  If something goes wrong during the initialization
           the function should return <c>{stop,Reason}</c>
 	  or <c>ignore</c>. See
           <seealso marker="#start_link/3">start_link/3,4</seealso>.
 	</p>
-	<p>This function may use
+	<p>
+	  This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Result</c>.
 	</p>
@@ -1072,24 +1161,29 @@ erlang:'!'            -----> Module:StateName/3
       </name>
       <fsummary>Handle an event</fsummary>
       <type>
-	<v>EventType =
+	<v>
+	  EventType =
 	  <seealso marker="#type-event_type">event_type()</seealso>
 	</v>
 	<v>EventContent = term()</v>
-	<v>State = NewState =
+	<v>
+	  State = NewState =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
-	<v>Data = NewData =
+	<v>
+	  Data = NewData =
 	  <seealso marker="#type-data">data()</seealso>
 	</v>
-	<v>Result =
+	<v>
+	  Result =
 	  <seealso marker="#type-state_callback_result">
 	    state_callback_result()
 	  </seealso>
 	</v>
       </type>
       <desc>
-        <p>Whenever a <c>gen_statem</c> receives an event from
+        <p>
+	  Whenever a <c>gen_statem</c> receives an event from
           <seealso marker="#call/2">call/2</seealso>,
           <seealso marker="#cast/2">cast/2</seealso> or
 	  as a normal process message one of these functions is called.
@@ -1098,7 +1192,8 @@ erlang:'!'            -----> Module:StateName/3
 	  and if it is <c>handle_event_function</c>
 	  then <c>Module:handle_event/4</c> is called.
 	</p>
-	<p>If <c>EventType</c> is
+	<p>
+	  If <c>EventType</c> is
 	  <seealso marker="#type-event_type"><c>{call,Caller}</c></seealso>
 	  the caller is waiting for a reply.  The reply can be sent
 	  from this or from any other
@@ -1107,20 +1202,20 @@ erlang:'!'            -----> Module:StateName/3
 	  <seealso marker="#type-action">Actions</seealso>, in
 	  <seealso marker="#type-reply_action">Replies</seealso>
 	  or by calling
-	  <seealso marker="#reply/2">
-	    <c>reply(Caller, Reply)</c>
-	  </seealso>.
+	  <seealso marker="#reply/2"><c>reply(Caller, Reply)</c></seealso>.
 	</p>
-	<p>If this function returns with a new state that
+	<p>
+	  If this function returns with a new state that
 	  does not match equal (<c>=/=</c>) to the current state
 	  all postponed events will be retried in the new state.
 	</p>
-	<p>See
-	  <seealso marker="#type-action">action()</seealso>
+	<p>
+	  See <seealso marker="#type-action">action()</seealso>
 	  for options that can be set and actions that can be done
 	  by <c>gen_statem</c> after returning from this function.
 	</p>
-	<p>These functions may use
+	<p>
+	  These functions may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
 	  to return <c>Result</c>.
 	</p>
@@ -1133,22 +1228,24 @@ erlang:'!'            -----> Module:StateName/3
       <type>
         <v>Reason = normal | shutdown | {shutdown,term()} | term()</v>
 	<v>State = <seealso marker="#type-state">state()</seealso></v>
-	<v>Data = <seealso marker="#type-data">data()</seealso>
-	</v>
+	<v>Data = <seealso marker="#type-data">data()</seealso></v>
 	<v>Ignored = term()</v>
       </type>
       <desc>
-        <p>This function is called by a <c>gen_statem</c>
+        <p>
+	  This function is called by a <c>gen_statem</c>
 	  when it is about to terminate. It should be the opposite of
 	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
           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
+        <p>
+	  <c>Reason</c> is a term denoting the stop reason and
           <seealso marker="#type-state">State</seealso>
 	  is the internal state of the <c>gen_statem</c>.
 	</p>
-        <p><c>Reason</c> depends on why the <c>gen_statem</c>
+        <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
@@ -1156,36 +1253,41 @@ erlang:'!'            -----> Module:StateName/3
 	  <c>Reason</c> will have the value specified in that tuple.
 	  If it is due to 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
+        <p>
+	  If the <c>gen_statem</c> is part of a supervision tree and is
           ordered by its supervisor to terminate, this function will be
           called with <c>Reason = shutdown</c> if the following
           conditions apply:</p>
         <list type="bulleted">
-          <item>the <c>gen_statem</c> has been set
+          <item>
+	    the <c>gen_statem</c> has been set
 	    to trap exit signals, and
 	  </item>
-          <item>the shutdown strategy as defined in the supervisor's
+          <item>
+	    the shutdown strategy as defined in the supervisor's
             child specification is an integer timeout value, not
             <c>brutal_kill</c>.
 	  </item>
         </list>
-        <p>Even if the <c>gen_statem</c> is <em>not</em>
+        <p>
+	  Even if the <c>gen_statem</c> is <em>not</em>
 	  part of a supervision tree, this function will be called
 	  if it receives an <c>'EXIT'</c> message from its parent.
 	  <c>Reason</c> will be the same as
 	  in the <c>'EXIT'</c> message.
 	</p>
-        <p>Otherwise, the <c>gen_statem</c> will be immediately terminated.
+        <p>
+	  Otherwise, the <c>gen_statem</c> will be immediately terminated.
 	</p>
-        <p>Note that for any other reason than <c>normal</c>,
+        <p>
+	  Note 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 due to an error
 	  and an error report is issued using
-          <seealso marker="kernel:error_logger#format/2">
-	    error_logger:format/2
-	  </seealso>.
+          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.
 	</p>
-	<p>This function may use
+	<p>
+	  This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Ignored</c>, which is ignored anyway.
 	</p>
@@ -1203,16 +1305,19 @@ erlang:'!'            -----> Module:StateName/3
         <v>OldState = NewState = term()</v>
         <v>Extra = term()</v>
 	<v>Result = {ok,{NewState,NewData}} | Reason</v>
-	<v>OldState = NewState =
+	<v>
+	  OldState = NewState =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
-	<v>OldData = NewData =
+	<v>
+	  OldData = NewData =
 	  <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Reason = term()</v>
       </type>
       <desc>
-        <p>This function is called by a <c>gen_statem</c> when it should
+        <p>
+	  This function is called by a <c>gen_statem</c> when it should
           update its internal state during a release upgrade/downgrade,
           i.e. when the instruction <c>{update,Module,Change,...}</c>
           where <c>Change={advanced,Extra}</c> is given in
@@ -1222,26 +1327,32 @@ erlang:'!'            -----> Module:StateName/3
 	  </seealso>
           for more information.
 	</p>
-        <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
+        <p>
+	  In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
           in the case of 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
+        <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>
+        <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 shall return the updated
+        <p>
+	  If successful, the function shall return the updated
           internal state in an
 	  <c>{ok,{NewState,NewData}}</c> tuple.
 	</p>
-	<p>If the function returns <c>Reason</c>, the ongoing
+	<p>
+	  If the function returns <c>Reason</c>, the ongoing
 	  upgrade will fail and roll back to the old release.</p>
-	<p>This function may use
+	<p>
+	  This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Result</c> or <c>Reason</c>.
 	</p>
@@ -1257,10 +1368,12 @@ erlang:'!'            -----> Module:StateName/3
       <type>
         <v>Opt = normal | terminate</v>
         <v>PDict = [{Key, Value}]</v>
-	<v>State =
+	<v>
+	  State =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
-	<v>Data =
+	<v>
+	  Data =
 	  <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>Key = term()</v>
@@ -1269,7 +1382,8 @@ erlang:'!'            -----> Module:StateName/3
       </type>
       <desc>
         <note>
-          <p>This callback is optional, so a callback module need not
+          <p>
+	    This callback is optional, so a callback module need not
             export it. The <c>gen_statem</c> module provides a default
             implementation of this function that returns
             <c>{State,Data}</c>.  If this callback fails the default
@@ -1280,43 +1394,52 @@ erlang:'!'            -----> Module:StateName/3
         </note>
         <p>This function is called by a <c>gen_statem</c> process when:</p>
         <list type="bulleted">
-          <item>One of
+          <item>
+	    One of
             <seealso marker="sys#get_status/1">
 	      <c>sys:get_status/1,2</c>
 	    </seealso>
             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.
+          <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 customising the form and
+        <p>
+	  This function is useful for customising the form and
           appearance of the <c>gen_statem</c> status for these cases. A
           callback module wishing to customise the
           <seealso marker="sys#get_status/1">
 	    <c>sys:get_status/1,2</c>
-	  </seealso> return value as well as how
+	  </seealso>
+	  return value as well as how
           its status appears in termination error logs exports an
           instance of <c>format_status/2</c> that returns a term
           describing the current status of the <c>gen_statem</c>.
 	</p>
-        <p><c>PDict</c> is the current value of the <c>gen_statem</c>'s
+        <p>
+	  <c>PDict</c> is the current value of the <c>gen_statem</c>'s
           process dictionary.
 	</p>
-        <p><seealso marker="#type-state"><c>State</c></seealso>
+        <p>
+	  <seealso marker="#type-state"><c>State</c></seealso>
 	  is the internal state of the <c>gen_statem</c>.
 	</p>
-        <p><seealso marker="#type-data"><c>Data</c></seealso>
+        <p>
+	  <seealso marker="#type-data"><c>Data</c></seealso>
 	  is the internal server data of the <c>gen_statem</c>.
 	</p>
-        <p>The function should return <c>Status</c>, a term that
+        <p>
+	  The function should return <c>Status</c>, a term that
           customises the 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
           <seealso marker="sys#get_status/1">
 	    <c>sys:get_status/1,2</c>
-	    </seealso> case (when <c>Opt</c>
+	  </seealso>
+	  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
@@ -1325,14 +1448,17 @@ erlang:'!'            -----> Module:StateName/3
           consistent with the rest of the
           <seealso marker="sys#get_status/1">
 	    <c>sys:get_status/1,2</c>
-	  </seealso> return value.
+	  </seealso>
+	  return value.
 	</p>
-        <p>One use for this function is to return compact alternative
+        <p>
+	  One use for this function is to return compact alternative
           state representations to avoid having large state terms
           printed in logfiles.  Another is to hide sensitive data from
 	  being written to the error log.
 	</p>
-	<p>This function may use
+	<p>
+	  This function may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return <c>Status</c>.
 	</p>
-- 
cgit v1.2.3


From e1bbf6f1a081ff41d3287a468450bef5f65ea4ad Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 24 Feb 2016 17:04:30 +0100
Subject: Type check in API

---
 lib/stdlib/src/gen_statem.erl | 104 ++++++++++++++++++++++++------------------
 1 file changed, 60 insertions(+), 44 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index c844b76653..dd980daddb 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -487,8 +487,17 @@ enter_loop(Module, Opts, CallbackMode, State, Data, Server_or_Actions) ->
 	Actions :: [action()] | action()) ->
 			no_return().
 enter_loop(Module, Opts, CallbackMode, State, Data, Server, Actions) ->
-    Parent = gen:get_parent(),
-    enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent).
+    case is_atom(Module) andalso callback_mode(CallbackMode) of
+	true ->
+	    Parent = gen:get_parent(),
+	    enter(
+	      Module, Opts, CallbackMode, State, Data, Server,
+	      Actions, Parent);
+	false ->
+	    error(
+	      badarg,
+	      [Module,Opts,CallbackMode,State,Data,Server,Actions])
+    end.
 
 %%---------------------------------------------------------------------------
 %% API helpers
@@ -510,38 +519,31 @@ do_send(Proc, Msg) ->
     end.
 
 %% Here init_it/6 and enter_loop/5,6,7 functions converge
-enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent)
-  when is_atom(Module), is_pid(Parent) ->
-    case callback_mode(CallbackMode) of
-	true ->
-	    Name = gen:get_proc_name(Server),
-	    Debug = gen:debug_options(Name, Opts),
-	    OldState = make_ref(),
-	    NewActions =
-		if
-		    is_list(Actions) ->
-			Actions ++ [{postpone,false}];
-		    true ->
-			[Actions,{postpone,false}]
-		end,
-	    S =	#{
-	      callback_mode => CallbackMode,
-	      module => Module,
-	      name => Name,
-	      state => OldState, % Discarded by loop_event_actions
-	      data => Data,
-	      timer => undefined,
-	      postponed => [],
-	      hibernate => false},
-	    loop_event_actions(
-	      Parent, Debug, S, [],
-	      {event,undefined}, % Discarded due to {postpone,false}
-	      OldState, State, Data, NewActions);
-	false ->
-	    erlang:error(
-	      badarg,
-	      [Module,Opts,CallbackMode,State,Data,Server,Actions,Parent])
-    end.
+enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent) ->
+    %% The values should already have been type checked
+    Name = gen:get_proc_name(Server),
+    Debug = gen:debug_options(Name, Opts),
+    OldState = make_ref(), % Will be discarded by loop_event_actions/9
+    NewActions =
+	if
+	    is_list(Actions) ->
+		Actions ++ [{postpone,false}];
+	    true ->
+		[Actions,{postpone,false}]
+	end,
+    S =	#{
+      callback_mode => CallbackMode,
+      module => Module,
+      name => Name,
+      state => OldState,
+      data => Data,
+      timer => undefined,
+      postponed => [],
+      hibernate => false},
+    loop_event_actions(
+      Parent, Debug, S, [],
+      {event,undefined}, % Will be discarded thanks to {postpone,false}
+      OldState, State, Data, NewActions).
 
 %%%==========================================================================
 %%%  gen callbacks
@@ -567,15 +569,29 @@ init_it(Starter, Parent, ServerRef, Module, Args, Opts) ->
 init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
     case Result of
 	{CallbackMode,State,Data} ->
-	    proc_lib:init_ack(Starter, {ok,self()}),
-	    enter(
-	      Module, Opts, CallbackMode, State, Data,
-	      ServerRef, [], Parent);
+	    case callback_mode(CallbackMode) of
+		true ->
+		    proc_lib:init_ack(Starter, {ok,self()}),
+		    enter(
+		      Module, Opts, CallbackMode, State, Data,
+		      ServerRef, [], Parent);
+		false ->
+		    Error = {bad_return_value,Result},
+		    proc_lib:init_ack(Starter, {error,Error}),
+		    exit(Error)
+	    end;
 	{CallbackMode,State,Data,Actions} ->
-	    proc_lib:init_ack(Starter, {ok,self()}),
-	    enter(
-	      Module, Opts, CallbackMode, State, Data,
-	      ServerRef, Actions, Parent);
+	    case callback_mode(CallbackMode) of
+		true ->
+		    proc_lib:init_ack(Starter, {ok,self()}),
+		    enter(
+		      Module, Opts, CallbackMode, State, Data,
+		      ServerRef, Actions, Parent);
+		false ->
+		    Error = {bad_return_value,Result},
+		    proc_lib:init_ack(Starter, {error,Error}),
+		    exit(Error)
+	    end;
 	{stop,Reason} ->
 	    gen:unregister_name(ServerRef),
 	    proc_lib:init_ack(Starter, {error,Reason}),
@@ -584,8 +600,8 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
 	    gen:unregister_name(ServerRef),
 	    proc_lib:init_ack(Starter, ignore),
 	    exit(normal);
-	Other ->
-	    Error = {bad_return_value,Other},
+	_ ->
+	    Error = {bad_return_value,Result},
 	    proc_lib:init_ack(Starter, {error,Error}),
 	    exit(Error)
     end.
-- 
cgit v1.2.3


From edc94441562b255467773ec27b11835910a708fd Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 25 Feb 2016 15:12:48 +0100
Subject: Remove {keep_state_and_data}
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Correct typo reported by Luïc Hoguin.
---
 lib/stdlib/doc/src/gen_statem.xml    | 2 +-
 lib/stdlib/src/gen_statem.erl        | 9 ++-------
 lib/stdlib/test/gen_statem_SUITE.erl | 2 +-
 3 files changed, 4 insertions(+), 9 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index da88bedf6b..35b842c173 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -61,7 +61,7 @@ gen_statem module            Callback module
 gen_statem:start
 gen_statem:start_link -----> Module:init/1
 
-gen_statem:stop       -----> Module:terminate/2
+gen_statem:stop       -----> Module:terminate/3
 
 gen_statem:call
 gen_statem:cast
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index dd980daddb..e6ad7ab0be 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -156,11 +156,10 @@
      Actions :: [action()] | action()} |
     {'keep_state', % {keep_state,NewData,[]}
      NewData :: data()} |
-    {'keep_state',
+    {'keep_state', % Keep state, change data
      NewData :: data(),
      Actions :: [action()] | action()} |
-    {'keep_state_and_data'} | % {keep_state_and_data,[]}
-    {'keep_state_and_data',
+    {'keep_state_and_data', % Keep state and data -> only actions
      Actions :: [action()] | action()}.
 
 
@@ -880,10 +879,6 @@ loop_event_result(
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, State, NewData, Actions);
-	{keep_state_and_data} ->
-	    loop_event_actions(
-	      Parent, Debug, S, Events, Event,
-	      State, State, Data, []);
 	{keep_state_and_data,Actions} ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 27b042c0d8..f5cbdd9a40 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1233,7 +1233,7 @@ wfor_conf(Type, Content, Data) ->
 		    {next_state,idle,Data,
 		     [{reply,From,'eh?'}]};
 		_ ->
-		    throw({keep_state_and_data})
+		    throw({keep_state_and_data,[]})
 	    end;
 	Result ->
 	    Result
-- 
cgit v1.2.3


From 63b291070d5522b5b116c8fe158497ee55149656 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 25 Feb 2016 15:45:32 +0100
Subject: Clarify documentation after Torben Hoffman's comments

---
 lib/stdlib/doc/src/gen_statem.xml | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 35b842c173..4af6732e7c 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -374,7 +374,7 @@ erlang:'!'            -----> Module:StateName/3
 	  When used in the
 	  <seealso marker="#type-action">action()</seealso>
 	  <c>{remove_event,RemoveEventPredicate}</c>,
-	  the event for which the predicate returns <c>true</c>
+	  the oldest event for which the predicate returns <c>true</c>
 	  will be removed.
 	</p>
 	<p>
@@ -441,6 +441,14 @@ erlang:'!'            -----> Module:StateName/3
 	    If the state changes the queue of incoming events
             is reset to start with the oldest postponed.
 	  </item>
+	  <item>
+	    All events inserted with
+	    <seealso marker="#type-action">
+	      <c>action() next_event</c>
+	    </seealso>
+	    are inserted in the queue to be processed before
+	    all other events.
+	  </item>
 	  <item>
 	    If the
             <seealso marker="#type-postpone">
@@ -450,7 +458,8 @@ erlang:'!'            -----> Module:StateName/3
 	      <c>timeout</c>
 	    </seealso>
 	    is set a state timer may be started or a timeout zero event
-	    may be enqueued as the newest incoming.
+	    may be enqueued as the newest incoming that is the last
+	    to process before going into <c>receive</c> for new events.
 	  </item>
 	  <item>
 	    The (possibly new)
@@ -582,16 +591,16 @@ erlang:'!'            -----> Module:StateName/3
 	    and <c><anno>EventContent</anno></c> as the next to process.
 	    This will bypass any events in the process mailbox as well
 	    as any other queued events.
+	    All <c>next_event</c> actions
+	    in the containing list are buffered and inserted
+	    after the actions have been done
+	    so the first in the list will be the first to process.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
 	    </seealso>
 	    should be used when you want to reliably distinguish
 	    an event inserted this way from any external event.
-	    If there are multiple <c>next_event</c> actions
-	    in the containing list they are buffered and all are
-	    inserted so the first in the list will be the
-	    first to process.
 	  </item>
 	  <tag><c>remove_event</c></tag>
 	  <item>
@@ -599,7 +608,11 @@ erlang:'!'            -----> Module:StateName/3
 	    that matches equal to <c><anno>EventType</anno></c>
 	    and <c><anno>EventContent</anno></c> or for which
 	    <c><anno>EventPredicate</anno></c>
-	    returns <c>true</c>.
+	    returns <c>true</c>.  Note that <c>next_event</c>
+	    and <c>postpone</c> events in the same actions list
+	    does not get into the event queue until after all actions
+	    has been done so you can not remove an event that you insert
+	    in the same actions list.  Make up your mind!
 	  </item>
 	  <tag><c>cancel_timer</c></tag>
 	  <item>
-- 
cgit v1.2.3


From cea77ca09be156669c657592bebf6efc9d5cfaee Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 25 Feb 2016 16:02:59 +0100
Subject: Write a simple example in the reference manual

---
 lib/stdlib/doc/src/gen_statem.xml | 188 +++++++++++++++++++++++++++++---------
 1 file changed, 144 insertions(+), 44 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 4af6732e7c..d50b88c561 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -91,7 +91,7 @@ erlang:'!'            -----> Module:StateName/3
       in a <c>gen_statem</c> is the callback function that is called
       for all events in this state, and is selected depending on
       <seealso marker="#type-callback_mode">callback_mode</seealso>
-      that the implementation specifies during <c>gen_statem</c> init.
+      that the implementation specifies when the the server starts.
     </p>
     <p>
       When
@@ -103,7 +103,8 @@ erlang:'!'            -----> Module:StateName/3
       </seealso>.
       This gathers all code for a specific state
       in one function and hence dispatches on state first.
-      Note that in this mode the callback function
+      Note that in this mode the fact that there is
+      a mandatory callback function
       <seealso marker="#Module:terminate/3">
         <c>Module:terminate/3</c>
       </seealso> makes the state name <c>terminate</c> unusable.
@@ -115,9 +116,8 @@ erlang:'!'            -----> Module:StateName/3
       <seealso marker="#Module:handle_event/4">
         <c>Module:handle_event/4</c>
       </seealso>.
-      This makes it easy to dispatch on state or on event as
-      you like but you will have to implement it.
-      Also be careful about which events you handle in which
+      This makes it easy to dispatch on state or on event as you desire.
+      Be careful about which events you handle in which
       states so you do not accidentally postpone one event
       forever creating an infinite busy loop.
     </p>
@@ -132,9 +132,9 @@ erlang:'!'            -----> Module:StateName/3
     </p>
     <p>
       The <c>gen_statem</c> event queue model is sufficient
-      to emulate the normal process message queue and selective receive
-      with postponing an event corresponding to not matching
-      it in a receive statement and changing states corresponding
+      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>
@@ -149,8 +149,8 @@ erlang:'!'            -----> Module:StateName/3
       <seealso marker="#type-event_type">
         <c>event_type()</c> <c>internal</c>
       </seealso>
-      that can be used for such events making it impossible
-      to mistake for an external event.
+      that 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
@@ -165,7 +165,7 @@ erlang:'!'            -----> Module:StateName/3
     <p>
       See the type
       <seealso marker="#type-transition_option">
-	<c>transition_option()</c>.
+	<c>transition_option()</c>
       </seealso>
       for the details of a state transition.
     </p>
@@ -192,7 +192,7 @@ erlang:'!'            -----> Module:StateName/3
       </seealso>) if a
       <seealso marker="#state_function">state function</seealso> or
       <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
-      specifies <c>'hibernate'</c> in the returned
+      specifies <c>hibernate</c> in the returned
       <seealso marker="#type-action"><c>Actions</c></seealso>
       list. This might be useful if the server is expected to be idle
       for a long time. However use this feature with care
@@ -202,6 +202,99 @@ erlang:'!'            -----> Module:StateName/3
     </p>
   </description>
 
+  <section>
+    <title>EXAMPLE</title>
+    <p>
+      This example shows a simple pushbutton model
+      for a toggling pushbutton implemented with
+      <seealso marker="#type-callback_mode">
+	callback_mode()
+      </seealso>
+      <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 on.
+    </p>
+    <p>This 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]).
+-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 callback mode and initial state + data.
+    %% Data is used only as a counter.
+    State = off, Data = 0,
+    {state_functions,State,Data}.
+
+
+%%% State functions
+
+off({call,Caller}, push, Data) ->
+    %% Go to 'on', increment count and reply
+    %% that the resulting status is 'on'
+    {next_state,on,Data+1,[{reply,Caller,on}]};
+off(EventType, EventContent, Data) ->
+    handle_event(EventType, EventContent, Data).
+
+on({call,Caller}, push, Data) ->
+    %% Go to 'off' and reply that the resulting status is 'off'
+    {next_state,off,Data,[{reply,Caller,off}]};
+on(EventType, EventContent, Data) ->
+    handle_event(EventType, EventContent, Data).
+
+%% Handle events common to all states
+handle_event({call,Caller}, get_count, Data) ->
+    %% Reply with the current count
+    {keep_state,Data,[{reply,Caller,Data}]};
+handle_event(_, _, Data) ->
+    %% Ignore all other events
+    {keep_state,Data}.
+    </code>
+    <p>And this 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>
+  </section>
+
   <datatypes>
     <datatype>
       <name name="server_name" />
@@ -327,7 +420,7 @@ erlang:'!'            -----> Module:StateName/3
 	  <seealso marker="#type-callback_mode">
 	    callback_mode
 	  </seealso>
-	  is <c>state_functions</c>, which is the default,
+	  is <c>state_functions</c>,
 	  the state has to be of this type.
 	</p>
       </desc>
@@ -353,11 +446,14 @@ erlang:'!'            -----> Module:StateName/3
 	<p>
 	  External events are of 3 different type:
 	  <c>{call,<anno>Caller</anno>}</c>, <c>cast</c> or <c>info</c>.
-	  Calls (synchronous) and casts (asynchronous)
+	  <seealso marker="#call/2">Calls</seealso>
+	  (synchronous) and
+	  <seealso marker="#cast/2">casts</seealso>
 	  originate from the corresponding API functions.
 	  For calls the event contain whom to reply to.
-	  Type <c>info</c> originates from normal messages sent
-	  to the <c>gen_statem</c> process.
+	  Type <c>info</c> originates from
+	  regular process messages sent
+	  to the <c>gen_statem</c>.
 	  It is also possible for the state machine
 	  implementation to insert events to itself,
 	  in particular of types
@@ -421,7 +517,8 @@ erlang:'!'            -----> Module:StateName/3
 	<p>
 	  Transition options may be set by
 	  <seealso marker="#type-action">actions</seealso>
-	  and they modify how the state transition is done:
+	  and they modify some details below in how
+	  the state transition is done:
 	</p>
 	<list type="ordered">
 	  <item>
@@ -430,12 +527,12 @@ erlang:'!'            -----> Module:StateName/3
 	    are processed in order of appearance.
 	  </item>
 	  <item>
-	    If the
+	    If
             <seealso marker="#type-postpone">
-	      <c>transition_option()</c>
+	      <c>postpone()</c>
 	    </seealso>
-            <seealso marker="#type-postpone"><c>postpone</c></seealso>
-	    is <c>true</c> the current event is postponed.
+	    is <c>true</c>
+	    the current event is postponed.
 	  </item>
 	  <item>
 	    If the state changes the queue of incoming events
@@ -450,15 +547,16 @@ erlang:'!'            -----> Module:StateName/3
 	    all other events.
 	  </item>
 	  <item>
-	    If the
-            <seealso marker="#type-postpone">
-	      <c>transition_option()</c>
-	    </seealso>
+	    If a
             <seealso marker="#type-state_timeout">
-	      <c>timeout</c>
+	      <em><c>state_timeout()</c></em>
+	    </seealso>
+	    is set through
+            <seealso marker="#type-action">
+	      <c>action() timeout</c>
 	    </seealso>
-	    is set a state timer may be started or a timeout zero event
-	    may be enqueued as the newest incoming that is the last
+	    a state timer may be started or a timeout zero event
+	    may be enqueued as the newest incoming, that is the last
 	    to process before going into <c>receive</c> for new events.
 	  </item>
 	  <item>
@@ -466,7 +564,12 @@ erlang:'!'            -----> Module:StateName/3
             <seealso marker="#state_function">state function</seealso>
             is called with the oldest enqueued event if there is any,
 	    otherwise the <c>gen_statem</c> goes into <c>receive</c>
-	    or hibernation (if the option <c>hibernate</c> is <c>true</c>)
+	    or hibernation
+	    (if
+            <seealso marker="#type-hibernate">
+	      <c>hibernate()</c>
+	    </seealso>
+	    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>
@@ -518,7 +621,7 @@ erlang:'!'            -----> Module:StateName/3
 	  Also note that it is not possible nor needed
 	  to cancel this timeout using the
 	  <seealso marker="#type-action">
-	    <c>action() cancel_timer</c>.
+	    <c>action() cancel_timer</c>
 	  </seealso>
 	  since this timeout is cancelled automatically by any other event.
 	</p>
@@ -538,25 +641,22 @@ erlang:'!'            -----> Module:StateName/3
 	<p>
 	  Actions are executed in the containing list order.
 	  The order matters for some actions such as <c>next_event</c>
-	  and <c>reply_action()</c>.  The order can in peculiar cases
-	  matter for <c>remove_event</c> with
-	  <c><anno>EventPredicate</anno></c> versus other
-	  event removal actions.
+	  and <c>reply_action()</c>.
 	</p>
 	<p>
-	  The order also matters for actions that set
+	  Actions that set
 	  <seealso marker="#type-transition_option">
 	    transition options
 	  </seealso>
-	  since setting an option overrides any previous
-	  of the same kind, so the last in the containing list wins.
+	  overrides any previous of the same kind,
+	  so the last in the containing list wins.
 	</p>
 	<taglist>
 	  <tag><c>postpone</c></tag>
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() postpone</c>
+	      <c>transition_option() postpone()</c>
 	    </seealso>
 	    for this state transition.
 	    This action is ignored when returned from
@@ -569,7 +669,7 @@ erlang:'!'            -----> Module:StateName/3
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() hibernate</c>
+	      <c>transition_option() hibernate()</c>
 	    </seealso>
 	    for this state transition.
 	  </item>
@@ -577,7 +677,7 @@ erlang:'!'            -----> Module:StateName/3
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() timeout</c>
+	      <c>transition_option() state_timeout()</c>
 	    </seealso>
 	    to <c><anno>Time</anno></c> with the
 	    <c>EventContent</c> as <c><anno>Msg</anno></c>
@@ -594,7 +694,7 @@ erlang:'!'            -----> Module:StateName/3
 	    All <c>next_event</c> actions
 	    in the containing list are buffered and inserted
 	    after the actions have been done
-	    so the first in the list will be the first to process.
+	    so that the first in the list will be the first to process.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
@@ -612,7 +712,7 @@ erlang:'!'            -----> Module:StateName/3
 	    and <c>postpone</c> events in the same actions list
 	    does not get into the event queue until after all actions
 	    has been done so you can not remove an event that you insert
-	    in the same actions list.  Make up your mind!
+	    with the same actions list.  Make up your mind!
 	  </item>
 	  <tag><c>cancel_timer</c></tag>
 	  <item>
@@ -622,7 +722,7 @@ erlang:'!'            -----> Module:StateName/3
 	    </seealso>
 	    with <c><anno>TimerRef</anno></c>,
 	    clean the process message queue from any late timeout message,
-	    and removes any late timeout message
+	    and remove any late timeout message
 	    from the <c>gen_statem</c> event queue using
 	    <c>{remove_event,<anno>EventPredicate</anno>}</c> above.
 	    This is a convenience function that saves quite some
@@ -639,7 +739,7 @@ erlang:'!'            -----> Module:StateName/3
 	  </item>
 	  <tag><c>unlink</c></tag>
 	  <item>
-	    Like <c>{cancel_timer,_}</c> above but for
+	    Like <c>cancel_timer</c> above but for
 	    <seealso marker="erts:erlang#unlink/1">
 	      <c>unlink/1</c>
 	    </seealso>
-- 
cgit v1.2.3


From 1e4831762b5ab4bd2210fc9e0a204e00dfe81b39 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 26 Feb 2016 10:35:16 +0100
Subject: Implement 'keep_state_and_data' and 'stop'

---
 lib/stdlib/doc/src/gen_statem.xml    |  7 ++++-
 lib/stdlib/src/gen_statem.erl        | 60 ++++++++++++++++++++----------------
 lib/stdlib/test/gen_statem_SUITE.erl |  4 +--
 3 files changed, 42 insertions(+), 29 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index d50b88c561..bda3ef081d 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -803,12 +803,17 @@ ok
 	  </item>
 	  <tag><c>keep_state_and_data</c></tag>
 	  <item>
-	    The <c>gen_statem</c> will keep the current state, or
+	    The <c>gen_statem</c> will keep the current state or
 	    do a state transition to the current state if you like,
 	    keep the current server data,
 	    and execute all <c><anno>Actions</anno></c>
 	  </item>
 	</taglist>
+	<p>
+	  All these terms are tuples or atoms and this property
+	  will hold in any future version of <c>gen_statem</c>,
+	  just in case you need such a promise.
+	</p>
       </desc>
     </datatype>
   </datatypes>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index e6ad7ab0be..16c296794f 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -135,32 +135,34 @@
 	 Caller :: caller(), Reply :: term()}.
 
 -type state_callback_result() ::
-    {'stop', % Stop the server
-     Reason :: term()} |
-    {'stop', % Stop the server
-     Reason :: term(),
-     NewData :: data()} |
-    {'stop_and_reply', % Reply then stop the server
-     Reason :: term(),
-     Replies :: [reply_action()] | reply_action()} |
-    {'stop_and_reply', % Reply then stop the server
-     Reason :: term(),
-     Replies :: [reply_action()] | reply_action(),
-     NewData :: data()} |
-    {'next_state', % {next_state,NewState,NewData,[]}
-     NewState :: state(),
-     NewData :: data()} |
-    {'next_state', % State transition, maybe to the same state
-     NewState :: state(),
-     NewData :: data(),
-     Actions :: [action()] | action()} |
-    {'keep_state', % {keep_state,NewData,[]}
-     NewData :: data()} |
-    {'keep_state', % Keep state, change data
-     NewData :: data(),
-     Actions :: [action()] | action()} |
-    {'keep_state_and_data', % Keep state and data -> only actions
-     Actions :: [action()] | action()}.
+	'stop' | % {stop,normal}
+	{'stop', % Stop the server
+	 Reason :: term()} |
+	{'stop', % Stop the server
+	 Reason :: term(),
+	 NewData :: data()} |
+	{'stop_and_reply', % Reply then stop the server
+	 Reason :: term(),
+	 Replies :: [reply_action()] | reply_action()} |
+	{'stop_and_reply', % Reply then stop the server
+	 Reason :: term(),
+	 Replies :: [reply_action()] | reply_action(),
+	 NewData :: data()} |
+	{'next_state', % {next_state,NewState,NewData,[]}
+	 NewState :: state(),
+	 NewData :: data()} |
+	{'next_state', % State transition, maybe to the same state
+	 NewState :: state(),
+	 NewData :: data(),
+	 Actions :: [action()] | action()} |
+	{'keep_state', % {keep_state,NewData,[]}
+	 NewData :: data()} |
+	{'keep_state', % Keep state, change data
+	 NewData :: data(),
+	 Actions :: [action()] | action()} |
+	'keep_state_and_data' | % {keep_state_and_data,[]}
+	{'keep_state_and_data', % Keep state and data -> only actions
+	 Actions :: [action()] | action()}.
 
 
 %% The state machine init function.  It is called only once and
@@ -841,6 +843,8 @@ loop_event_result(
   #{state := State, data := Data} = S,
   Events, Event, Result) ->
     case Result of
+	stop ->
+	    ?TERMINATE(exit, normal, Debug, S, [Event|Events]);
 	{stop,Reason} ->
 	    ?TERMINATE(exit, Reason, Debug, S, [Event|Events]);
 	{stop,Reason,NewData} ->
@@ -879,6 +883,10 @@ loop_event_result(
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, State, NewData, Actions);
+	keep_state_and_data ->
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, State, Data, []);
 	{keep_state_and_data,Actions} ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index f5cbdd9a40..09b309c36f 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1233,7 +1233,7 @@ wfor_conf(Type, Content, Data) ->
 		    {next_state,idle,Data,
 		     [{reply,From,'eh?'}]};
 		_ ->
-		    throw({keep_state_and_data,[]})
+		    throw(keep_state_and_data)
 	    end;
 	Result ->
 	    Result
@@ -1334,7 +1334,7 @@ handle_common_events(cast, {get,Pid}, State, Data) ->
 handle_common_events({call,From}, stop, _, Data) ->
     {stop_and_reply,normal,[{reply,From,stopped}],Data};
 handle_common_events(cast, stop, _, _) ->
-    {stop,normal};
+    stop;
 handle_common_events({call,From}, {stop,Reason}, _, Data) ->
     {stop_and_reply,Reason,{reply,From,stopped},Data};
 handle_common_events(cast, {stop,Reason}, _, _) ->
-- 
cgit v1.2.3


From efda33e83f2bbc666f6ec261d54ad95c38acbc36 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 26 Feb 2016 10:51:53 +0100
Subject: Allow actions without containing list

Type check atom state as early as possible
---
 lib/stdlib/src/gen_statem.erl        | 21 ++++++++++++++++-----
 lib/stdlib/test/gen_statem_SUITE.erl |  6 +++---
 2 files changed, 19 insertions(+), 8 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 16c296794f..83de4114a7 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -571,7 +571,9 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
     case Result of
 	{CallbackMode,State,Data} ->
 	    case callback_mode(CallbackMode) of
-		true ->
+		true
+		  when CallbackMode =:= state_functions, is_atom(State);
+		       CallbackMode =/= state_functions ->
 		    proc_lib:init_ack(Starter, {ok,self()}),
 		    enter(
 		      Module, Opts, CallbackMode, State, Data,
@@ -840,7 +842,7 @@ loop_events(
 %% Interpret all callback return value variants
 loop_event_result(
   Parent, Debug,
-  #{state := State, data := Data} = S,
+  #{callback_mode := CallbackMode, state := State, data := Data} = S,
   Events, Event, Result) ->
     case Result of
 	stop ->
@@ -866,12 +868,15 @@ loop_event_result(
 		  exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
 	    %% Since we got back here Replies was bad
 	    terminate(Class, NewReason, Stacktrace, NewDebug, NewS, Q);
-	{next_state,NewState,NewData} ->
+	{next_state,NewState,NewData}
+	  when CallbackMode =:= state_functions, is_atom(NewState);
+	       CallbackMode =/= state_functions ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, []);
 	{next_state,NewState,NewData,Actions}
-	  when is_list(Actions) ->
+	  when CallbackMode =:= state_functions, is_atom(NewState);
+	       CallbackMode =/= state_functions ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions);
@@ -900,7 +905,13 @@ loop_event_actions(
   Parent, Debug, S, Events, Event, State, NewState, NewData, Actions) ->
     loop_event_actions(
       Parent, Debug, S, Events, Event, State, NewState, NewData,
-      false, false, undefined, [], Actions).
+      false, false, undefined, [],
+      if
+	  is_list(Actions) ->
+	      Actions;
+	  true ->
+	      [Actions]
+      end).
 %%
 loop_event_actions(
   Parent, Debug, #{postponed := P0} = S, Events, Event,
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 09b309c36f..0429c0e5f4 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1178,7 +1178,7 @@ idle({call,From}, {delayed_answer,T}, Data) ->
     end;
 idle({call,From}, {timeout,Time}, _Data) ->
     {next_state,timeout,{From,Time},
-     [{timeout,Time,idle}]};
+     {timeout,Time,idle}};
 idle(Type, Content, Data) ->
     case handle_common_events(Type, Content, idle, Data) of
 	undefined ->
@@ -1220,7 +1220,7 @@ timeout3(_, _, Data) ->
 
 wfor_conf({call,From}, confirm, Data) ->
     {next_state,connected,Data,
-     [{reply,From,yes}]};
+     {reply,From,yes}};
 wfor_conf(cast, {ping,_,_}, _) ->
     {keep_state_and_data,[postpone]};
 wfor_conf(cast, confirm, Data) ->
@@ -1241,7 +1241,7 @@ wfor_conf(Type, Content, Data) ->
 
 connected({call,From}, {msg,Ref}, Data) ->
     {keep_state,Data,
-     [{reply,From,{ack,Ref}}]};
+     {reply,From,{ack,Ref}}};
 connected(cast, {msg,From,Ref}, Data) ->
     From ! {ack,Ref},
     {keep_state,Data};
-- 
cgit v1.2.3


From 07790dfcd4c5706878e8562365e2418021e67056 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 26 Feb 2016 11:58:47 +0100
Subject: Optimize postponed handling

---
 lib/stdlib/src/gen_statem.erl | 187 +++++++++++++++++++++++-------------------
 1 file changed, 101 insertions(+), 86 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 83de4114a7..8f058cc3a8 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -903,108 +903,63 @@ loop_event_result(
 
 loop_event_actions(
   Parent, Debug, S, Events, Event, State, NewState, NewData, Actions) ->
+    Postpone = false, % Shall we postpone this event, true or false
+    Hibernate = false,
+    Timeout = undefined,
+    NextEvents = [],
+    P = false, % The postponed list or false if unchanged
     loop_event_actions(
       Parent, Debug, S, Events, Event, State, NewState, NewData,
-      false, false, undefined, [],
       if
 	  is_list(Actions) ->
 	      Actions;
 	  true ->
 	      [Actions]
-      end).
+      end,
+      Postpone, Hibernate, Timeout, NextEvents, P).
 %%
 loop_event_actions(
-  Parent, Debug, #{postponed := P0} = S, Events, Event,
-  State, NewState, NewData,
-  Postpone, Hibernate, Timeout, NextEvents, []) ->
-    P1 = % Move current event to postponed if Postpone
-	case Postpone of
-	    true ->
-		[Event|P0];
-	    false ->
-		P0
-	end,
-    {Timer,Q1} =
-	case Timeout of
-	    undefined ->
-		{undefined,Events};
-	    {timeout,0,Msg} ->
-		%% Pretend the timeout has just been received
-		{undefined,Events ++ [{timeout,Msg}]};
-	    {timeout,Time,Msg} ->
-		{erlang:start_timer(Time, self(), Msg),
-		Events}
-	end,
-    {Q2,P} = % Move all postponed events to queue if state change
-	if
-	    NewState =:= State ->
-		{Q1,P1};
-	    true ->
-		{lists:reverse(P1, Q1),[]}
-	end,
-    %% Place next events first in queue
-    Q = lists:reverse(NextEvents, Q2),
-    %%
-    NewDebug =
-	sys_debug(
-	  Debug, S,
-	  case Postpone of
-	      true ->
-		  {postpone,Event,NewState};
-	      false ->
-		  {consume,Event,NewState}
-	  end),
-    %% Loop to top; process next event
-    loop_events(
-      Parent, NewDebug,
-      S#{
-	state := NewState,
-	data := NewData,
-	timer := Timer,
-	hibernate := Hibernate,
-	postponed := P},
-      Q, Timer);
-loop_event_actions(
-  Parent, Debug, S, Events, Event, State, NewState, NewData,
-  Postpone, Hibernate, Timeout, NextEvents, [Action|Actions]) ->
+  Parent, Debug, S, Events, Event,
+  State, NewState, NewData, [Action|Actions],
+  Postpone, Hibernate, Timeout, NextEvents, P) ->
     case Action of
 	%% Set options
 	postpone ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData,
-	      true, Hibernate, Timeout, NextEvents, Actions);
+	      State, NewState, NewData, Actions,
+	      true, Hibernate, Timeout, NextEvents, P);
 	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData,
-	      NewPostpone, Hibernate, Timeout, NextEvents, Actions);
+	      State, NewState, NewData, Actions,
+	      NewPostpone, Hibernate, Timeout, NextEvents, P);
 	{postpone,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
 	hibernate ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData,
-	      Postpone, true, Timeout, NextEvents, Actions);
+	      State, NewState, NewData, Actions,
+	      Postpone, true, Timeout, NextEvents, P);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData,
-	      Postpone, NewHibernate, Timeout, NextEvents, Actions);
+	      State, NewState, NewData, Actions,
+	      Postpone, NewHibernate, Timeout, NextEvents, P);
 	{hibernate,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
 	{timeout,infinity,_} -> % Clear timer - it will never trigger
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData,
-	      Postpone, Hibernate, undefined, NextEvents, Actions);
+	      State, NewState, NewData, Actions,
+	      Postpone, Hibernate, undefined, NextEvents, P);
 	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData,
-	      Postpone, Hibernate, NewTimeout, NextEvents, Actions);
+	      State, NewState, NewData, Actions,
+	      Postpone, Hibernate, NewTimeout, NextEvents, P);
 	{timeout,_,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
@@ -1015,8 +970,8 @@ loop_event_actions(
 		    NewDebug = do_reply(Debug, S, Caller, Reply),
 		    loop_event_actions(
 		      Parent, NewDebug, S, Events, Event,
-		      State, NewState, NewData,
-		      Postpone, Hibernate, Timeout, NextEvents, Actions);
+		      State, NewState, NewData, Actions,
+		      Postpone, Hibernate, Timeout, NextEvents, P);
 		false ->
 		    ?TERMINATE(
 		       error, {bad_action,Action}, Debug, S, [Event|Events])
@@ -1026,9 +981,9 @@ loop_event_actions(
 		true ->
 		    loop_event_actions(
 		      Parent, Debug, S, Events, Event,
-		      State, NewState, NewData,
+		      State, NewState, NewData, Actions,
 		      Postpone, Hibernate, Timeout,
-		      [{Type,Content}|NextEvents], Actions);
+		      [{Type,Content}|NextEvents], P);
 		false ->
 		    ?TERMINATE(
 		       error, {bad_action,Action}, Debug, S, [Event|Events])
@@ -1039,33 +994,36 @@ loop_event_actions(
 		false ->
 		    loop_event_actions(
 		      Parent, Debug, S, Events, Event,
-		      State, NewState, NewData,
-		      Postpone, Hibernate, Timeout, NextEvents, Actions);
+		      State, NewState, NewData, Actions,
+		      Postpone, Hibernate, Timeout, NextEvents, P);
 		undefined ->
 		    ?TERMINATE(
 		       error, {bad_action,Action}, Debug, S, [Event|Events]);
 		RemoveFun when is_function(RemoveFun, 2) ->
-		    #{postponed := P} = S,
-		    case remove_event(RemoveFun, Events, P) of
+		    P0 =
+			case P of
+			    false ->
+				maps:get(postponed, S);
+			    _ ->
+				P
+			end,
+		    case remove_event(RemoveFun, Events, P0) of
 			false ->
 			    loop_event_actions(
 			      Parent, Debug, S, Events, Event,
-			      State, NewState, NewData,
-			      Postpone, Hibernate, Timeout, NextEvents,
-			      Actions);
+			      State, NewState, NewData, Actions,
+			      Postpone, Hibernate, Timeout, NextEvents, P);
 			{NewEvents,false} ->
 			    loop_event_actions(
 			      Parent, Debug, S, NewEvents, Event,
-			      State, NewState, NewData,
-			      Postpone, Hibernate, Timeout, NextEvents,
-			      Actions);
+			      State, NewState, NewData, Actions,
+			      Postpone, Hibernate, Timeout, NextEvents, P);
 			{false,NewP} ->
-			    NewS = S#{postponed := NewP},
 			    loop_event_actions(
-			      Parent, Debug, NewS, Events, Event,
-			      State, NewState, NewData,
+			      Parent, Debug, S, Events, Event,
+			      State, NewState, NewData, Actions,
 			      Postpone, Hibernate, Timeout, NextEvents,
-			      Actions);
+			      NewP);
 			[Class,Reason,Stacktrace] ->
 			    terminate(
 			      Class, Reason, Stacktrace,
@@ -1075,7 +1033,64 @@ loop_event_actions(
 		    terminate(
 		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
 	    end
-    end.
+    end;
+loop_event_actions(
+  Parent, Debug, S, Events, Event, State, NewState, NewData, [],
+  Postpone, Hibernate, Timeout, NextEvents, P) ->
+    P0 =
+	case P of
+	    false ->
+		maps:get(postponed, S);
+	    _ ->
+		P
+	end,
+    P1 = % Move current event to postponed if Postpone
+	case Postpone of
+	    true ->
+		[Event|P0];
+	    false ->
+		P0
+	end,
+    {Timer,Q1} =
+	case Timeout of
+	    undefined ->
+		{undefined,Events};
+	    {timeout,0,Msg} ->
+		%% Pretend the timeout has just been received
+		{undefined,Events ++ [{timeout,Msg}]};
+	    {timeout,Time,Msg} ->
+		{erlang:start_timer(Time, self(), Msg),
+		Events}
+	end,
+    {Q2,P2} = % Move all postponed events to queue if state change
+	if
+	    NewState =:= State ->
+		{Q1,P1};
+	    true ->
+		{lists:reverse(P1, Q1),[]}
+	end,
+    %% Place next events first in queue
+    Q3 = lists:reverse(NextEvents, Q2),
+    %%
+    NewDebug =
+	sys_debug(
+	  Debug, S,
+	  case Postpone of
+	      true ->
+		  {postpone,Event,NewState};
+	      false ->
+		  {consume,Event,NewState}
+	  end),
+    %% Loop to top; process next event
+    loop_events(
+      Parent, NewDebug,
+      S#{
+	state := NewState,
+	data := NewData,
+	timer := Timer,
+	hibernate := Hibernate,
+	postponed := P2},
+      Q3, Timer).
 
 %%---------------------------------------------------------------------------
 %% Server helpers
-- 
cgit v1.2.3


From ded8d9e3ec0ba6481d80e28f6057e6ccf5a6d575 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 26 Feb 2016 14:35:25 +0100
Subject: ct:ify test suite

---
 lib/stdlib/test/gen_statem_SUITE.erl | 165 ++++++++++++++++++-----------------
 1 file changed, 86 insertions(+), 79 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 0429c0e5f4..321573b721 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -26,7 +26,9 @@
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-suite() -> [{ct_hooks,[ts_install_cth]}].
+suite() ->
+    [{ct_hooks,[ts_install_cth]},
+     {timetrap,{minutes,1}}].
 
 all() ->
     [{group, start},
@@ -82,27 +84,24 @@ end_per_group(_GroupName, Config) ->
     Config.
 
 init_per_testcase(_CaseName, Config) ->
-    ?t:messages_get(),
-    Dog = ?t:timetrap(?t:minutes(1)),
+    flush(),
 %%%    dbg:tracer(),
 %%%    dbg:p(all, c),
 %%%    dbg:tpl(gen_statem, cx),
 %%%    dbg:tpl(proc_lib, cx),
 %%%    dbg:tpl(gen, cx),
 %%%    dbg:tpl(sys, cx),
-    [{watchdog, Dog} | Config].
+    Config.
 
 end_per_testcase(_CaseName, Config) ->
 %%%    dbg:stop(),
-    Dog = ?config(watchdog, Config),
-    test_server:timetrap_cancel(Dog),
     Config.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -define(EXPECT_FAILURE(Code, Reason),
 	try begin Code end of
-	    _ ->
-		?t:fail()
+	    Reason ->
+		ct:fail({unexpected,Reason})
 	catch
 	    error:Reason -> Reason;
 	    exit:Reason -> Reason
@@ -110,7 +109,7 @@ end_per_testcase(_CaseName, Config) ->
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %% anonymous
-start1(Config) when is_list(Config) ->
+start1(Config) ->
     %%OldFl = process_flag(trap_exit, true),
 
     {ok,Pid0} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
@@ -125,7 +124,7 @@ start1(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% anonymous w. shutdown
-start2(Config) when is_list(Config) ->
+start2(Config) ->
     %% Dont link when shutdown
     {ok,Pid0} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     ok = do_func_test(Pid0),
@@ -135,7 +134,7 @@ start2(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% anonymous with timeout
-start3(Config) when is_list(Config) ->
+start3(Config) ->
     %%OldFl = process_flag(trap_exit, true),
 
     {ok,Pid0} =
@@ -152,7 +151,7 @@ start3(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% anonymous with ignore
-start4(Config) when is_list(Config) ->
+start4(Config) ->
     OldFl = process_flag(trap_exit, true),
 
     ignore = gen_statem:start(?MODULE, start_arg(Config, ignore), []),
@@ -161,8 +160,7 @@ start4(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% anonymous with stop
-start5(suite) -> [];
-start5(Config) when is_list(Config) ->
+start5(Config) ->
     OldFl = process_flag(trap_exit, true),
 
     {error,stopped} = gen_statem:start(?MODULE, start_arg(Config, stop), []),
@@ -171,7 +169,7 @@ start5(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% anonymous linked
-start6(Config) when is_list(Config) ->
+start6(Config) ->
     {ok,Pid} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
     ok = do_func_test(Pid),
     ok = do_sync_func_test(Pid),
@@ -180,7 +178,7 @@ start6(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% global register linked
-start7(Config) when is_list(Config) ->
+start7(Config) ->
     STM = {global,my_stm},
 
     {ok,Pid} =
@@ -200,7 +198,7 @@ start7(Config) when is_list(Config) ->
 
 
 %% local register
-start8(Config) when is_list(Config) ->
+start8(Config) ->
     %%OldFl = process_flag(trap_exit, true),
     Name = my_stm,
     STM = {local,Name},
@@ -220,7 +218,7 @@ start8(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% local register linked
-start9(Config) when is_list(Config) ->
+start9(Config) ->
     %%OldFl = process_flag(trap_exit, true),
     Name = my_stm,
     STM = {local,Name},
@@ -240,7 +238,7 @@ start9(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% global register
-start10(Config) when is_list(Config) ->
+start10(Config) ->
     STM = {global,my_stm},
 
     {ok,Pid} =
@@ -259,7 +257,7 @@ start10(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% Stop registered processes
-start11(Config) when is_list(Config) ->
+start11(Config) ->
     Name = my_stm,
     LocalSTM = {local,Name},
     GlobalSTM = {global,Name},
@@ -278,14 +276,14 @@ start11(Config) when is_list(Config) ->
     receive after 1 -> true end,
     Result =
 	gen_statem:start(GlobalSTM, ?MODULE, start_arg(Config, []), []),
-    io:format("Result = ~p~n",[Result]),
+    ct:log("Result = ~p~n",[Result]),
     {ok,_Pid3} = Result,
     stop_it(GlobalSTM),
 
     ok = verify_empty_msgq().
 
 %% Via register linked
-start12(Config) when is_list(Config) ->
+start12(Config) ->
     dummy_via:reset(),
     VIA = {via,dummy_via,my_stm},
 
@@ -378,19 +376,20 @@ stop7(Config) ->
 
 %% Anonymous on remote node
 stop8(Config) ->
-    {ok,Node} = ?t:start_node(gen_statem_stop8, slave, []),
+    Node = gen_statem_stop8,
+    {ok,NodeName} = ct_slave:start(Node),
     Dir = filename:dirname(code:which(?MODULE)),
-    rpc:call(Node, code, add_path, [Dir]),
+    rpc:call(NodeName, code, add_path, [Dir]),
     {ok,Pid} =
 	rpc:call(
-	  Node, gen_statem,start,
+	  NodeName, gen_statem,start,
 	  [?MODULE,start_arg(Config, []),[]]),
     ok = gen_statem:stop(Pid),
-    false = rpc:call(Node, erlang, is_process_alive, [Pid]),
+    false = rpc:call(NodeName, erlang, is_process_alive, [Pid]),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason1),
-    true = ?t:stop_node(Node),
-    {{nodedown,Node},{sys,terminate,_}} =
+    {ok,NodeName} = ct_slave:stop(Node),
+    {{nodedown,NodeName},{sys,terminate,_}} =
 	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason2),
     ok.
 
@@ -398,46 +397,48 @@ stop8(Config) ->
 stop9(Config) ->
     Name = to_stop,
     LocalSTM = {local,Name},
-    {ok,Node} = ?t:start_node(gen_statem__stop9, slave, []),
-    STM = {Name,Node},
+    Node = gen_statem__stop9,
+    {ok,NodeName} = ct_slave:start(Node),
+    STM = {Name,NodeName},
     Dir = filename:dirname(code:which(?MODULE)),
-    rpc:call(Node, code, add_path, [Dir]),
+    rpc:call(NodeName, code, add_path, [Dir]),
     {ok,Pid} =
 	rpc:call(
-	  Node, gen_statem, start,
+	  NodeName, gen_statem, start,
 	  [LocalSTM,?MODULE,start_arg(Config, []),[]]),
     ok = gen_statem:stop(STM),
-    undefined = rpc:call(Node,erlang,whereis,[Name]),
-    false = rpc:call(Node,erlang,is_process_alive,[Pid]),
+    undefined = rpc:call(NodeName,erlang,whereis,[Name]),
+    false = rpc:call(NodeName,erlang,is_process_alive,[Pid]),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(STM), Reason1),
-    true = ?t:stop_node(Node),
-    {{nodedown,Node},{sys,terminate,_}} =
+    {ok,NodeName} = ct_slave:stop(Node),
+    {{nodedown,NodeName},{sys,terminate,_}} =
 	?EXPECT_FAILURE(gen_statem:stop(STM), Reason2),
     ok.
 
 %% Globally registered name on remote node
 stop10(Config) ->
+    Node = gen_statem_stop10,
     STM = {global,to_stop},
-    {ok,Node} = ?t:start_node(gen_statem_stop10, slave, []),
+    {ok,NodeName} = ct_slave:start(Node),
     Dir = filename:dirname(code:which(?MODULE)),
-    rpc:call(Node,code,add_path,[Dir]),
+    rpc:call(NodeName,code,add_path,[Dir]),
     {ok,Pid} =
 	rpc:call(
-	  Node, gen_statem, start,
+	  NodeName, gen_statem, start,
 	  [STM,?MODULE,start_arg(Config, []),[]]),
     global:sync(),
     ok = gen_statem:stop(STM),
-    false = rpc:call(Node, erlang, is_process_alive, [Pid]),
+    false = rpc:call(NodeName, erlang, is_process_alive, [Pid]),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(STM), Reason1),
-    true = ?t:stop_node(Node),
+    {ok,NodeName} = ct_slave:stop(Node),
     noproc =
 	?EXPECT_FAILURE(gen_statem:stop(STM), Reason2),
     ok.
 
 %% Check that time outs in calls work
-abnormal1(Config) when is_list(Config) ->
+abnormal1(Config) ->
     Name = abnormal1,
     LocalSTM = {local,Name},
 
@@ -455,7 +456,7 @@ abnormal1(Config) when is_list(Config) ->
 
 %% Check that bad return values makes the stm crash. Note that we must
 %% trap exit since we must link to get the real bad_return_ error
-abnormal2(Config) when is_list(Config) ->
+abnormal2(Config) ->
     OldFl = process_flag(trap_exit, true),
     {ok,Pid} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
 
@@ -465,13 +466,13 @@ abnormal2(Config) when is_list(Config) ->
     receive
 	{'EXIT',Pid,{bad_return_value,badreturn}} -> ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     process_flag(trap_exit, OldFl),
     ok = verify_empty_msgq().
 
-shutdown(Config) when is_list(Config) ->
+shutdown(Config) ->
     process_flag(trap_exit, true),
 
     {ok,Pid0} = gen_statem:start_link(?MODULE, start_arg(Config, []), []),
@@ -486,15 +487,15 @@ shutdown(Config) when is_list(Config) ->
 
     receive
 	Any ->
-	    io:format("Unexpected: ~p", [Any]),
-	    ?t:fail()
+	    ct:log("Unexpected: ~p", [Any]),
+	    ct:fail({unexpected,Any})
     after 500 ->
 	    ok
     end.
 
 
 
-sys1(Config) when is_list(Config) ->
+sys1(Config) ->
     {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     {status, Pid, {module,gen_statem}, _} = sys:get_status(Pid),
     sys:suspend(Pid),
@@ -507,7 +508,7 @@ sys1(Config) when is_list(Config) ->
 	  end),
     receive
 	{Tag,_} ->
-	    ?t:fail()
+	    ct:fail(should_be_suspended)
     after 3000 ->
 	    exit(Caller, ok)
     end,
@@ -517,7 +518,7 @@ sys1(Config) when is_list(Config) ->
     sys:resume(Pid),
     stop_it(Pid).
 
-call_format_status(Config) when is_list(Config) ->
+call_format_status(Config) ->
     {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     Status = sys:get_status(Pid),
     {status,Pid,_Mod,[_PDict,running,_,_, Data]} = Status,
@@ -573,7 +574,7 @@ call_format_status(Config) when is_list(Config) ->
 
 
 
-error_format_status(Config) when is_list(Config) ->
+error_format_status(Config) ->
     error_logger_forwarder:register(),
     OldFl = process_flag(trap_exit, true),
     Data = "called format_status",
@@ -593,10 +594,10 @@ error_format_status(Config) when is_list(Config) ->
 	    ok;
 	Other when is_tuple(Other), element(1, Other) =:= error ->
 	    error_logger_forwarder:unregister(),
-	    ?t:fail({unexpected,Other})
+	    ct:fail({unexpected,Other})
     after 1000 ->
 	    error_logger_forwarder:unregister(),
-	    ?t:fail()
+	    ct:fail(timeout)
     end,
     process_flag(trap_exit, OldFl),
     error_logger_forwarder:unregister(),
@@ -609,7 +610,7 @@ error_format_status(Config) when is_list(Config) ->
     end,
     ok = verify_empty_msgq().
 
-terminate_crash_format(Config) when is_list(Config) ->
+terminate_crash_format(Config) ->
     error_logger_forwarder:register(),
     OldFl = process_flag(trap_exit, true),
     Data = crash_terminate,
@@ -629,10 +630,10 @@ terminate_crash_format(Config) when is_list(Config) ->
 	    ok;
 	Other when is_tuple(Other), element(1, Other) =:= error ->
 	    error_logger_forwarder:unregister(),
-	    ?t:fail({unexpected,Other})
+	    ct:fail({unexpected,Other})
     after 1000 ->
 	    error_logger_forwarder:unregister(),
-	    ?t:fail()
+	    ct:fail(timeout)
     end,
     process_flag(trap_exit, OldFl),
     error_logger_forwarder:unregister(),
@@ -646,7 +647,7 @@ terminate_crash_format(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 
-get_state(Config) when is_list(Config) ->
+get_state(Config) ->
     State = self(),
     {ok,Pid} =
 	gen_statem:start(
@@ -675,7 +676,7 @@ get_state(Config) when is_list(Config) ->
     stop_it(Pid3),
     ok = verify_empty_msgq().
 
-replace_state(Config) when is_list(Config) ->
+replace_state(Config) ->
     State = self(),
     {ok, Pid} =
 	gen_statem:start(
@@ -707,7 +708,7 @@ replace_state(Config) when is_list(Config) ->
     ok = verify_empty_msgq().
 
 %% Hibernation
-hibernate(Config) when is_list(Config) ->
+hibernate(Config) ->
     OldFl = process_flag(trap_exit, true),
 
     {ok,Pid0} =
@@ -718,7 +719,7 @@ hibernate(Config) when is_list(Config) ->
     receive
 	{'EXIT',Pid0,normal} -> ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     {ok,Pid} =
@@ -801,7 +802,7 @@ hibernate(Config) when is_list(Config) ->
     receive
 	{'EXIT',Pid,normal} -> ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
     ok = verify_empty_msgq().
 
@@ -810,8 +811,8 @@ is_in_erlang_hibernate(Pid) ->
     is_in_erlang_hibernate_1(200, Pid).
 
 is_in_erlang_hibernate_1(0, Pid) ->
-    io:format("~p\n", [erlang:process_info(Pid, current_function)]),
-    ?t:fail(not_in_erlang_hibernate_3);
+    ct:log("~p\n", [erlang:process_info(Pid, current_function)]),
+    ct:fail(not_in_erlang_hibernate_3);
 is_in_erlang_hibernate_1(N, Pid) ->
     {current_function,MFA} = erlang:process_info(Pid, current_function),
     case MFA of
@@ -827,8 +828,8 @@ is_not_in_erlang_hibernate(Pid) ->
     is_not_in_erlang_hibernate_1(200, Pid).
 
 is_not_in_erlang_hibernate_1(0, Pid) ->
-    io:format("~p\n", [erlang:process_info(Pid, current_function)]),
-    ?t:fail(not_in_erlang_hibernate_3);
+    ct:log("~p\n", [erlang:process_info(Pid, current_function)]),
+    ct:fail(not_in_erlang_hibernate_3);
 is_not_in_erlang_hibernate_1(N, Pid) ->
     {current_function,MFA} = erlang:process_info(Pid, current_function),
     case MFA of
@@ -839,10 +840,8 @@ is_not_in_erlang_hibernate_1(N, Pid) ->
 	    ok
     end.
 
-%%sys1(suite) -> [];
-%%sys1(_) ->
 
-enter_loop(Config) when is_list(Config) ->
+enter_loop(_Config) ->
     OldFlag = process_flag(trap_exit, true),
 
     dummy_via:reset(),
@@ -856,7 +855,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid1a,normal} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Unregistered process + {local,Name}
@@ -866,7 +865,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid1b,process_not_registered} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Globally registered process + {global,Name}
@@ -878,7 +877,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid2a,normal} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Unregistered process + {global,Name}
@@ -888,7 +887,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid2b,process_not_registered_globally} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Unregistered process + no name
@@ -900,7 +899,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid3,normal} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Process not started using proc_lib
@@ -913,7 +912,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid4,process_was_not_started_by_proc_lib} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Make sure I am the parent, ie that ordering a shutdown will
@@ -926,7 +925,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid5,shutdown} ->
 	    ok
     after 5000 ->
-	    ?t:fail(gen_statem_did_not_die)
+	    ct:fail(gen_statem_did_not_die)
     end,
 
     %% Make sure gen_statem:enter_loop does not accept {local,Name}
@@ -939,7 +938,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid6a,process_not_registered} ->
 	    ok
     after 1000 ->
-	    ?t:fail(gen_statem_started)
+	    ct:fail(gen_statem_started)
     end,
     unregister(armitage),
 
@@ -953,7 +952,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid6b,process_not_registered_globally} ->
 	    ok
     after 1000 ->
-	    ?t:fail(gen_statem_started)
+	    ct:fail(gen_statem_started)
     end,
     global:unregister_name(armitage),
 
@@ -964,7 +963,7 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT',Pid6c,{process_not_registered_via,dummy_via}} ->
 	    ok
     after 1000 ->
-	    ?t:fail(
+	    ct:fail(
 	      {gen_statem_started,
 	       process_info(self(), messages)})
     end,
@@ -1105,7 +1104,7 @@ do_sync_disconnect(STM) ->
 
 verify_empty_msgq() ->
     receive after 500 -> ok end,
-    [] = ?t:messages_get(),
+    [] = flush(),
     ok.
 
 start_arg(Config, Arg) ->
@@ -1388,3 +1387,11 @@ format_status(terminate, [_Pdict,State,Data]) ->
     {formatted,State,Data};
 format_status(normal, [_Pdict,_State,_Data]) ->
     [format_status_called].
+
+flush() ->
+    receive
+	Msg ->
+	    [Msg|flush()]
+    after 0 ->
+	    []
+    end.
-- 
cgit v1.2.3


From df457111fbb82d160605f45c43552249cd6f8ac5 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 26 Feb 2016 14:52:24 +0100
Subject: Test the order for multiple next_event

---
 lib/stdlib/test/gen_statem_SUITE.erl | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 321573b721..268b45a0e7 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -44,10 +44,10 @@ all() ->
 groups() ->
     [{start, [],
       [start1, start2, start3, start4, start5, start6, start7,
-       start8, start9, start10, start11, start12]},
+       start8, start9, start10, start11, start12, next_events]},
      {start_handle_event, [],
       [start1, start2, start3, start4, start5, start6, start7,
-       start8, start9, start10, start11, start12]},
+       start8, start9, start10, start11, start12, next_events]},
      {stop, [],
       [stop1, stop2, stop3, stop4, stop5, stop6, stop7, stop8, stop9, stop10]},
      {stop_handle_event, [],
@@ -998,6 +998,18 @@ enter_loop(Reg1, Reg2) ->
 	      ?MODULE, [], CallbackMode, state0, [])
     end.
 
+
+%% Test the order for multiple {next_event,T,C}
+next_events(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
+    ok = gen_statem:cast(Pid, next_event),
+    {state,next_events,[]} = gen_statem:call(Pid, get),
+    ok = gen_statem:stop(Pid),
+    false = erlang:is_process_alive(Pid),
+    noproc =
+	?EXPECT_FAILURE(gen_statem:stop(Pid), Reason).
+
+
 %%
 %% Functionality check
 %%
@@ -1178,6 +1190,11 @@ idle({call,From}, {delayed_answer,T}, Data) ->
 idle({call,From}, {timeout,Time}, _Data) ->
     {next_state,timeout,{From,Time},
      {timeout,Time,idle}};
+idle(cast, next_event, _Data) ->
+    {next_state,next_events,[a,b,c],
+     [{next_event,internal,a},
+      {next_event,internal,b},
+      {next_event,internal,c}]};
 idle(Type, Content, Data) ->
     case handle_common_events(Type, Content, idle, Data) of
 	undefined ->
@@ -1323,6 +1340,16 @@ hiber_wakeup(Type, Content, Data) ->
 	    Result
     end.
 
+next_events(internal, Msg, [Msg|Msgs]) ->
+    {keep_state,Msgs};
+next_events(Type, Content, Data) ->
+    case handle_common_events(Type, Content, next_events, Data) of
+	undefined ->
+	    {keep_state,Data};
+	Result ->
+	    Result
+    end.
+
 
 handle_common_events({call,From}, get, State, Data) ->
     {keep_state,Data,
-- 
cgit v1.2.3


From c2b8e6cdbc884e93cabe78e9fc9dcc040eb828eb Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 26 Feb 2016 16:19:55 +0100
Subject: Relax caller() type check and cleanup

---
 lib/stdlib/src/gen_statem.erl | 56 ++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 27 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 8f058cc3a8..29848d13a3 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -249,7 +249,7 @@ callback_mode(CallbackMode) ->
 	    false
     end.
 %%
-caller({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
+caller({Pid,_}) when is_pid(Pid) ->
     true;
 caller(_) ->
     false.
@@ -279,7 +279,7 @@ event_type(Type) ->
 -define(
    TERMINATE(Class, Reason, Debug, S, Q),
    terminate(
-     Class,
+     begin Class end,
      begin Reason end,
      ?STACKTRACE(),
      begin Debug end,
@@ -355,23 +355,23 @@ stop(ServerRef, Reason, Timeout) ->
 %% Send an event to a state machine that arrives with type 'event'
 -spec cast(ServerRef :: server_ref(), Msg :: term()) -> ok.
 cast({global,Name}, Msg) ->
-    try	global:send(Name, cast(Msg)) of
+    try	global:send(Name, wrap_cast(Msg)) of
 	_ -> ok
     catch
 	_:_ -> ok
     end;
 cast({via,RegMod,Name}, Msg) ->
-    try	RegMod:send(Name, cast(Msg)) of
+    try	RegMod:send(Name, wrap_cast(Msg)) of
 	_ -> ok
     catch
 	_:_ -> ok
     end;
 cast({Name,Node} = ServerRef, Msg) when is_atom(Name), is_atom(Node) ->
-    do_send(ServerRef, cast(Msg));
+    send(ServerRef, wrap_cast(Msg));
 cast(ServerRef, Msg) when is_atom(ServerRef) ->
-    do_send(ServerRef, cast(Msg));
+    send(ServerRef, wrap_cast(Msg));
 cast(ServerRef, Msg) when is_pid(ServerRef) ->
-    do_send(ServerRef, cast(Msg)).
+    send(ServerRef, wrap_cast(Msg)).
 
 %% Call a state machine (synchronous; a reply is expected) that
 %% arrives with type {call,Caller}
@@ -425,7 +425,7 @@ call(ServerRef, Request, Timeout) ->
 	      {Reason,{?MODULE,call,[ServerRef,Request,Timeout]}},
 	      Stacktrace);
 	{'DOWN',Mref,_,_,Reason} ->
-	    %% There is just a theoretical possibility that the
+	    %% There is a theoretical possibility that the
 	    %% proxy process gets killed between try--of and !
 	    %% so this clause is in case of that
 	    exit(Reason)
@@ -433,14 +433,13 @@ call(ServerRef, Request, Timeout) ->
 
 %% Reply from a state machine callback to whom awaits in call/2
 -spec reply([reply_action()] | reply_action()) -> ok.
-reply({reply,{_To,_Tag}=Caller,Reply}) ->
+reply({reply,Caller,Reply}) ->
     reply(Caller, Reply);
 reply(Replies) when is_list(Replies) ->
-    [reply(Reply) || Reply <- Replies],
-    ok.
+    replies(Replies).
 %%
 -spec reply(Caller :: caller(), Reply :: term()) -> ok.
-reply({To,Tag}, Reply) ->
+reply({To,Tag}, Reply) when is_pid(To) ->
     Msg = {Tag,Reply},
     try To ! Msg of
 	_ ->
@@ -503,11 +502,17 @@ enter_loop(Module, Opts, CallbackMode, State, Data, Server, Actions) ->
 %%---------------------------------------------------------------------------
 %% API helpers
 
-cast(Event) ->
+wrap_cast(Event) ->
     {'$gen_cast',Event}.
 
+replies([{reply,Caller,Reply}|Replies]) ->
+    reply(Caller, Reply),
+    replies(Replies);
+replies([]) ->
+    ok.
+
 %% Might actually not send the message in case of caught exception
-do_send(Proc, Msg) ->
+send(Proc, Msg) ->
     try erlang:send(Proc, Msg, [noconnect]) of
 	noconnect ->
 	    _ = spawn(erlang, send, [Proc,Msg]),
@@ -723,20 +728,17 @@ wakeup_from_hibernate(Parent, Debug, S) ->
 loop(Parent, Debug, #{hibernate := Hib} = S) ->
     case Hib of
 	true ->
-	    loop_hibernate(Parent, Debug, S);
+	    %% Does not return but restarts process at
+	    %% wakeup_from_hibernate/3 that jumps to loop_receive/3
+	    proc_lib:hibernate(
+	      ?MODULE, wakeup_from_hibernate, [Parent,Debug,S]),
+	    error(
+	      {should_not_have_arrived_here_but_instead_in,
+	       {wakeup_from_hibernate,3}});
 	false ->
 	    loop_receive(Parent, Debug, S)
     end.
 
-loop_hibernate(Parent, Debug, S) ->
-    %% Does not return but restarts process at
-    %% wakeup_from_hibernate/3 that jumps to loop_receive/3
-    proc_lib:hibernate(
-      ?MODULE, wakeup_from_hibernate, [Parent,Debug,S]),
-    error(
-      {should_not_have_arrived_here_but_instead_in,
-       {wakeup_from_hibernate,3}}).
-
 %% Entry point for wakeup_from_hibernate/3
 loop_receive(Parent, Debug, #{timer := Timer} = S) ->
     receive
@@ -754,7 +756,7 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 		    %% but this will stand out in the crash report...
 		    ?TERMINATE(exit, Reason, Debug, S, [EXIT]);
 		{timeout,Timer,Content} when Timer =/= undefined ->
-		    loop_receive(
+		    loop_event(
 		      Parent, Debug, S, {timeout,Content}, undefined);
 		_ ->
 		    Event =
@@ -766,11 +768,11 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 			    _ ->
 				{info,Msg}
 			end,
-		    loop_receive(Parent, Debug, S, Event, Timer)
+		    loop_event(Parent, Debug, S, Event, Timer)
 	    end
     end.
 
-loop_receive(Parent, Debug, S, Event, Timer) ->
+loop_event(Parent, Debug, S, Event, Timer) ->
     NewDebug = sys_debug(Debug, S, {in,Event}),
     %% Here the queue of not yet processed events is created
     loop_events(Parent, NewDebug, S, [Event], Timer).
-- 
cgit v1.2.3


From e660572b020da58c89149c7f052c7127cc0263cb Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 29 Feb 2016 11:36:27 +0100
Subject: Remove the remove_event action and all alike

Removing events from the internal queues is not necessary with
the choosen semantics of the event queue vs. hibernate.

In an early implementation it was possible by combining
hibernate with e.g. postpone to get an event in the queue
that you would not see before processing the postponed event,
and therefore should you decide to cancel a timer it was
essential to be able to remove that unseen event from the queue.

With the choosen semantics you will have to postpone or generate
an event for it to be in the event queue, and if you e.g. postpone
a timeout event and then cancel the timer it is your mistake.
You have seen the event and should know better than to try to
cancel the timer.

So, the actions: remove_event, cancel_timer, demonitor and unlink
are now removed.

There have also been some cleanup of the timer handling code.
---
 lib/stdlib/doc/src/gen_statem.xml    |  71 +-------
 lib/stdlib/src/gen_statem.erl        | 326 +++++++++--------------------------
 lib/stdlib/test/gen_statem_SUITE.erl |  35 ++--
 3 files changed, 104 insertions(+), 328 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index bda3ef081d..04b80d29ac 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -461,24 +461,6 @@ ok
 	</p>
       </desc>
     </datatype>
-    <datatype>
-      <name name="event_predicate" />
-      <desc>
-	<p>
-	  A <c>fun()</c> of arity 2 that takes an event
-	  and returns a boolean.
-	  When used in the
-	  <seealso marker="#type-action">action()</seealso>
-	  <c>{remove_event,RemoveEventPredicate}</c>,
-	  the oldest event for which the predicate returns <c>true</c>
-	  will be removed.
-	</p>
-	<p>
-	  The predicate may <em>not</em> use a throw exception
-	  to return its result.
-	</p>
-      </desc>
-    </datatype>
     <datatype>
       <name name="callback_mode" />
       <desc>
@@ -617,13 +599,11 @@ ok
 	  counts just like a new in this respect.
 	  If the value is <c>infinity</c> no timer is started.
 	  If it is <c>0</c> the timeout event
-	  is immediately enqueued as the newest received.
+	  is immediately enqueued as the newest received
+	  (unless there are retried or inserted events to process).
 	  Also note that it is not possible nor needed
-	  to cancel this timeout using the
-	  <seealso marker="#type-action">
-	    <c>action() cancel_timer</c>
-	  </seealso>
-	  since this timeout is cancelled automatically by any other event.
+	  to cancel this timeout since it is cancelled automatically
+	  by any other event.
 	</p>
       </desc>
     </datatype>
@@ -702,49 +682,6 @@ ok
 	    should be used when you want to reliably distinguish
 	    an event inserted this way from any external event.
 	  </item>
-	  <tag><c>remove_event</c></tag>
-	  <item>
-	    Remove the oldest queued event
-	    that matches equal to <c><anno>EventType</anno></c>
-	    and <c><anno>EventContent</anno></c> or for which
-	    <c><anno>EventPredicate</anno></c>
-	    returns <c>true</c>.  Note that <c>next_event</c>
-	    and <c>postpone</c> events in the same actions list
-	    does not get into the event queue until after all actions
-	    has been done so you can not remove an event that you insert
-	    with the same actions list.  Make up your mind!
-	  </item>
-	  <tag><c>cancel_timer</c></tag>
-	  <item>
-	    Cancel the timer by calling
-	    <seealso marker="erts:erlang#cancel_timer/2">
-	      <c>erlang:cancel_timer/2</c>
-	    </seealso>
-	    with <c><anno>TimerRef</anno></c>,
-	    clean the process message queue from any late timeout message,
-	    and remove any late timeout message
-	    from the <c>gen_statem</c> event queue using
-	    <c>{remove_event,<anno>EventPredicate</anno>}</c> above.
-	    This is a convenience function that saves quite some
-	    lines of code and testing time over doing it from
-	    the primitives mentioned above.
-	  </item>
-	  <tag><c>demonitor</c></tag>
-	  <item>
-	    Like <c>cancel_timer</c> above but for
-	    <seealso marker="erts:erlang#demonitor/2">
-	      <c>demonitor/2</c>
-	    </seealso>
-	    with <c><anno>MonitorRef</anno></c>.
-	  </item>
-	  <tag><c>unlink</c></tag>
-	  <item>
-	    Like <c>cancel_timer</c> above but for
-	    <seealso marker="erts:erlang#unlink/1">
-	      <c>unlink/1</c>
-	    </seealso>
-	    with <c><anno>Id</anno></c>.
-	  </item>
 	</taglist>
       </desc>
     </datatype>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 29848d13a3..26f1aede6f 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -66,9 +66,6 @@
 	{'call',Caller :: caller()} | 'cast' |
 	'info' | 'timeout' | 'internal'.
 
--type event_predicate() :: % Return true for the event in question
-	fun((event_type(), term()) -> boolean()).
-
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
 
 -type transition_option() ::
@@ -117,19 +114,7 @@
 	%% action() list is the first to be delivered.
 	{'next_event', % Insert event as the next to handle
 	 EventType :: event_type(),
-	 EventContent :: term()} |
-	%%
-	{'remove_event', % Remove the oldest matching (=:=) event
-	 EventType :: event_type(), EventContent :: term()} |
-	{'remove_event', % Remove the oldest event satisfying predicate
-	 EventPredicate :: event_predicate()} |
-	%%
-	{'cancel_timer', % Cancel timer and clean up mess(ages)
-	 TimerRef :: reference()} |
-	{'demonitor', % Demonitor and clean up mess(ages)
-	 MonitorRef :: reference()} |
-	{'unlink', % Unlink and clean up mess(ages)
-	 Id :: pid() | port()}.
+	 EventContent :: term()}.
 -type reply_action() ::
 	{'reply', % Reply to a caller
 	 Caller :: caller(), Reply :: term()}.
@@ -745,11 +730,11 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 	Msg ->
 	    case Msg of
 		{system,Pid,Req} ->
+		    #{hibernate := Hibernate} = S,
 		    %% Does not return but tail recursively calls
 		    %% system_continue/3 that jumps to loop/3
 		    sys:handle_system_msg(
-		      Req, Pid, Parent, ?MODULE, Debug, S,
-		      maps:get(hibernate, S));
+		      Req, Pid, Parent, ?MODULE, Debug, S, Hibernate);
 		{'EXIT',Parent,Reason} = EXIT ->
 		    %% EXIT is not a 2-tuple and therefore
 		    %% not an event and has no event_type(),
@@ -757,8 +742,25 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 		    ?TERMINATE(exit, Reason, Debug, S, [EXIT]);
 		{timeout,Timer,Content} when Timer =/= undefined ->
 		    loop_event(
-		      Parent, Debug, S, {timeout,Content}, undefined);
+		      Parent, Debug, S, {timeout,Content});
 		_ ->
+		    %% Cancel Timer if running
+		    case Timer of
+			undefined ->
+			    ok;
+			_ ->
+			    case erlang:cancel_timer(Timer) of
+				TimeLeft when is_integer(TimeLeft) ->
+				    ok;
+				false ->
+				    receive
+					{timeout,Timer,_} ->
+					    ok
+				    after 0 ->
+					    ok
+				    end
+			    end
+		    end,
 		    Event =
 			case Msg of
 			    {'$gen_call',Caller,Request} ->
@@ -768,22 +770,20 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 			    _ ->
 				{info,Msg}
 			end,
-		    loop_event(Parent, Debug, S, Event, Timer)
+		    loop_event(Parent, Debug, S, Event)
 	    end
     end.
 
-loop_event(Parent, Debug, S, Event, Timer) ->
+loop_event(Parent, Debug, S, Event) ->
+    %% The timer field in S is now invalid and ignored
+    %% until we get back to loop/3
     NewDebug = sys_debug(Debug, S, {in,Event}),
     %% Here the queue of not yet processed events is created
-    loop_events(Parent, NewDebug, S, [Event], Timer).
+    loop_events(Parent, NewDebug, S, [Event]).
 
-%% Process first event in queue, or if there is none receive a new
-%%
-%% The loop_event* functions optimize S map handling by dismantling it,
-%% passing the parts in arguments to avoid map lookups and construct the
-%% new S map in one go on exit.  Premature optimization, I know, but
-%% there were quite some map lookups repeated in different functions.
-loop_events(Parent, Debug, S, [], _Timer) ->
+%% Process first the event queue, or if it is empty
+%% loop back to receive a new event
+loop_events(Parent, Debug, S, []) ->
     loop(Parent, Debug, S);
 loop_events(
   Parent, Debug,
@@ -791,9 +791,7 @@ loop_events(
     module := Module,
     state := State,
     data := Data} = S,
-  [{Type,Content} = Event|Events] = Q, Timer) ->
-    _ = (Timer =/= undefined) andalso
-	cancel_timer(Timer),
+  [{Type,Content} = Event|Events] = Q) ->
     try
 	case CallbackMode of
 	    state_functions ->
@@ -841,7 +839,7 @@ loop_events(
 	    terminate(Class, Reason, Stacktrace, Debug, S, Q)
     end.
 
-%% Interpret all callback return value variants
+%% Interpret all callback return variants
 loop_event_result(
   Parent, Debug,
   #{callback_mode := CallbackMode, state := State, data := Data} = S,
@@ -909,7 +907,6 @@ loop_event_actions(
     Hibernate = false,
     Timeout = undefined,
     NextEvents = [],
-    P = false, % The postponed list or false if unchanged
     loop_event_actions(
       Parent, Debug, S, Events, Event, State, NewState, NewData,
       if
@@ -918,24 +915,25 @@ loop_event_actions(
 	  true ->
 	      [Actions]
       end,
-      Postpone, Hibernate, Timeout, NextEvents, P).
+      Postpone, Hibernate, Timeout, NextEvents).
 %%
+%% Process all action()s
 loop_event_actions(
   Parent, Debug, S, Events, Event,
   State, NewState, NewData, [Action|Actions],
-  Postpone, Hibernate, Timeout, NextEvents, P) ->
+  Postpone, Hibernate, Timeout, NextEvents) ->
     case Action of
-	%% Set options
+	%% Actions that set options
 	postpone ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions,
-	      true, Hibernate, Timeout, NextEvents, P);
+	      true, Hibernate, Timeout, NextEvents);
 	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions,
-	      NewPostpone, Hibernate, Timeout, NextEvents, P);
+	      NewPostpone, Hibernate, Timeout, NextEvents);
 	{postpone,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
@@ -943,12 +941,12 @@ loop_event_actions(
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions,
-	      Postpone, true, Timeout, NextEvents, P);
+	      Postpone, true, Timeout, NextEvents);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions,
-	      Postpone, NewHibernate, Timeout, NextEvents, P);
+	      Postpone, NewHibernate, Timeout, NextEvents);
 	{hibernate,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
@@ -956,12 +954,12 @@ loop_event_actions(
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions,
-	      Postpone, Hibernate, undefined, NextEvents, P);
+	      Postpone, Hibernate, undefined, NextEvents);
 	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NewState, NewData, Actions,
-	      Postpone, Hibernate, NewTimeout, NextEvents, P);
+	      Postpone, Hibernate, NewTimeout, NextEvents);
 	{timeout,_,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
@@ -973,7 +971,7 @@ loop_event_actions(
 		    loop_event_actions(
 		      Parent, NewDebug, S, Events, Event,
 		      State, NewState, NewData, Actions,
-		      Postpone, Hibernate, Timeout, NextEvents, P);
+		      Postpone, Hibernate, Timeout, NextEvents);
 		false ->
 		    ?TERMINATE(
 		       error, {bad_action,Action}, Debug, S, [Event|Events])
@@ -985,67 +983,25 @@ loop_event_actions(
 		      Parent, Debug, S, Events, Event,
 		      State, NewState, NewData, Actions,
 		      Postpone, Hibernate, Timeout,
-		      [{Type,Content}|NextEvents], P);
+		      [{Type,Content}|NextEvents]);
 		false ->
 		    ?TERMINATE(
 		       error, {bad_action,Action}, Debug, S, [Event|Events])
 	    end;
 	_ ->
-	    %% All others are remove actions
-	    case remove_fun(Action) of
-		false ->
-		    loop_event_actions(
-		      Parent, Debug, S, Events, Event,
-		      State, NewState, NewData, Actions,
-		      Postpone, Hibernate, Timeout, NextEvents, P);
-		undefined ->
-		    ?TERMINATE(
-		       error, {bad_action,Action}, Debug, S, [Event|Events]);
-		RemoveFun when is_function(RemoveFun, 2) ->
-		    P0 =
-			case P of
-			    false ->
-				maps:get(postponed, S);
-			    _ ->
-				P
-			end,
-		    case remove_event(RemoveFun, Events, P0) of
-			false ->
-			    loop_event_actions(
-			      Parent, Debug, S, Events, Event,
-			      State, NewState, NewData, Actions,
-			      Postpone, Hibernate, Timeout, NextEvents, P);
-			{NewEvents,false} ->
-			    loop_event_actions(
-			      Parent, Debug, S, NewEvents, Event,
-			      State, NewState, NewData, Actions,
-			      Postpone, Hibernate, Timeout, NextEvents, P);
-			{false,NewP} ->
-			    loop_event_actions(
-			      Parent, Debug, S, Events, Event,
-			      State, NewState, NewData, Actions,
-			      Postpone, Hibernate, Timeout, NextEvents,
-			      NewP);
-			[Class,Reason,Stacktrace] ->
-			    terminate(
-			      Class, Reason, Stacktrace,
-			      Debug, S, [Event|Events])
-		    end;
-		[Class,Reason,Stacktrace] ->
-		    terminate(
-		      Class, Reason, Stacktrace, Debug, S, [Event|Events])
-	    end
+	    ?TERMINATE(
+	       error, {bad_action,Action}, Debug, S, [Event|Events])
     end;
+%%
+%% End of actions list
 loop_event_actions(
-  Parent, Debug, S, Events, Event, State, NewState, NewData, [],
-  Postpone, Hibernate, Timeout, NextEvents, P) ->
-    P0 =
-	case P of
-	    false ->
-		maps:get(postponed, S);
-	    _ ->
-		P
-	end,
+  Parent, Debug, #{postponed := P0} = S, Events, Event,
+  State, NewState, NewData, [],
+  Postpone, Hibernate, Timeout, NextEvents) ->
+    %%
+    %% All options have been collected and next_events are buffered.
+    %% Do the actual state transition.
+    %%
     P1 = % Move current event to postponed if Postpone
 	case Postpone of
 	    true ->
@@ -1053,23 +1009,12 @@ loop_event_actions(
 	    false ->
 		P0
 	end,
-    {Timer,Q1} =
-	case Timeout of
-	    undefined ->
-		{undefined,Events};
-	    {timeout,0,Msg} ->
-		%% Pretend the timeout has just been received
-		{undefined,Events ++ [{timeout,Msg}]};
-	    {timeout,Time,Msg} ->
-		{erlang:start_timer(Time, self(), Msg),
-		Events}
-	end,
-    {Q2,P2} = % Move all postponed events to queue if state change
+    {Q2,P} = % Move all postponed events to queue if state change
 	if
 	    NewState =:= State ->
-		{Q1,P1};
+		{Events,P1};
 	    true ->
-		{lists:reverse(P1, Q1),[]}
+		{lists:reverse(P1, Events),[]}
 	end,
     %% Place next events first in queue
     Q3 = lists:reverse(NextEvents, Q2),
@@ -1083,16 +1028,41 @@ loop_event_actions(
 	      false ->
 		  {consume,Event,NewState}
 	  end),
-    %% Loop to top; process next event
+    %% Have a peek on the event queue so we can avoid starting
+    %% the state timer unless we have to
+    {Q,Timer} =
+	case Timeout of
+	    undefined ->
+		%% No state timeout has been requested
+		{Q3,undefined};
+	    {timeout,Time,Msg} ->
+		%% A state timeout has been requested
+		case Q3 of
+		    [] when Time =:= 0 ->
+			%% Immediate timeout - simulate it
+			%% so we do not get the timeout message
+			%% after any received event
+			{[{timeout,Msg}],undefined};
+		    [] ->
+			%% Actually start a timer
+			{Q3,erlang:start_timer(Time, self(), Msg)};
+		    _ ->
+			%% Do not start a timer since any queued
+			%% event cancels the state timer so we pretend
+			%% that the timer has been started and cancelled
+			{Q3,undefined}
+		end
+	end,
+    %% Loop to top of event queue loop; process next event
     loop_events(
       Parent, NewDebug,
       S#{
 	state := NewState,
 	data := NewData,
 	timer := Timer,
-	hibernate := Hibernate,
-	postponed := P2},
-      Q3, Timer).
+	postponed := P,
+	hibernate := Hibernate},
+      Q).
 
 %%---------------------------------------------------------------------------
 %% Server helpers
@@ -1125,103 +1095,6 @@ do_reply(Debug, S, Caller, Reply) ->
     sys_debug(Debug, S, {out,Reply,Caller}).
 
 
-%% Remove oldest matching event from the queue(s)
-remove_event(RemoveFun, Q, P) ->
-    try
-	case remove_tail_event(RemoveFun, P) of
-	    false ->
-		case remove_head_event(RemoveFun, Q) of
-		    false ->
-			false;
-		    NewQ ->
-			{false,NewQ}
-		end;
-	    NewP ->
-		{NewP,false}
-	end
-    catch
-	Class:Reason ->
-	    [Class,Reason,erlang:get_stacktrace()]
-    end.
-
-%% Do the given action and create an event removal predicate fun()
-remove_fun({remove_event,Type,Content}) ->
-    fun (T, C) when T =:= Type, C =:= Content -> true;
-	(_, _) -> false
-    end;
-remove_fun({remove_event,RemoveFun}) when is_function(RemoveFun, 2) ->
-    RemoveFun;
-remove_fun({cancel_timer,TimerRef}) ->
-    try cancel_timer(TimerRef) of
-	false ->
-	    false;
-	true ->
-	    fun
-		(info, {timeout,TRef,_})
-		  when TRef =:= TimerRef ->
-		    true;
-		(_, _) ->
-		    false
-	    end
-    catch
-	Class:Reason ->
-	    [Class,Reason,erlang:get_stacktrace()]
-    end;
-remove_fun({demonitor,MonitorRef}) ->
-    try erlang:demonitor(MonitorRef, [flush,info]) of
-	false ->
-	    false;
-	true ->
-	    fun (info, {'DOWN',MRef,_,_,_})
-		  when MRef =:= MonitorRef->
-		    true;
-		(_, _) ->
-		    false
-	    end
-    catch
-	Class:Reason ->
-	    [Class,Reason,erlang:get_stacktrace()]
-    end;
-remove_fun({unlink,Id}) ->
-    try unlink(Id) of
-	true ->
-	    receive
-		{'EXIT',Id,_} ->
-		    ok
-	    after 0 ->
-		    ok
-	    end,
-	    fun (info, {'EXIT',I,_})
-		  when I =:= Id ->
-		    true;
-		(_, _) ->
-		    false
-	    end
-    catch
-	Class:Reason ->
-	    [Class,Reason,erlang:get_stacktrace()]
-    end;
-remove_fun(_) ->
-    undefined.
-
-
-%% Cancel a timer and clense the process mailbox returning
-%% false if no such timer message can arrive after this or
-%% true otherwise
-cancel_timer(TimerRef) ->
-    case erlang:cancel_timer(TimerRef) of
-	TimeLeft when is_integer(TimeLeft) ->
-	    false;
-	false ->
-	    receive
-		{timeout,TimerRef,_} ->
-		    false
-	    after 0 ->
-		    true
-	    end
-    end.
-
-
 terminate(
   Class, Reason, Stacktrace, Debug,
   #{module := Module,
@@ -1350,30 +1223,3 @@ format_status_default(Opt, State, Data) ->
 	_ ->
 	    [{data,[{"State",SSD}]}]
     end.
-
-%%---------------------------------------------------------------------------
-%% Farily general helpers
-
-%% Return the modified list where the first element that satisfies
-%% the RemoveFun predicate is removed, or false if no such element exists.
-remove_head_event(_RemoveFun, []) ->
-    false;
-remove_head_event(RemoveFun, [{Tag,Content}|Events]) ->
-    case RemoveFun(Tag, Content) of
-	false ->
-	    remove_head_event(RemoveFun, Events);
-	true ->
-	    Events
-    end.
-
-%% Return the modified list where the last element that satisfies
-%% the RemoveFun predicate is removed, or false if no such element exists.
-remove_tail_event(_RemoveFun, []) ->
-    false;
-remove_tail_event(RemoveFun, [{Tag,Content} = Event|Events]) ->
-    case remove_tail_event(RemoveFun, Events) of
-	false ->
-	    RemoveFun(Tag, Content) andalso Events;
-	NewEvents ->
-	    [Event|NewEvents]
-    end.
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 268b45a0e7..38aab752b8 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1210,29 +1210,22 @@ idle(Type, Content, Data) ->
     end.
 
 timeout(timeout, idle, {From,Time}) ->
-    TRef2 = erlang:start_timer(Time, self(), ok),
-    TRefC1 = erlang:start_timer(Time, self(), cancel1),
-    TRefC2 = erlang:start_timer(Time, self(), cancel2),
-    {next_state,timeout2,{From,Time,TRef2},
-     [{cancel_timer, TRefC1},
-      {next_event,internal,{cancel_timer,TRefC2}}]};
-timeout(_, _, Data) ->
-    {keep_state,Data}.
-
-timeout2(
-  internal, {cancel_timer,TRefC2}, {From,Time,TRef2}) ->
-    Time4 = Time * 4,
-    receive after Time4 -> ok end,
-    {next_state,timeout3,{From,TRef2},
-     [{cancel_timer,TRefC2}]};
-timeout2(_, _, Data) ->
-    {keep_state,Data}.
-
-timeout3(info, {timeout,TRef2,Result}, {From,TRef2}) ->
+    TRef = erlang:start_timer(Time, self(), ok),
+    {next_state,timeout2,{From,TRef},
+     [{timeout,1,should_be_cancelled},
+      postpone]}; % Should cancel state timeout
+timeout(_, _, _) ->
+    keep_state_and_data.
+
+timeout2(timeout, idle, _) ->
+    keep_state_and_data;
+timeout2(timeout, Reason, _) ->
+    {stop,Reason};
+timeout2(info, {timeout,TRef,Result}, {From,TRef}) ->
     gen_statem:reply([{reply,From,Result}]),
     {next_state,idle,state};
-timeout3(_, _, Data) ->
-    {keep_state,Data}.
+timeout2(_, _, _) ->
+    {keep_state_and_data,[]}.
 
 wfor_conf({call,From}, confirm, Data) ->
     {next_state,connected,Data,
-- 
cgit v1.2.3


From 79d75b981274f6841e1d4c09c125f92e1731ab4b Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 29 Feb 2016 16:10:00 +0100
Subject: Sharpen test suite

---
 lib/stdlib/src/gen_statem.erl        |   2 +-
 lib/stdlib/test/gen_statem_SUITE.erl | 141 ++++++++++++++++++++++++++++++++++-
 2 files changed, 139 insertions(+), 4 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 26f1aede6f..17d361efc2 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -1169,7 +1169,7 @@ error_info(
 	  "** Reason for termination = ~w:~p~n" ++
 	  "** State = ~p~n" ++
 	  "** Callback mode = ~p~n" ++
-	  "** Queued/Posponed = ~w/~w~n" ++
+	  "** Queued/Postponed = ~w/~w~n" ++
 	  case FixedStacktrace of
 	      [] ->
 		  "";
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 38aab752b8..e62255035d 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -37,7 +37,7 @@ all() ->
      {group, stop_handle_event},
      {group, abnormal},
      {group, abnormal_handle_event},
-     shutdown,
+     shutdown, stop_and_reply, postpone_and_next_event,
      {group, sys},
      hibernate, enter_loop].
 
@@ -495,6 +495,113 @@ shutdown(Config) ->
 
 
 
+stop_and_reply(_Config) ->
+    process_flag(trap_exit, true),
+
+    Machine =
+	%% Abusing the internal format of From...
+	#{init =>
+	      fun (cast, {echo,From1,Reply1}, _) ->
+		      {next_state,wait,{reply,From1,Reply1}}
+	      end,
+	  wait =>
+	      fun (cast, {stop_and_reply,Reason,From2,Reply2},R1) ->
+		      {stop_and_reply,Reason,
+		       [R1,{reply,From2,Reply2}]}
+	      end},
+    {ok,STM} =
+	gen_statem:start_link(
+	  ?MODULE,
+	  {map_statem,Machine,init,undefined,[]},
+	  []),
+
+    Self = self(),
+    Tag1 = make_ref(),
+    gen_statem:cast(STM, {echo,{Self,Tag1},reply1}),
+    Tag2 = make_ref(),
+    gen_statem:cast(STM, {stop_and_reply,reason,{Self,Tag2},reply2}),
+    case flush() of
+	[{Tag1,reply1},{Tag2,reply2},{'EXIT',STM,reason}] ->
+	    ok;
+	Other1 ->
+	    ct:fail({unexpected,Other1})
+    end,
+
+    {noproc,_} =
+	?EXPECT_FAILURE(gen_statem:call(STM, hej), Reason),
+    case flush() of
+	[] ->
+	    ok;
+	Other2 ->
+	    ct:fail({unexpected,Other2})
+    end.
+
+
+
+postpone_and_next_event(_Config) ->
+    process_flag(trap_exit, true),
+
+    Machine =
+	%% Abusing the internal format of From...
+	#{init =>
+	      fun (cast, _, _) ->
+		      {keep_state_and_data,postpone};
+		  ({call,From}, {buffer,Pid,[Tag3,Tag4]}, _) ->
+		      {next_state,buffer,[],
+		       [{next_event,internal,{reply,{Pid,Tag3},ok3}},
+			{next_event,internal,{reply,{Pid,Tag4},ok4}},
+			{reply,From,ok}]}
+	      end,
+	  buffer =>
+	      fun (internal, Reply, Replies) ->
+		      {keep_state,[Reply|Replies]};
+		  (cast, Reply, Replies) ->
+		      {keep_state,[Reply|Replies]};
+		  ({call,From}, {stop,Reason}, Replies) ->
+		      {next_state,stop,Replies,
+		       lists:reverse(
+			 Replies,
+			 [{reply,From,ok},
+			  {next_event,internal,{stop,Reason}}])}
+	      end,
+	  stop =>
+	      fun (internal, Result, _) ->
+		      Result
+	      end},
+
+    {ok,STM} =
+	gen_statem:start_link(
+	  ?MODULE,
+	  {map_statem,Machine,init,undefined,[]},
+	  []),
+    Self = self(),
+    Tag1 = make_ref(),
+    gen_statem:cast(STM, {reply,{Self,Tag1},ok1}),
+    Tag2 = make_ref(),
+    gen_statem:cast(STM, {reply,{Self,Tag2},ok2}),
+    Tag3 = make_ref(),
+    Tag4 = make_ref(),
+    ok = gen_statem:call(STM, {buffer,Self,[Tag3,Tag4]}),
+    ok = gen_statem:call(STM, {stop,reason}),
+    case flush() of
+	[{Tag3,ok3},{Tag4,ok4},{Tag1,ok1},{Tag2,ok2},
+	 {'EXIT',STM,reason}] ->
+	    ok;
+	Other1 ->
+	    ct:fail({unexpected,Other1})
+    end,
+
+    {noproc,_} =
+	?EXPECT_FAILURE(gen_statem:call(STM, hej), Reason),
+    case flush() of
+	[] ->
+	    ok;
+	Other2 ->
+	    ct:fail({unexpected,Other2})
+    end.
+
+
+
 sys1(Config) ->
     {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     {status, Pid, {module,gen_statem}, _} = sys:get_status(Pid),
@@ -1115,7 +1222,6 @@ do_sync_disconnect(STM) ->
 
 
 verify_empty_msgq() ->
-    receive after 500 -> ok end,
     [] = flush(),
     ok.
 
@@ -1157,6 +1263,8 @@ init({callback_mode,CallbackMode,Arg}) ->
 	Other ->
 	    Other
     end;
+init({map_statem,Machine,State,Data,Ops}) when is_map(Machine) ->
+    {handle_event_function,State,[Data|Machine],Ops};
 init([]) ->
     {state_functions,idle,data}.
 
@@ -1367,6 +1475,33 @@ handle_common_events(cast, {'alive?',Pid}, _, Data) ->
 handle_common_events(_, _, _, _) ->
     undefined.
 
+%% Wrapper state machine that uses a map state machine spec
+handle_event(
+  Type, Event, State, [Data|Machine])
+  when is_map(Machine) ->
+    #{State := HandleEvent} = Machine,
+    case
+	try HandleEvent(Type, Event, Data) of
+	    Result ->
+		Result
+	catch
+	    Result ->
+		Result
+	end of
+	{stop,Reason,NewData} ->
+	    {stop,Reason,[NewData|Machine]};
+	{next_state,NewState,NewData} ->
+	    {next_state,NewState,[NewData|Machine]};
+	{next_state,NewState,NewData,Ops} ->
+	    {next_state,NewState,[NewData|Machine],Ops};
+	{keep_state,NewData} ->
+	    {keep_state,[NewData|Machine]};
+	{keep_state,NewData,Ops} ->
+	    {keep_state,[NewData|Machine],Ops};
+	Other ->
+	    Other
+    end;
+%%
 %% Dispatcher to test callback_mode handle_event_function
 %%
 %% Wrap the state in a 1 element list just to test non-atom
@@ -1412,6 +1547,6 @@ flush() ->
     receive
 	Msg ->
 	    [Msg|flush()]
-    after 0 ->
+    after 500 ->
 	    []
     end.
-- 
cgit v1.2.3


From a0c69303c971b4c65e5cd450dbe7de680aa58181 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 1 Mar 2016 09:08:30 +0100
Subject: Fixup sharpened test suite

---
 lib/stdlib/test/gen_statem_SUITE.erl | 55 +++++++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 20 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index e62255035d..f605f0c7b9 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -37,7 +37,7 @@ all() ->
      {group, stop_handle_event},
      {group, abnormal},
      {group, abnormal_handle_event},
-     shutdown, stop_and_reply, postpone_and_next_event,
+     shutdown, stop_and_reply, event_order,
      {group, sys},
      hibernate, enter_loop].
 
@@ -501,7 +501,11 @@ stop_and_reply(_Config) ->
     Machine =
 	%% Abusing the internal format of From...
 	#{init =>
-	      fun (cast, {echo,From1,Reply1}, _) ->
+	      fun () ->
+		      {ok,start,undefined}
+	      end,
+	  start =>
+	      fun (cast, {echo,From1,Reply1}, undefined) ->
 		      {next_state,wait,{reply,From1,Reply1}}
 	      end,
 	  wait =>
@@ -509,11 +513,7 @@ stop_and_reply(_Config) ->
 		      {stop_and_reply,Reason,
 		       [R1,{reply,From2,Reply2}]}
 	      end},
-    {ok,STM} =
-	gen_statem:start_link(
-	  ?MODULE,
-	  {map_statem,Machine,init,undefined,[]},
-	  []),
+    {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine}, []),
 
     Self = self(),
     Tag1 = make_ref(),
@@ -538,42 +538,49 @@ stop_and_reply(_Config) ->
 
 
 
-postpone_and_next_event(_Config) ->
+event_order(_Config) ->
     process_flag(trap_exit, true),
 
     Machine =
 	%% Abusing the internal format of From...
 	#{init =>
+	      fun () ->
+		      {ok,start,undefined}
+	      end,
+	  start =>
 	      fun (cast, _, _) ->
-		      {keep_state_and_data,postpone};
-		  ({call,From}, {buffer,Pid,[Tag3,Tag4]}, _) ->
+		      {keep_state_and_data,postpone}; %% Handled in 'buffer'
+		  ({call,From}, {buffer,Pid,[Tag3,Tag4,Tag5]},
+		   undefined) ->
 		      {next_state,buffer,[],
 		       [{next_event,internal,{reply,{Pid,Tag3},ok3}},
 			{next_event,internal,{reply,{Pid,Tag4},ok4}},
+			{timeout,0,{reply,{Pid,Tag5},ok5}},
+			%% The timeout should not happen since there
+			%% are events that cancel it i.e next_event
+			%% and postponed
 			{reply,From,ok}]}
 	      end,
 	  buffer =>
 	      fun (internal, Reply, Replies) ->
 		      {keep_state,[Reply|Replies]};
+		  (timeout, Reply, Replies) ->
+		      {keep_state,[Reply|Replies]};
 		  (cast, Reply, Replies) ->
 		      {keep_state,[Reply|Replies]};
 		  ({call,From}, {stop,Reason}, Replies) ->
-		      {next_state,stop,Replies,
+		      {next_state,stop,undefined,
 		       lists:reverse(
 			 Replies,
 			 [{reply,From,ok},
 			  {next_event,internal,{stop,Reason}}])}
 	      end,
 	  stop =>
-	      fun (internal, Result, _) ->
+	      fun (internal, Result, undefined) ->
 		      Result
 	      end},
 
-    {ok,STM} =
-	gen_statem:start_link(
-	  ?MODULE,
-	  {map_statem,Machine,init,undefined,[]},
-	  []),
+    {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine}, []),
     Self = self(),
     Tag1 = make_ref(),
     gen_statem:cast(STM, {reply,{Self,Tag1},ok1}),
@@ -581,7 +588,8 @@ postpone_and_next_event(_Config) ->
     gen_statem:cast(STM, {reply,{Self,Tag2},ok2}),
     Tag3 = make_ref(),
     Tag4 = make_ref(),
-    ok = gen_statem:call(STM, {buffer,Self,[Tag3,Tag4]}),
+    Tag5 = make_ref(),
+    ok = gen_statem:call(STM, {buffer,Self,[Tag3,Tag4,Tag5]}),
     ok = gen_statem:call(STM, {stop,reason}),
     case flush() of
 	[{Tag3,ok3},{Tag4,ok4},{Tag1,ok1},{Tag2,ok2},
@@ -1263,8 +1271,15 @@ init({callback_mode,CallbackMode,Arg}) ->
 	Other ->
 	    Other
     end;
-init({map_statem,Machine,State,Data,Ops}) when is_map(Machine) ->
-    {handle_event_function,State,[Data|Machine],Ops};
+init({map_statem,#{init := Init}=Machine}) ->
+    case Init() of
+	{ok,State,Data,Ops} ->
+	    {handle_event_function,State,[Data|Machine],Ops};
+	{ok,State,Data} ->
+	    {handle_event_function,State,[Data|Machine]};
+	Other ->
+	    Other
+    end;
 init([]) ->
     {state_functions,idle,data}.
 
-- 
cgit v1.2.3


From 9dfb4e6cf574870ac6e6a5a2a507c989c64e7525 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 1 Mar 2016 08:31:58 +0100
Subject: Change code_change/4 to {ok,State,Data}

---
 lib/stdlib/doc/src/gen_statem.xml    |  4 ++--
 lib/stdlib/src/gen_statem.erl        |  4 ++--
 lib/stdlib/test/gen_statem_SUITE.erl | 15 ++++++++++++---
 3 files changed, 16 insertions(+), 7 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 04b80d29ac..01be3099c1 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -241,7 +241,7 @@ stop() ->
 terminate(_Reason, _State, _Data) ->
     void.
 code_change(_Vsn, State, Data, _Extra) ->
-    {ok,{State,Data}}.
+    {ok,State,Data}.
 init([]) ->
     %% Set the callback mode and initial state + data.
     %% Data is used only as a counter.
@@ -1359,7 +1359,7 @@ ok
         <v>&nbsp;&nbsp;Vsn = term()</v>
         <v>OldState = NewState = term()</v>
         <v>Extra = term()</v>
-	<v>Result = {ok,{NewState,NewData}} | Reason</v>
+	<v>Result = {ok,NewState,NewData} | Reason</v>
 	<v>
 	  OldState = NewState =
 	  <seealso marker="#type-state">state()</seealso>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 17d361efc2..cc09efc140 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -200,7 +200,7 @@
 	    OldState :: state(),
 	    OldData :: data(),
 	    Extra :: term()) ->
-    {ok, {NewState :: state(), NewData :: data()}}.
+    {ok, NewState :: state(), NewData :: data()}.
 
 %% Format the callback module state in some sensible that is
 %% often condensed way.  For StatusOption =:= 'normal' the perferred
@@ -619,7 +619,7 @@ system_code_change(
 	    Result -> Result
 	end
     of
-	{ok,{NewState,NewData}} ->
+	{ok,NewState,NewData} ->
 	    {ok,
 	     S#{
 	       state := NewState,
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index f605f0c7b9..573a64bbb7 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -55,7 +55,7 @@ groups() ->
      {abnormal, [], [abnormal1, abnormal2]},
      {abnormal_handle_event, [], [abnormal1, abnormal2]},
      {sys, [],
-      [sys1,
+      [sys1, code_change,
        call_format_status,
        error_format_status, terminate_crash_format,
        get_state, replace_state]},
@@ -633,6 +633,15 @@ sys1(Config) ->
     sys:resume(Pid),
     stop_it(Pid).
 
+code_change(Config) ->
+    {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
+    {idle,data} = sys:get_state(Pid),
+    sys:suspend(Pid),
+    sys:change_code(Pid, ?MODULE, old_vsn, extra),
+    sys:resume(Pid),
+    {idle,{old_vsn,data,extra}} = sys:get_state(Pid),
+    stop_it(Pid).
+
 call_format_status(Config) ->
     {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     Status = sys:get_status(Pid),
@@ -1550,8 +1559,8 @@ wrap_result(Result) ->
 
 
 
-code_change(_OldVsn, State, Data, _Extra) ->
-    {ok,State,Data}.
+code_change(OldVsn, State, Data, Extra) ->
+    {ok,State,{OldVsn,Data,Extra}}.
 
 format_status(terminate, [_Pdict,State,Data]) ->
     {formatted,State,Data};
-- 
cgit v1.2.3


From d840b24857a1d54419953661f70716c449c11864 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 3 Mar 2016 10:54:01 +0100
Subject: Fix most of the system docs and emacs mode

---
 lib/stdlib/doc/src/gen_statem.xml | 87 +++++++++++++++++++++++++++---------
 lib/stdlib/doc/src/proc_lib.xml   |  8 ++--
 lib/stdlib/doc/src/supervisor.xml | 10 +++--
 lib/stdlib/doc/src/sys.xml        | 31 ++++++++-----
 lib/stdlib/src/gen_statem.erl     | 93 +++++++++++++++++++++++----------------
 5 files changed, 153 insertions(+), 76 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 01be3099c1..db6a4e03ea 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -407,7 +407,7 @@ ok
       <name name="state" />
       <desc>
 	<p>
-	  After a state change (<c>NewState =/= State</c>)
+	  After a state change (<c>NextState =/= State</c>)
 	  all postponed events are retried.
 	</p>
       </desc>
@@ -566,7 +566,7 @@ ok
 	<p>
 	  If <c>true</c> postpone the current event and retry
 	  it when the state changes that is:
-	  <c>NewState =/= State</c>.
+	  <c>NextState =/= State</c>.
 	</p>
       </desc>
     </datatype>
@@ -701,7 +701,47 @@ ok
       </desc>
     </datatype>
     <datatype>
-      <name name="state_callback_result" />
+      <name name="state_function_result" />
+      <desc>
+	<taglist>
+	  <tag><c>next_state</c></tag>
+	  <item>
+	    The <c>gen_statem</c> will do a state transition to
+	    <c><anno>NextStateName</anno></c>
+	    (which may be the same as the current state),
+	    set <c><anno>NewData</anno></c>
+	    and execute all <c><anno>Actions</anno></c>
+	  </item>
+	</taglist>
+	<p>
+	  All these terms are tuples or atoms and this property
+	  will hold in any future version of <c>gen_statem</c>,
+	  just in case you need such a promise.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="handle_event_result" />
+      <desc>
+	<taglist>
+	  <tag><c>next_state</c></tag>
+	  <item>
+	    The <c>gen_statem</c> will do a state transition to
+	    <c><anno>NextState</anno></c>
+	    (which may be the same as the current state),
+	    set <c><anno>NewData</anno></c>
+	    and execute all <c><anno>Actions</anno></c>
+	  </item>
+	</taglist>
+	<p>
+	  All these terms are tuples or atoms and this property
+	  will hold in any future version of <c>gen_statem</c>,
+	  just in case you need such a promise.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="common_state_callback_result" />
       <desc>
 	<taglist>
 	  <tag><c>stop</c></tag>
@@ -723,14 +763,6 @@ ok
 	    with <c>Reason</c> and
 	    <c><anno>NewData</anno></c>, if given.
 	  </item>
-	  <tag><c>next_state</c></tag>
-	  <item>
-	    The <c>gen_statem</c> will do a state transition to
-	    <c><anno>NewState</anno></c>
-	    (which may be the same as the current state),
-	    set <c><anno>NewData</anno></c>
-	    and execute all <c><anno>Actions</anno></c>
-	  </item>
 	  <tag><c>keep_state</c></tag>
 	  <item>
 	    The <c>gen_statem</c> will keep the current state, or
@@ -1209,10 +1241,11 @@ ok
     </func>
 
     <func>
-      <name>Module:StateName(EventType, EventContent, Data) -> Result
+      <name>Module:StateName(EventType, EventContent, Data) ->
+      StateFunctionResult
       </name>
       <name>Module:handle_event(EventType, EventContent,
-      State, Data) -> Result
+      State, Data) -> HandleEventResult
       </name>
       <fsummary>Handle an event</fsummary>
       <type>
@@ -1222,7 +1255,7 @@ ok
 	</v>
 	<v>EventContent = term()</v>
 	<v>
-	  State = NewState =
+	  State =
 	  <seealso marker="#type-state">state()</seealso>
 	</v>
 	<v>
@@ -1230,9 +1263,15 @@ ok
 	  <seealso marker="#type-data">data()</seealso>
 	</v>
 	<v>
-	  Result =
-	  <seealso marker="#type-state_callback_result">
-	    state_callback_result()
+	  StateFunctionResult =
+	  <seealso marker="#type-state_function_result">
+	    state_function_result()
+	  </seealso>
+	</v>
+	<v>
+	  HandleEventResult =
+	  <seealso marker="#type-handle_event_result">
+	    handle_event_result()
 	  </seealso>
 	</v>
       </type>
@@ -1260,9 +1299,15 @@ ok
 	  <seealso marker="#reply/2"><c>reply(Caller, Reply)</c></seealso>.
 	</p>
 	<p>
-	  If this function returns with a new state that
+	  If this function returns with a next state that
 	  does not match equal (<c>=/=</c>) to the current state
-	  all postponed events will be retried in the new state.
+	  all postponed events will be 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 has to be an atom but for <c>HandleEventResult</c>
+	  there is no restriction on the next state.
 	</p>
 	<p>
 	  See <seealso marker="#type-action">action()</seealso>
@@ -1272,7 +1317,7 @@ ok
 	<p>
 	  These functions may use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
-	  to return <c>Result</c>.
+	  to return the result.
 	</p>
       </desc>
     </func>
@@ -1401,7 +1446,7 @@ ok
         <p>
 	  If successful, the function shall return the updated
           internal state in an
-	  <c>{ok,{NewState,NewData}}</c> tuple.
+	  <c>{ok,NewState,NewData}</c> tuple.
 	</p>
 	<p>
 	  If the function returns <c>Reason</c>, the ongoing
diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml
index 85f0c0c908..245580b1ba 100644
--- a/lib/stdlib/doc/src/proc_lib.xml
+++ b/lib/stdlib/doc/src/proc_lib.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2014</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -34,9 +34,9 @@
     <p>This module is used to start processes adhering to
       the <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso>. Specifically, the functions in this
       module are used by the OTP standard behaviors (<c>gen_server</c>,
-      <c>gen_fsm</c>, ...) when starting new processes. The functions
-      can also be used to start <em>special processes</em>, user
-      defined processes which comply to the OTP design principles. See
+      <c>gen_fsm</c>, <c>gen_statem</c>, ...) when starting new processes.
+      The functions can also be used to start <em>special processes</em>,
+      user defined processes which comply to the OTP design principles. See
       <seealso marker="doc/design_principles:spec_proc">Sys and Proc_Lib</seealso> in OTP Design Principles for an example.</p>
     <p>Some useful information is initialized when a process starts.
       The registered names, or the process identifiers, of the parent
diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml
index 24ff251ce3..9d81fb0db7 100644
--- a/lib/stdlib/doc/src/supervisor.xml
+++ b/lib/stdlib/doc/src/supervisor.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2014</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -34,8 +34,8 @@
     <p>A behaviour module for implementing a supervisor, a process which
       supervises other processes called child processes. A child
       process can either be another supervisor or a worker process.
-      Worker processes are normally implemented using one of
-      the <c>gen_event</c>, <c>gen_fsm</c>, or <c>gen_server</c>
+      Worker processes are normally implemented using one of the
+      <c>gen_event</c>, <c>gen_fsm</c>, <c>gen_statem</c> or <c>gen_server</c>
       behaviours. A supervisor implemented using this module will have
       a standard set of interface functions and include functionality
       for tracing and error reporting. Supervisors are used to build a
@@ -221,7 +221,8 @@
         <p><c>modules</c> is used by the release handler during code
           replacement to determine which processes are using a certain
           module. As a rule of thumb, if the child process is a
-          <c>supervisor</c>, <c>gen_server</c>, or <c>gen_fsm</c>,
+          <c>supervisor</c>, <c>gen_server</c>,
+	  <c>gen_fsm</c> or <c>gen_statem</c>
 	  this should be a list with one element <c>[Module]</c>,
 	  where <c>Module</c> is the callback module. If the child
 	  process is an event manager (<c>gen_event</c>) with a
@@ -633,6 +634,7 @@
     <title>SEE ALSO</title>
     <p><seealso marker="gen_event">gen_event(3)</seealso>, 
       <seealso marker="gen_fsm">gen_fsm(3)</seealso>, 
+      <seealso marker="gen_statem">gen_statem(3)</seealso>,
       <seealso marker="gen_server">gen_server(3)</seealso>, 
       <seealso marker="sys">sys(3)</seealso></p>
   </section>
diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index d400f72e1d..2255395f46 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2014</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -217,14 +217,18 @@
           processes. For example, a <c>gen_server</c> process returns
           the callback module's state, a <c>gen_fsm</c> process
           returns information such as its current state name and state data,
-          and a <c>gen_event</c> process returns information about each of its
+	  a <c>gen_statem</c> process returns information about
+	  its current state and data, and a <c>gen_event</c> process
+	  returns information about each of its
           registered handlers. Callback modules for <c>gen_server</c>,
-          <c>gen_fsm</c>, and <c>gen_event</c> can also customise the value
+          <c>gen_fsm</c>, <c>gen_statem</c> and <c>gen_event</c>
+	  can also customise the value
           of <c><anno>Misc</anno></c> by exporting a <c>format_status/2</c>
           function that contributes module-specific information;
-          see <seealso marker="gen_server#Module:format_status/2">gen_server:format_status/2</seealso>,
-          <seealso marker="gen_fsm#Module:format_status/2">gen_fsm:format_status/2</seealso>, and
-          <seealso marker="gen_event#Module:format_status/2">gen_event:format_status/2</seealso>
+          see <seealso marker="gen_server#Module:format_status/2">gen_server format_status/2</seealso>,
+          <seealso marker="gen_fsm#Module:format_status/2">gen_fsm format_status/2</seealso>,
+          <seealso marker="gen_statem#Module:format_status/2">gen_statem format_status/2</seealso>, and
+          <seealso marker="gen_event#Module:format_status/2">gen_event format_status/2</seealso>
           for more details.</p>
       </desc>
     </func>
@@ -245,6 +249,8 @@
           processes. For a <c>gen_server</c> process, the returned <c><anno>State</anno></c>
           is simply the callback module's state. For a <c>gen_fsm</c> process,
           <c><anno>State</anno></c> is the tuple <c>{CurrentStateName, CurrentStateData}</c>.
+	  For a <c>gen_statem</c> process <c><anno>State</anno></c> is
+	  the tuple <c>{CurrentState,CurrentData}.</c>
           For a <c>gen_event</c> process, <c><anno>State</anno></c> a list of tuples,
           where each tuple corresponds to an event handler registered in the process and contains
           <c>{Module, Id, HandlerState}</c>, where <c>Module</c> is the event handler's module name,
@@ -263,8 +269,9 @@
           details of the exception.</p>
         <p>The <c>system_get_state/1</c> function is primarily useful for user-defined
           behaviours and modules that implement OTP <seealso marker="#special_process">special
-          processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> OTP
-          behaviour modules export this function, and so callback modules for those behaviours
+          processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>,
+	  <c>gen_statem</c> and <c>gen_event</c> OTP
+          behaviour modules export this function, so callback modules for those behaviours
           need not supply their own.</p>
         <p>To obtain more information about a process, including its state, see
           <seealso marker="#get_status-1">get_status/1</seealso> and
@@ -290,6 +297,8 @@
           <c>gen_fsm</c> process, <c><anno>State</anno></c> is the tuple
           <c>{CurrentStateName, CurrentStateData}</c>, and <c><anno>NewState</anno></c>
           is a similar tuple that may contain a new state name, new state data, or both.
+	  The same applies for a <c>gen_statem</c> process but
+	  it names the tuple fields <c>{CurrentState,CurrentData}</c>.
           For a <c>gen_event</c> process, <c><anno>State</anno></c> is the tuple
           <c>{Module, Id, HandlerState}</c> where <c>Module</c> is the event handler's module name,
           <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without
@@ -304,7 +313,8 @@
           state, then regardless of process type, it may simply return its <c><anno>State</anno></c>
           argument.</p>
         <p>If a <c><anno>StateFun</anno></c> function crashes or throws an exception, then
-          for <c>gen_server</c> and <c>gen_fsm</c> processes, the original state of the process is
+          for <c>gen_server</c>, <c>gen_fsm</c> or <c>gen_statem</c> processes,
+	  the original state of the process is
           unchanged. For <c>gen_event</c> processes, a crashing or failing <c><anno>StateFun</anno></c>
           function means that only the state of the particular event handler it was working on when it
           failed or crashed is unchanged; it can still succeed in changing the states of other event
@@ -329,7 +339,8 @@
           <c>{callback_failed, StateFun, {Class, Reason}}</c>.</p>
         <p>The <c>system_replace_state/2</c> function is primarily useful for user-defined behaviours and
           modules that implement OTP <seealso marker="#special_process">special processes</seealso>. The
-          <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> OTP behaviour modules export this function,
+          <c>gen_server</c>, <c>gen_fsm</c>, <c>gen_statem</c> and
+	  <c>gen_event</c> OTP behaviour modules export this function,
           and so callback modules for those behaviours need not supply their own.</p>
       </desc>
     </func>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index cc09efc140..438c366f8e 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -44,8 +44,16 @@
 -export(
    [wakeup_from_hibernate/3]).
 
+%% Type exports for templates
+-export_type(
+   [event_type/0,
+    callback_mode/0,
+    state_function_result/0,
+    handle_event_result/0,
+    action/0]).
+
 %% Fix problem for doc build
--export_type([transition_option/0,state_callback_result/0]).
+-export_type([transition_option/0]).
 
 %%%==========================================================================
 %%% Interface functions.
@@ -84,7 +92,7 @@
 
 -type action() ::
 	%% During a state change:
-	%% * NewState and NewData are set.
+	%% * NextState and NewData are set.
 	%% * All action()s are executed in order of apperance.
 	%% * Postponing the current event is performed
 	%%   iff 'postpone' is 'true'.
@@ -119,7 +127,25 @@
 	{'reply', % Reply to a caller
 	 Caller :: caller(), Reply :: term()}.
 
--type state_callback_result() ::
+-type state_function_result() ::
+	{'next_state', % {next_state,NextStateName,NewData,[]}
+	 NextStateName :: state_name(),
+	 NewData :: data()} |
+	{'next_state', % State transition, maybe to the same state
+	 NextStateName :: state_name(),
+	 NewData :: data(),
+	 Actions :: [action()] | action()} |
+	common_state_callback_result().
+-type handle_event_result() ::
+	{'next_state', % {next_state,NextState,NewData,[]}
+	 NextState :: state(),
+	 NewData :: data()} |
+	{'next_state', % State transition, maybe to the same state
+	 NextState :: state(),
+	 NewData :: data(),
+	 Actions :: [action()] | action()} |
+	common_state_callback_result().
+-type common_state_callback_result() ::
 	'stop' | % {stop,normal}
 	{'stop', % Stop the server
 	 Reason :: term()} |
@@ -133,13 +159,6 @@
 	 Reason :: term(),
 	 Replies :: [reply_action()] | reply_action(),
 	 NewData :: data()} |
-	{'next_state', % {next_state,NewState,NewData,[]}
-	 NewState :: state(),
-	 NewData :: data()} |
-	{'next_state', % State transition, maybe to the same state
-	 NewState :: state(),
-	 NewData :: data(),
-	 Actions :: [action()] | action()} |
 	{'keep_state', % {keep_state,NewData,[]}
 	 NewData :: data()} |
 	{'keep_state', % Keep state, change data
@@ -171,7 +190,7 @@
 	    event_type(),
 	    EventContent :: term(),
 	    Data :: data()) ->
-    state_callback_result().
+    state_function_result().
 %%
 %% State callback for callback_mode() =:= handle_event_function.
 %%
@@ -182,7 +201,7 @@
 	    EventContent :: term(),
 	    State :: state(), % Current state
 	    Data :: data()) ->
-    state_callback_result().
+    handle_event_result().
 
 %% Clean up before the server terminates.
 -callback terminate(
@@ -514,7 +533,7 @@ enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent) ->
     %% The values should already have been type checked
     Name = gen:get_proc_name(Server),
     Debug = gen:debug_options(Name, Opts),
-    OldState = make_ref(), % Will be discarded by loop_event_actions/9
+    PrevState = make_ref(), % Will be discarded by loop_event_actions/9
     NewActions =
 	if
 	    is_list(Actions) ->
@@ -526,7 +545,7 @@ enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent) ->
       callback_mode => CallbackMode,
       module => Module,
       name => Name,
-      state => OldState,
+      state => PrevState,
       data => Data,
       timer => undefined,
       postponed => [],
@@ -534,7 +553,7 @@ enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent) ->
     loop_event_actions(
       Parent, Debug, S, [],
       {event,undefined}, % Will be discarded thanks to {postpone,false}
-      OldState, State, Data, NewActions).
+      PrevState, State, Data, NewActions).
 
 %%%==========================================================================
 %%%  gen callbacks
@@ -868,18 +887,18 @@ loop_event_result(
 		  exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
 	    %% Since we got back here Replies was bad
 	    terminate(Class, NewReason, Stacktrace, NewDebug, NewS, Q);
-	{next_state,NewState,NewData}
-	  when CallbackMode =:= state_functions, is_atom(NewState);
+	{next_state,NextState,NewData}
+	  when CallbackMode =:= state_functions, is_atom(NextState);
 	       CallbackMode =/= state_functions ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, []);
-	{next_state,NewState,NewData,Actions}
-	  when CallbackMode =:= state_functions, is_atom(NewState);
+	      State, NextState, NewData, []);
+	{next_state,NextState,NewData,Actions}
+	  when CallbackMode =:= state_functions, is_atom(NextState);
 	       CallbackMode =/= state_functions ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions);
+	      State, NextState, NewData, Actions);
 	{keep_state,NewData} ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
@@ -902,13 +921,13 @@ loop_event_result(
     end.
 
 loop_event_actions(
-  Parent, Debug, S, Events, Event, State, NewState, NewData, Actions) ->
+  Parent, Debug, S, Events, Event, State, NextState, NewData, Actions) ->
     Postpone = false, % Shall we postpone this event, true or false
     Hibernate = false,
     Timeout = undefined,
     NextEvents = [],
     loop_event_actions(
-      Parent, Debug, S, Events, Event, State, NewState, NewData,
+      Parent, Debug, S, Events, Event, State, NextState, NewData,
       if
 	  is_list(Actions) ->
 	      Actions;
@@ -920,19 +939,19 @@ loop_event_actions(
 %% Process all action()s
 loop_event_actions(
   Parent, Debug, S, Events, Event,
-  State, NewState, NewData, [Action|Actions],
+  State, NextState, NewData, [Action|Actions],
   Postpone, Hibernate, Timeout, NextEvents) ->
     case Action of
 	%% Actions that set options
 	postpone ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions,
+	      State, NextState, NewData, Actions,
 	      true, Hibernate, Timeout, NextEvents);
 	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions,
+	      State, NextState, NewData, Actions,
 	      NewPostpone, Hibernate, Timeout, NextEvents);
 	{postpone,_} ->
 	    ?TERMINATE(
@@ -940,12 +959,12 @@ loop_event_actions(
 	hibernate ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions,
+	      State, NextState, NewData, Actions,
 	      Postpone, true, Timeout, NextEvents);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions,
+	      State, NextState, NewData, Actions,
 	      Postpone, NewHibernate, Timeout, NextEvents);
 	{hibernate,_} ->
 	    ?TERMINATE(
@@ -953,12 +972,12 @@ loop_event_actions(
 	{timeout,infinity,_} -> % Clear timer - it will never trigger
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions,
+	      State, NextState, NewData, Actions,
 	      Postpone, Hibernate, undefined, NextEvents);
 	{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
-	      State, NewState, NewData, Actions,
+	      State, NextState, NewData, Actions,
 	      Postpone, Hibernate, NewTimeout, NextEvents);
 	{timeout,_,_} ->
 	    ?TERMINATE(
@@ -970,7 +989,7 @@ loop_event_actions(
 		    NewDebug = do_reply(Debug, S, Caller, Reply),
 		    loop_event_actions(
 		      Parent, NewDebug, S, Events, Event,
-		      State, NewState, NewData, Actions,
+		      State, NextState, NewData, Actions,
 		      Postpone, Hibernate, Timeout, NextEvents);
 		false ->
 		    ?TERMINATE(
@@ -981,7 +1000,7 @@ loop_event_actions(
 		true ->
 		    loop_event_actions(
 		      Parent, Debug, S, Events, Event,
-		      State, NewState, NewData, Actions,
+		      State, NextState, NewData, Actions,
 		      Postpone, Hibernate, Timeout,
 		      [{Type,Content}|NextEvents]);
 		false ->
@@ -996,7 +1015,7 @@ loop_event_actions(
 %% End of actions list
 loop_event_actions(
   Parent, Debug, #{postponed := P0} = S, Events, Event,
-  State, NewState, NewData, [],
+  State, NextState, NewData, [],
   Postpone, Hibernate, Timeout, NextEvents) ->
     %%
     %% All options have been collected and next_events are buffered.
@@ -1011,7 +1030,7 @@ loop_event_actions(
 	end,
     {Q2,P} = % Move all postponed events to queue if state change
 	if
-	    NewState =:= State ->
+	    NextState =:= State ->
 		{Events,P1};
 	    true ->
 		{lists:reverse(P1, Events),[]}
@@ -1024,9 +1043,9 @@ loop_event_actions(
 	  Debug, S,
 	  case Postpone of
 	      true ->
-		  {postpone,Event,NewState};
+		  {postpone,Event,NextState};
 	      false ->
-		  {consume,Event,NewState}
+		  {consume,Event,NextState}
 	  end),
     %% Have a peek on the event queue so we can avoid starting
     %% the state timer unless we have to
@@ -1057,7 +1076,7 @@ loop_event_actions(
     loop_events(
       Parent, NewDebug,
       S#{
-	state := NewState,
+	state := NextState,
 	data := NewData,
 	timer := Timer,
 	postponed := P,
-- 
cgit v1.2.3


From 447f3cf2d041670d93683de4fab02338b26fbaf1 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 3 Mar 2016 11:27:02 +0100
Subject: Rename state_timeout -> event_timeout

---
 lib/stdlib/doc/src/gen_statem.xml | 36 +++++++++++++++++++++++-------------
 lib/stdlib/src/gen_statem.erl     | 10 +++++-----
 2 files changed, 28 insertions(+), 18 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index db6a4e03ea..4489ddfb91 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -155,7 +155,7 @@ erlang:'!'            -----> Module:StateName/3
     <p>
       Inserting an event replaces the trick of calling your own
       state handling functions that you often would have to
-      resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
+      resort to in for example <seealso marker="gen_fsm">gen_fsm</seealso>
       to force processing an inserted event before others.
       If you for example in <c>gen_statem</c> postpone an event
       in one state and then call some other state function of yours,
@@ -529,17 +529,16 @@ ok
 	    all other events.
 	  </item>
 	  <item>
-	    If a
-            <seealso marker="#type-state_timeout">
-	      <em><c>state_timeout()</c></em>
+	    If an
+            <seealso marker="#type-event_timeout">
+	      <em><c>event_timeout()</c></em>
 	    </seealso>
 	    is set through
             <seealso marker="#type-action">
 	      <c>action() timeout</c>
 	    </seealso>
-	    a state timer may be started or a timeout zero event
-	    may be enqueued as the newest incoming, that is the last
-	    to process before going into <c>receive</c> for new events.
+	    an event timer may be started or a timeout zero event
+	    may be enqueued.
 	  </item>
 	  <item>
 	    The (possibly new)
@@ -588,7 +587,7 @@ ok
       </desc>
     </datatype>
     <datatype>
-      <name name="state_timeout" />
+      <name name="event_timeout" />
       <desc>
 	<p>
 	  Generate an event of
@@ -600,7 +599,8 @@ ok
 	  If the value is <c>infinity</c> no timer is started.
 	  If it is <c>0</c> the timeout event
 	  is immediately enqueued as the newest received
-	  (unless there are retried or inserted events to process).
+	  (unless there are retried or inserted events to process
+	  since then the timeout is cancelled).
 	  Also note that it is not possible nor needed
 	  to cancel this timeout since it is cancelled automatically
 	  by any other event.
@@ -653,15 +653,25 @@ ok
 	    </seealso>
 	    for this state transition.
 	  </item>
+	  <tag><c>Timeout</c></tag>
+	  <item>
+	    Short for <c>{timeout,Timeout}</c> that is
+	    the timeout message is the timeout time.
+	    This form exists to make the
+	    <seealso marker="#state_function">state function</seealso>
+	    return value <c>{next_state,NextState,NewData,Timeout}</c>
+	    allowed like for
+	    <seealso marker="gen_fsm#Module:StateName/2">
+	      gen_fsm Module:StateName/2</seealso>.
+	  </item>
 	  <tag><c>timeout</c></tag>
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() state_timeout()</c>
+	      <c>transition_option() event_timeout()</c>
 	    </seealso>
 	    to <c><anno>Time</anno></c> with the
-	    <c>EventContent</c> as <c><anno>Msg</anno></c>
-	    for the next state.
+	    <c>EventContent</c> as <c><anno>Msg</anno></c>.
 	  </item>
 	  <tag><c>reply_action()</c></tag>
 	  <item>Reply to a caller.</item>
@@ -1419,7 +1429,7 @@ ok
         <p>
 	  This function is called by a <c>gen_statem</c> when it should
           update its internal state during a release upgrade/downgrade,
-          i.e. when the instruction <c>{update,Module,Change,...}</c>
+          that is when the instruction <c>{update,Module,Change,...}</c>
           where <c>Change={advanced,Extra}</c> is given in
           the <c>appup</c> file. See
           <seealso marker="doc/design_principles:release_handling#instr">
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 438c366f8e..92e26bd7ed 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -77,7 +77,7 @@
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
 
 -type transition_option() ::
-	postpone() | hibernate() | state_timeout().
+	postpone() | hibernate() | event_timeout().
 -type postpone() ::
 	%% If 'true' postpone the current event
 	%% and retry it when the state changes (=/=)
@@ -85,7 +85,7 @@
 -type hibernate() ::
 	%% If 'true' hibernate the server instead of going into receive
 	boolean().
--type state_timeout() ::
+-type event_timeout() ::
 	%% Generate a ('timeout', Msg, ...) event after Time
 	%% unless some other event is delivered
 	Time :: timeout().
@@ -111,9 +111,9 @@
 	'hibernate' | % Set the hibernate option
 	{'hibernate', Hibernate :: hibernate()} |
 	%%
-	(Timeout :: state_timeout()) | % {timeout,Timeout}
-	{'timeout', % Set the timeout option
-	 Time :: state_timeout(), Msg :: term()} |
+	(Timeout :: event_timeout()) | % {timeout,Timeout}
+	{'timeout', % Set the event timeout option
+	 Time :: event_timeout(), Msg :: term()} |
 	%%
 	reply_action() |
 	%%
-- 
cgit v1.2.3


From 65d2eecef2dedb012abcc76c855b8da90934f10c Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 4 Mar 2016 14:28:27 +0100
Subject: Fix broken documenation reference

---
 lib/stdlib/doc/src/gen_statem.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 4489ddfb91..4708fc1301 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -361,7 +361,7 @@ ok
 	<p>
 	  Debug option that can be used when starting
 	  a <c>gen_statem</c> server through for example
-	  <seealso marker="#enter_loop/4">enter_loop/4</seealso>.
+	  <seealso marker="#enter_loop/5">enter_loop/5</seealso>.
 	</p>
 	<p>
 	  For every entry in <c><anno>Dbgs</anno></c>
-- 
cgit v1.2.3


From 0eddc557de9b0a996ab42aefd66f3229a06f6675 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 17 Mar 2016 15:41:26 +0100
Subject: Do documentation improvements from Fred Hebert

---
 lib/stdlib/doc/src/gen_statem.xml | 66 ++++++++++++++++++++++++++++++++-------
 1 file changed, 54 insertions(+), 12 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 4708fc1301..90d2326954 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -35,10 +35,10 @@
       A behaviour module for implementing a state machine.
       Two callback modes are supported.  One for a finite state
       machine like <seealso marker="gen_fsm">gen_fsm</seealso>
-      that require the state to be an atom and use that state as
+      that requires the state to be an atom and use that state as
       the name of the callback function for a particular state,
-      and one without restriction on the state that use the same
-      callback function for all states.
+      and one without restriction on the state data type
+      that uses the same callback function for all states.
     </p>
     <p>
       A generic state machine process (<c>gen_statem</c>) implemented
@@ -96,7 +96,7 @@ erlang:'!'            -----> Module:StateName/3
     <p>
       When
       <seealso marker="#type-callback_mode">callback_mode</seealso>
-      is <c>state_functions</c> the state has to be an atom and
+      is <c>state_functions</c>, the state has to be an atom and
       is used as the state function name.  See
       <seealso marker="#Module:StateName/3">
         <c>Module:StateName/3</c>
@@ -127,8 +127,8 @@ erlang:'!'            -----> Module:StateName/3
       <seealso marker="#state_function">state function</seealso>
       in that order.  The state function can postpone an event
       so it is not retried in the current state.
-      After a state change all enqueued events (including postponed)
-      are again presented to the state function.
+      After a state change all enqueued events (including postponed ones)
+      are presented again to the state function.
     </p>
     <p>
       The <c>gen_statem</c> event queue model is sufficient
@@ -177,8 +177,10 @@ erlang:'!'            -----> Module:StateName/3
     </p>
     <p>
       Note that a <c>gen_statem</c> does not trap exit signals
-      automatically, this must be explicitly initiated by
-      the callback module.
+      automatically, this must be explicitly initiated in
+      the callback module (by calling
+      <seealso marker="erts:erlang#process_flag/2">
+	<c>process_flag(trap_exit, true)</c></seealso>.
     </p>
     <p>
       Unless otherwise stated, all functions in this module fail if
@@ -293,6 +295,42 @@ ok
      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>
+      And just to compare styles here is the same example using
+      <seealso marker="#type-callback_mode">
+	<c>callback_mode</c>
+      </seealso>
+      <c>state_functions</c>, or rather here is code to replace
+      from the <c>init/1</c> function of the <c>pushbutton</c>
+      example module above:
+    </p>
+    <code type="erl">
+init([]) ->
+    %% Set the callback mode and initial state + data.
+    %% Data is used only as a counter.
+    State = off, Data = 0,
+    {handle_event_function,State,Data}.
+
+
+%%% Event handling
+
+handle_event({call,Caller}, push, off, Data) ->
+    %% Go to 'on', increment count and reply
+    %% that the resulting status is 'on'
+    {next_state,on,Data+1,[{reply,Caller,on}]};
+handle_event({call,Caller}, push, on, Data) ->
+    %% Go to 'off' and reply that the resulting status is 'off'
+    {next_state,off,Data,[{reply,Caller,off}]};
+%%
+%% Event handling common to all states
+handle_event({call,Caller}, get_count, State, Data) ->
+    %% Reply with the current count
+    {next_state,State,Data,[{reply,Caller,Data}]};
+handle_event(_, _, State, Data) ->
+    %% Ignore all other events
+    {next_state,State,Data}.
+    </code>
   </section>
 
   <datatypes>
@@ -564,8 +602,8 @@ ok
       <desc>
 	<p>
 	  If <c>true</c> postpone the current event and retry
-	  it when the state changes that is:
-	  <c>NextState =/= State</c>.
+	  it when the state changes
+	  (<c>NextState =/= State</c>).
 	</p>
       </desc>
     </datatype>
@@ -778,14 +816,18 @@ ok
 	    The <c>gen_statem</c> will keep the current state, or
 	    do a state transition to the current state if you like,
 	    set <c><anno>NewData</anno></c>
-	    and execute all <c><anno>Actions</anno></c>
+	    and execute all <c><anno>Actions</anno></c>.
+	    This is the same as
+	    <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>.
 	  </item>
 	  <tag><c>keep_state_and_data</c></tag>
 	  <item>
 	    The <c>gen_statem</c> will keep the current state or
 	    do a state transition to the current state if you like,
 	    keep the current server data,
-	    and execute all <c><anno>Actions</anno></c>
+	    and execute all <c><anno>Actions</anno></c>.
+	    This is the same as
+	    <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>.
 	  </item>
 	</taglist>
 	<p>
-- 
cgit v1.2.3


From 2cd331fec3e08799bdd482399e8c969102e1142f Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 17 Mar 2016 16:05:35 +0100
Subject: Change Caller -> From as suggested by Fred Hebert

---
 lib/stdlib/doc/src/gen_statem.xml | 50 +++++++++++++++++++--------------------
 lib/stdlib/src/gen_statem.erl     | 46 +++++++++++++++++------------------
 2 files changed, 48 insertions(+), 48 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 90d2326954..83f7dc1c8a 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -253,23 +253,23 @@ init([]) ->
 
 %%% State functions
 
-off({call,Caller}, push, Data) ->
+off({call,From}, push, Data) ->
     %% Go to 'on', increment count and reply
     %% that the resulting status is 'on'
-    {next_state,on,Data+1,[{reply,Caller,on}]};
+    {next_state,on,Data+1,[{reply,From,on}]};
 off(EventType, EventContent, Data) ->
     handle_event(EventType, EventContent, Data).
 
-on({call,Caller}, push, Data) ->
+on({call,From}, push, Data) ->
     %% Go to 'off' and reply that the resulting status is 'off'
-    {next_state,off,Data,[{reply,Caller,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,Caller}, get_count, Data) ->
+handle_event({call,From}, get_count, Data) ->
     %% Reply with the current count
-    {keep_state,Data,[{reply,Caller,Data}]};
+    {keep_state,Data,[{reply,From,Data}]};
 handle_event(_, _, Data) ->
     %% Ignore all other events
     {keep_state,Data}.
@@ -315,18 +315,18 @@ init([]) ->
 
 %%% Event handling
 
-handle_event({call,Caller}, push, off, Data) ->
+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,Caller,on}]};
-handle_event({call,Caller}, push, on, Data) ->
+    {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,Caller,off}]};
+    {next_state,off,Data,[{reply,From,off}]};
 %%
 %% Event handling common to all states
-handle_event({call,Caller}, get_count, State, Data) ->
+handle_event({call,From}, get_count, State, Data) ->
     %% Reply with the current count
-    {next_state,State,Data,[{reply,Caller,Data}]};
+    {next_state,State,Data,[{reply,From,Data}]};
 handle_event(_, _, State, Data) ->
     %% Ignore all other events
     {next_state,State,Data}.
@@ -429,12 +429,12 @@ handle_event(_, _, State, Data) ->
     </datatype>
 
     <datatype>
-      <name name="caller" />
+      <name name="from" />
       <desc>
 	<p>
 	  Destination to use when replying through for example the
 	  <seealso marker="#type-action">
-	    action() {reply,Caller,Reply}
+	    action() {reply,From,Reply}
 	  </seealso>
 	  to a process that has called the <c>gen_statem</c> server using
 	  <seealso marker="#call/2">call/2</seealso>.
@@ -483,7 +483,7 @@ handle_event(_, _, State, Data) ->
       <desc>
 	<p>
 	  External events are of 3 different type:
-	  <c>{call,<anno>Caller</anno>}</c>, <c>cast</c> or <c>info</c>.
+	  <c>{call,<anno>From</anno>}</c>, <c>cast</c> or <c>info</c>.
 	  <seealso marker="#call/2">Calls</seealso>
 	  (synchronous) and
 	  <seealso marker="#cast/2">casts</seealso>
@@ -739,9 +739,9 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  Reply to a caller waiting for a reply in
 	  <seealso marker="#call/2"><c>call/2</c></seealso>.
-          <c><anno>Caller</anno></c> must be the term from the
+          <c><anno>From</anno></c> must be the term from the
 	  <seealso marker="#type-event_type">
-	    <c>{call,<anno>Caller</anno>}</c>
+	    <c>{call,<anno>From</anno>}</c>
 	  </seealso>
 	  argument to the
 	  <seealso marker="#state_function">state function</seealso>.
@@ -1029,14 +1029,14 @@ handle_event(_, _, State, Data) ->
 	  The <c>gen_statem</c> will call the
 	  <seealso marker="#state_function">state function</seealso> with
 	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
-	  <c>{call,Caller}</c> and event content
+	  <c>{call,From}</c> and event content
 	  <c><anno>Request</anno></c>.
 	</p>
 	<p>
 	  A <c><anno>Reply</anno></c> is generated when a
 	  <seealso marker="#state_function">state function</seealso>
 	  returns with
-	  <c>{reply,Caller,<anno>Reply</anno>}</c> as one
+	  <c>{reply,From,<anno>Reply</anno>}</c> as one
 	  <seealso marker="#type-action"><c>action()</c></seealso>,
 	  and that <c><anno>Reply</anno></c> becomes the return value
 	  of this function.
@@ -1100,13 +1100,13 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#state_function">state function</seealso>.
 	</p>
         <p>
-	  <c><anno>Caller</anno></c> must be the term from the
+	  <c><anno>From</anno></c> must be the term from the
 	  <seealso marker="#type-event_type">
-	    <c>{call,<anno>Caller</anno>}</c>
+	    <c>{call,<anno>From</anno>}</c>
 	  </seealso>
 	  argument to the
 	  <seealso marker="#state_function">state function</seealso>.
-	  <c><anno>Caller</anno></c> and <c><anno>Reply</anno></c>
+	  <c><anno>From</anno></c> and <c><anno>Reply</anno></c>
 	  can also be specified using a
 	  <seealso marker="#type-reply_action">
 	    <c>reply_action()</c>
@@ -1340,15 +1340,15 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<p>
 	  If <c>EventType</c> is
-	  <seealso marker="#type-event_type"><c>{call,Caller}</c></seealso>
+	  <seealso marker="#type-event_type"><c>{call,From}</c></seealso>
 	  the caller is waiting for a reply.  The reply can be sent
 	  from this or from any other
 	  <seealso marker="#state_function">state function</seealso>
-	  by returning with <c>{reply,Caller,Reply}</c> in
+	  by returning with <c>{reply,From,Reply}</c> in
 	  <seealso marker="#type-action">Actions</seealso>, in
 	  <seealso marker="#type-reply_action">Replies</seealso>
 	  or by calling
-	  <seealso marker="#reply/2"><c>reply(Caller, Reply)</c></seealso>.
+	  <seealso marker="#reply/2"><c>reply(From, Reply)</c></seealso>.
 	</p>
 	<p>
 	  If this function returns with a next state that
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 92e26bd7ed..82ac5824eb 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -59,7 +59,7 @@
 %%% Interface functions.
 %%%==========================================================================
 
--type caller() ::
+-type from() ::
 	{To :: pid(), Tag :: term()}. % Reply-to specifier for call
 
 -type state() ::
@@ -71,7 +71,7 @@
 -type data() :: term().
 
 -type event_type() ::
-	{'call',Caller :: caller()} | 'cast' |
+	{'call',From :: from()} | 'cast' |
 	'info' | 'timeout' | 'internal'.
 
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
@@ -125,7 +125,7 @@
 	 EventContent :: term()}.
 -type reply_action() ::
 	{'reply', % Reply to a caller
-	 Caller :: caller(), Reply :: term()}.
+	 From :: from(), Reply :: term()}.
 
 -type state_function_result() ::
 	{'next_state', % {next_state,NextStateName,NewData,[]}
@@ -253,13 +253,13 @@ callback_mode(CallbackMode) ->
 	    false
     end.
 %%
-caller({Pid,_}) when is_pid(Pid) ->
+from({Pid,_}) when is_pid(Pid) ->
     true;
-caller(_) ->
+from(_) ->
     false.
 %%
-event_type({call,Caller}) ->
-    caller(Caller);
+event_type({call,From}) ->
+    from(From);
 event_type(Type) ->
     case Type of
 	cast ->
@@ -378,7 +378,7 @@ cast(ServerRef, Msg) when is_pid(ServerRef) ->
     send(ServerRef, wrap_cast(Msg)).
 
 %% Call a state machine (synchronous; a reply is expected) that
-%% arrives with type {call,Caller}
+%% arrives with type {call,From}
 -spec call(ServerRef :: server_ref(), Request :: term()) -> Reply :: term().
 call(ServerRef, Request) ->
     call(ServerRef, Request, infinity).
@@ -437,12 +437,12 @@ call(ServerRef, Request, Timeout) ->
 
 %% Reply from a state machine callback to whom awaits in call/2
 -spec reply([reply_action()] | reply_action()) -> ok.
-reply({reply,Caller,Reply}) ->
-    reply(Caller, Reply);
+reply({reply,From,Reply}) ->
+    reply(From, Reply);
 reply(Replies) when is_list(Replies) ->
     replies(Replies).
 %%
--spec reply(Caller :: caller(), Reply :: term()) -> ok.
+-spec reply(From :: from(), Reply :: term()) -> ok.
 reply({To,Tag}, Reply) when is_pid(To) ->
     Msg = {Tag,Reply},
     try To ! Msg of
@@ -509,8 +509,8 @@ enter_loop(Module, Opts, CallbackMode, State, Data, Server, Actions) ->
 wrap_cast(Event) ->
     {'$gen_cast',Event}.
 
-replies([{reply,Caller,Reply}|Replies]) ->
-    reply(Caller, Reply),
+replies([{reply,From,Reply}|Replies]) ->
+    reply(From, Reply),
     replies(Replies);
 replies([]) ->
     ok.
@@ -782,8 +782,8 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) ->
 		    end,
 		    Event =
 			case Msg of
-			    {'$gen_call',Caller,Request} ->
-				{{call,Caller},Request};
+			    {'$gen_call',From,Request} ->
+				{{call,From},Request};
 			    {'$gen_cast',E} ->
 				{cast,E};
 			    _ ->
@@ -983,10 +983,10 @@ loop_event_actions(
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
 	%% Actual actions
-	{reply,Caller,Reply} ->
-	    case caller(Caller) of
+	{reply,From,Reply} ->
+	    case from(From) of
 		true ->
-		    NewDebug = do_reply(Debug, S, Caller, Reply),
+		    NewDebug = do_reply(Debug, S, From, Reply),
 		    loop_event_actions(
 		      Parent, NewDebug, S, Events, Event,
 		      State, NextState, NewData, Actions,
@@ -1101,17 +1101,17 @@ do_reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
 do_reply_then_terminate(
   Class, Reason, Stacktrace, Debug, S, Q, [R|Rs]) ->
     case R of
-	{reply,{_To,_Tag}=Caller,Reply} ->
-	    NewDebug = do_reply(Debug, S, Caller, Reply),
+	{reply,{_To,_Tag}=From,Reply} ->
+	    NewDebug = do_reply(Debug, S, From, Reply),
 	    do_reply_then_terminate(
 	      Class, Reason, Stacktrace, NewDebug, S, Q, Rs);
 	_ ->
 	    [error,{bad_action,R},?STACKTRACE(),Debug]
     end.
 
-do_reply(Debug, S, Caller, Reply) ->
-    reply(Caller, Reply),
-    sys_debug(Debug, S, {out,Reply,Caller}).
+do_reply(Debug, S, From, Reply) ->
+    reply(From, Reply),
+    sys_debug(Debug, S, {out,Reply,From}).
 
 
 terminate(
-- 
cgit v1.2.3


From 6bf2768c6836440634019d69231534ed69fcf982 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 18 Mar 2016 10:23:48 +0100
Subject: Do more intricate Fred Hebert doc changes

---
 lib/stdlib/doc/src/gen_statem.xml | 126 +++++++++++++++++++++-----------------
 lib/stdlib/src/gen_statem.erl     |  10 +--
 2 files changed, 74 insertions(+), 62 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 83f7dc1c8a..bd70c4c37e 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -127,8 +127,7 @@ erlang:'!'            -----> Module:StateName/3
       <seealso marker="#state_function">state function</seealso>
       in that order.  The state function can postpone an event
       so it is not retried in the current state.
-      After a state change all enqueued events (including postponed ones)
-      are presented again to the state function.
+      After a state change the queue restarts with the postponed events.
     </p>
     <p>
       The <c>gen_statem</c> event queue model is sufficient
@@ -157,10 +156,10 @@ erlang:'!'            -----> Module:StateName/3
       state handling functions that you often would have to
       resort to in for example <seealso marker="gen_fsm">gen_fsm</seealso>
       to force processing an inserted event before others.
-      If you for example in <c>gen_statem</c> postpone an event
-      in one state and then call some other state function of yours,
-      you have not changed states and hence the postponed event
-      will not be retried, which is logical but might be confusing.
+      A warning, though: if you in <c>gen_statem</c> for example
+      postpone an event in one state and then call some other state function of yours,
+      you have not changed states and hence the postponed event will not be retried,
+      which is logical but might be confusing.
     </p>
     <p>
       See the type
@@ -302,8 +301,8 @@ ok
 	<c>callback_mode</c>
       </seealso>
       <c>state_functions</c>, or rather here is code to replace
-      from the <c>init/1</c> function of the <c>pushbutton</c>
-      example module above:
+      from the <c>init/1</c> function of the <c>pushbutton.erl</c>
+      example file above:
     </p>
     <code type="erl">
 init([]) ->
@@ -364,8 +363,8 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<p>It can be:</p>
 	<taglist>
-	  <tag><c>pid()</c></tag>
-	  <tag><c>LocalName</c></tag>
+	  <tag><c>pid()</c><br />
+	  <c>LocalName</c></tag>
 	  <item>The <c>gen_statem</c> is locally registered.</item>
 	  <tag><c>Name, Node</c></tag>
 	  <item>
@@ -489,13 +488,10 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#cast/2">casts</seealso>
 	  originate from the corresponding API functions.
 	  For calls the event contain whom to reply to.
-	  Type <c>info</c> originates from
-	  regular process messages sent
-	  to the <c>gen_statem</c>.
-	  It is also possible for the state machine
-	  implementation to insert events to itself,
-	  in particular of types
-	  <c>timeout</c> and <c>internal</c>.
+	  Type <c>info</c> originates from regular process messages sent
+	  to the <c>gen_statem</c>. It is also possible for the state machine
+	  implementation to generate events of types
+	  <c>timeout</c> and <c>internal</c> to itself.
 	</p>
       </desc>
     </datatype>
@@ -559,7 +555,7 @@ handle_event(_, _, State, Data) ->
             is reset to start with the oldest postponed.
 	  </item>
 	  <item>
-	    All events inserted with
+	    All events stored with
 	    <seealso marker="#type-action">
 	      <c>action() next_event</c>
 	    </seealso>
@@ -634,14 +630,21 @@ handle_event(_, _, State, Data) ->
 	  event arrives in which case this timeout is cancelled.
 	  Note that a retried or inserted event
 	  counts just like a new in this respect.
-	  If the value is <c>infinity</c> no timer is started.
-	  If it is <c>0</c> the timeout event
-	  is immediately enqueued as the newest received
-	  (unless there are retried or inserted events to process
-	  since then the timeout is cancelled).
-	  Also note that it is not possible nor needed
-	  to cancel this timeout since it is cancelled automatically
-	  by any other event.
+	</p>
+	<p>
+	  If the value is <c>infinity</c> no timer is started since
+	  it will never trigger anyway.
+	</p>
+	<p>
+	  If the value is <c>0</c> the timeout event is immediately enqueued
+	  unless there already are enqueued events since then the
+	  timeout is immediately cancelled.
+	  This is a feature ensuring that a timeout <c>0</c> event
+	  will be processed before any not yet received external event.
+	</p>
+	<p>
+	  Note that it is not possible nor needed to cancel this timeout
+	  since it is cancelled automatically by any other event.
 	</p>
       </desc>
     </datatype>
@@ -658,16 +661,19 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<p>
 	  Actions are executed in the containing list order.
-	  The order matters for some actions such as <c>next_event</c>
-	  and <c>reply_action()</c>.
 	</p>
 	<p>
 	  Actions that set
 	  <seealso marker="#type-transition_option">
 	    transition options
 	  </seealso>
-	  overrides any previous of the same kind,
+	  overrides any previous of the same type,
 	  so the last in the containing list wins.
+	  For example the last
+	  <seealso marker="#type-event_timeout">
+	    <c>event_timeout()</c>
+	  </seealso>
+	  overrides any other <c>event_timeout()</c> in the list.
 	</p>
 	<taglist>
 	  <tag><c>postpone</c></tag>
@@ -693,7 +699,7 @@ handle_event(_, _, State, Data) ->
 	  </item>
 	  <tag><c>Timeout</c></tag>
 	  <item>
-	    Short for <c>{timeout,Timeout}</c> that is
+	    Short for <c>{timeout,Timeout,Timeout}</c> that is
 	    the timeout message is the timeout time.
 	    This form exists to make the
 	    <seealso marker="#state_function">state function</seealso>
@@ -708,27 +714,33 @@ handle_event(_, _, State, Data) ->
 	    <seealso marker="#type-transition_option">
 	      <c>transition_option() event_timeout()</c>
 	    </seealso>
-	    to <c><anno>Time</anno></c> with the
-	    <c>EventContent</c> as <c><anno>Msg</anno></c>.
+	    to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>.
 	  </item>
 	  <tag><c>reply_action()</c></tag>
 	  <item>Reply to a caller.</item>
 	  <tag><c>next_event</c></tag>
 	  <item>
-	    Insert the given <c><anno>EventType</anno></c>
-	    and <c><anno>EventContent</anno></c> as the next to process.
-	    This will bypass any events in the process mailbox as well
-	    as any other queued events.
-	    All <c>next_event</c> actions
-	    in the containing list are buffered and inserted
-	    after the actions have been done
-	    so that the first in the list will be the first to process.
-	    An event of type
-	    <seealso marker="#type-event_type">
-	      <c>internal</c>
-	    </seealso>
-	    should be used when you want to reliably distinguish
-	    an event inserted this way from any external event.
+	      Store the given <c><anno>EventType</anno></c>
+	      and <c><anno>EventContent</anno></c> for insertion after all
+	      actions have been executed.
+	  </item>
+	  <item>
+	    <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
+	      will become the first to process.
+	    </p>
+	  </item>
+	  <item>
+	    <p>
+	      An event of type
+	      <seealso marker="#type-event_type">
+		<c>internal</c>
+	      </seealso>
+	      should be used when you want to reliably distinguish
+	      an event inserted this way from any external event.
+	    </p>
 	  </item>
 	</taglist>
       </desc>
@@ -1047,17 +1059,17 @@ handle_event(_, _, State, Data) ->
 	  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.
-	  <note>
-	    <p>
-	      To avoid getting a late reply in the caller's
-	      inbox this function spawns a proxy process that
-	      does the call.  A late reply gets delivered to the
-	      dead proxy process hence gets discarded.  This is
-	      less efficient than using
-	      <c><anno>Timeout</anno> =:= infinity</c>.
-	    </p>
-	  </note>
 	</p>
+	<note>
+	  <p>
+	    To avoid getting a late reply in the caller's
+	    inbox this function spawns a proxy process that
+	    does the call.  A late reply gets delivered to the
+	    dead proxy process hence gets discarded.  This is
+	    less efficient than using
+	    <c><anno>Timeout</anno> =:= infinity</c>.
+	  </p>
+	</note>
         <p>
 	  The call may fail for example if the <c>gen_statem</c> dies
 	  before or during this function call.
@@ -1218,7 +1230,7 @@ handle_event(_, _, State, Data) ->
     <title>CALLBACK FUNCTIONS</title>
     <p>
       The following functions should be exported from a
-      <c><c>gen_statem</c></c> callback module.
+      <c>gen_statem</c> callback module.
     </p>
   </section>
   <funcs>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 82ac5824eb..9c1e126507 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -86,7 +86,7 @@
 	%% If 'true' hibernate the server instead of going into receive
 	boolean().
 -type event_timeout() ::
-	%% Generate a ('timeout', Msg, ...) event after Time
+	%% Generate a ('timeout', EventContent, ...) event after Time
 	%% unless some other event is delivered
 	Time :: timeout().
 
@@ -113,7 +113,7 @@
 	%%
 	(Timeout :: event_timeout()) | % {timeout,Timeout}
 	{'timeout', % Set the event timeout option
-	 Time :: event_timeout(), Msg :: term()} |
+	 Time :: event_timeout(), EventContent :: term()} |
 	%%
 	reply_action() |
 	%%
@@ -1054,17 +1054,17 @@ loop_event_actions(
 	    undefined ->
 		%% No state timeout has been requested
 		{Q3,undefined};
-	    {timeout,Time,Msg} ->
+	    {timeout,Time,EventContent} ->
 		%% A state timeout has been requested
 		case Q3 of
 		    [] when Time =:= 0 ->
 			%% Immediate timeout - simulate it
 			%% so we do not get the timeout message
 			%% after any received event
-			{[{timeout,Msg}],undefined};
+			{[{timeout,EventContent}],undefined};
 		    [] ->
 			%% Actually start a timer
-			{Q3,erlang:start_timer(Time, self(), Msg)};
+			{Q3,erlang:start_timer(Time, self(), EventContent)};
 		    _ ->
 			%% Do not start a timer since any queued
 			%% event cancels the state timer so we pretend
-- 
cgit v1.2.3


From 9db6054d674969fef314bf8676b6f9b583af3bef Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 12 Apr 2016 14:30:02 +0200
Subject: Fix missing short forms for event timeout

---
 lib/stdlib/src/gen_statem.erl        | 75 +++++++++++++++++++++---------------
 lib/stdlib/test/gen_statem_SUITE.erl |  8 ++--
 2 files changed, 48 insertions(+), 35 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 9c1e126507..b3a149a569 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -942,12 +942,32 @@ loop_event_actions(
   State, NextState, NewData, [Action|Actions],
   Postpone, Hibernate, Timeout, NextEvents) ->
     case Action of
+	%% Actual actions
+	{reply,From,Reply} ->
+	    case from(From) of
+		true ->
+		    NewDebug = do_reply(Debug, S, From, Reply),
+		    loop_event_actions(
+		      Parent, NewDebug, S, Events, Event,
+		      State, NextState, NewData, Actions,
+		      Postpone, Hibernate, Timeout, NextEvents);
+		false ->
+		    ?TERMINATE(
+		       error, {bad_action,Action}, Debug, S, [Event|Events])
+	    end;
+	{next_event,Type,Content} ->
+	    case event_type(Type) of
+		true ->
+		    loop_event_actions(
+		      Parent, Debug, S, Events, Event,
+		      State, NextState, NewData, Actions,
+		      Postpone, Hibernate, Timeout,
+		      [{Type,Content}|NextEvents]);
+		false ->
+		    ?TERMINATE(
+		       error, {bad_action,Action}, Debug, S, [Event|Events])
+	    end;
 	%% Actions that set options
-	postpone ->
-	    loop_event_actions(
-	      Parent, Debug, S, Events, Event,
-	      State, NextState, NewData, Actions,
-	      true, Hibernate, Timeout, NextEvents);
 	{postpone,NewPostpone} when is_boolean(NewPostpone) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
@@ -956,11 +976,11 @@ loop_event_actions(
 	{postpone,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
-	hibernate ->
+	postpone ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NextState, NewData, Actions,
-	      Postpone, true, Timeout, NextEvents);
+	      true, Hibernate, Timeout, NextEvents);
 	{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
@@ -969,6 +989,11 @@ loop_event_actions(
 	{hibernate,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
+	hibernate ->
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NextState, NewData, Actions,
+	      Postpone, true, Timeout, NextEvents);
 	{timeout,infinity,_} -> % Clear timer - it will never trigger
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
@@ -982,31 +1007,17 @@ loop_event_actions(
 	{timeout,_,_} ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events]);
-	%% Actual actions
-	{reply,From,Reply} ->
-	    case from(From) of
-		true ->
-		    NewDebug = do_reply(Debug, S, From, Reply),
-		    loop_event_actions(
-		      Parent, NewDebug, S, Events, Event,
-		      State, NextState, NewData, Actions,
-		      Postpone, Hibernate, Timeout, NextEvents);
-		false ->
-		    ?TERMINATE(
-		       error, {bad_action,Action}, Debug, S, [Event|Events])
-	    end;
-	{next_event,Type,Content} ->
-	    case event_type(Type) of
-		true ->
-		    loop_event_actions(
-		      Parent, Debug, S, Events, Event,
-		      State, NextState, NewData, Actions,
-		      Postpone, Hibernate, Timeout,
-		      [{Type,Content}|NextEvents]);
-		false ->
-		    ?TERMINATE(
-		       error, {bad_action,Action}, Debug, S, [Event|Events])
-	    end;
+	infinity -> % Clear timer - it will never trigger
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NextState, NewData, Actions,
+	      Postpone, Hibernate, undefined, NextEvents);
+	Time when is_integer(Time), Time >= 0 ->
+	    NewTimeout = {timeout,Time,Time},
+	    loop_event_actions(
+	      Parent, Debug, S, Events, Event,
+	      State, NextState, NewData, Actions,
+	      Postpone, Hibernate, NewTimeout, NextEvents);
 	_ ->
 	    ?TERMINATE(
 	       error, {bad_action,Action}, Debug, S, [Event|Events])
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 573a64bbb7..27fb7d9650 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -1305,10 +1305,10 @@ terminate(_Reason, _State, _Data) ->
 
 idle(cast, {connect,Pid}, Data) ->
     Pid ! accept,
-    {next_state,wfor_conf,Data};
+    {next_state,wfor_conf,Data,infinity}; % NoOp timeout just to test API
 idle({call,From}, connect, Data) ->
     gen_statem:reply(From, accept),
-    {next_state,wfor_conf,Data};
+    {next_state,wfor_conf,Data,infinity}; % NoOp timeout just to test API
 idle(cast, badreturn, _Data) ->
     badreturn;
 idle({call,_From}, badreturn, _Data) ->
@@ -1343,13 +1343,15 @@ idle(Type, Content, Data) ->
 
 timeout(timeout, idle, {From,Time}) ->
     TRef = erlang:start_timer(Time, self(), ok),
+    {keep_state,{From,TRef},0}; % Immediate timeout 0
+timeout(timeout, 0, {From,TRef}) ->
     {next_state,timeout2,{From,TRef},
      [{timeout,1,should_be_cancelled},
       postpone]}; % Should cancel state timeout
 timeout(_, _, _) ->
     keep_state_and_data.
 
-timeout2(timeout, idle, _) ->
+timeout2(timeout, 0, _) ->
     keep_state_and_data;
 timeout2(timeout, Reason, _) ->
     {stop,Reason};
-- 
cgit v1.2.3


From a2f3c685b5aeac798e12302cf8fe7df13184b669 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 15 Apr 2016 10:09:54 +0200
Subject: Introduce corrections from Fred Hebert and Ingela

---
 lib/stdlib/doc/src/gen_statem.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index bd70c4c37e..c21398d64d 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -45,7 +45,7 @@
       using this module will have a standard set of interface functions
       and include functionality for tracing and error reporting.
       It will also fit into an OTP supervision tree. Refer to
-      <seealso marker="doc/design_principles:gen_server_concepts">
+      <seealso marker="doc/design_principles:statem">
         OTP Design Principles
       </seealso>
       for more information.
-- 
cgit v1.2.3


From 26b3c7d60d52d8a7be006b06d856bb0f7276e77a Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 21 Apr 2016 15:58:52 +0200
Subject: Modify code_change/4 to return CallbackMode

Also move check of non-atom states in callback mode
state_functions to where the state function is called.
This gives homogenous diagnostics for state functions,
code_change/4 and system_replace_state StateFun.

Irregularities pointed out by James Fish.
---
 lib/stdlib/doc/src/gen_statem.xml    | 71 ++++++++++++++++++++++--------------
 lib/stdlib/src/gen_statem.erl        | 60 +++++++++++++++---------------
 lib/stdlib/test/gen_statem_SUITE.erl |  8 ++--
 3 files changed, 79 insertions(+), 60 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index c21398d64d..adca3673be 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -32,8 +32,9 @@
   <modulesummary>Generic State Machine Behaviour</modulesummary>
   <description>
     <p>
-      A behaviour module for implementing a state machine.
-      Two callback modes are supported.  One for a finite state
+      A behaviour module for implementing a state machine. Two
+      <seealso marker="#type-callback_mode"><em>callback modes</em></seealso>
+      are supported.  One for a finite state
       machine like <seealso marker="gen_fsm">gen_fsm</seealso>
       that requires the state to be an atom and use that state as
       the name of the callback function for a particular state,
@@ -89,13 +90,13 @@ erlang:'!'            -----> Module:StateName/3
       The "<em>state function</em>" for a specific
       <seealso marker="#type-state">state</seealso>
       in a <c>gen_statem</c> is the callback function that is called
-      for all events in this state, and is selected depending on
-      <seealso marker="#type-callback_mode">callback_mode</seealso>
+      for all events in this state, and is selected depending on which
+      <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
       that the implementation specifies when the the server starts.
     </p>
     <p>
-      When
-      <seealso marker="#type-callback_mode">callback_mode</seealso>
+      When the
+      <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
       is <c>state_functions</c>, the state has to be an atom and
       is used as the state function name.  See
       <seealso marker="#Module:StateName/3">
@@ -110,7 +111,8 @@ erlang:'!'            -----> Module:StateName/3
       </seealso> makes the state name <c>terminate</c> unusable.
     </p>
     <p>
-      When <seealso marker="#type-callback_mode">callback_mode</seealso>
+      When the
+      <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
       is <c>handle_event_function</c> the state can be any term
       and the state function name is
       <seealso marker="#Module:handle_event/4">
@@ -208,9 +210,7 @@ erlang:'!'            -----> Module:StateName/3
     <p>
       This example shows a simple pushbutton model
       for a toggling pushbutton implemented with
-      <seealso marker="#type-callback_mode">
-	callback_mode()
-      </seealso>
+      <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
       <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
@@ -226,6 +226,7 @@ erlang:'!'            -----> Module:StateName/3
 -export([on/3,off/3]).
 
 name() -> pushbutton_statem. % The registered server name
+callback_mode() -> state_functions.
 
 %% API.  This example uses a registered name name()
 %% and does not link to the caller.
@@ -242,12 +243,12 @@ stop() ->
 terminate(_Reason, _State, _Data) ->
     void.
 code_change(_Vsn, State, Data, _Extra) ->
-    {ok,State,Data}.
+    {callback_mode(),State,Data}.
 init([]) ->
     %% Set the callback mode and initial state + data.
     %% Data is used only as a counter.
     State = off, Data = 0,
-    {state_functions,State,Data}.
+    {callback_mode(),State,Data}.
 
 
 %%% State functions
@@ -297,9 +298,7 @@ ok
 
     <p>
       And just to compare styles here is the same example using
-      <seealso marker="#type-callback_mode">
-	<c>callback_mode</c>
-      </seealso>
+      <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
       <c>state_functions</c>, or rather here is code to replace
       from the <c>init/1</c> function of the <c>pushbutton.erl</c>
       example file above:
@@ -453,10 +452,8 @@ handle_event(_, _, State, Data) ->
       <name name="state_name" />
       <desc>
 	<p>
-	  If
-	  <seealso marker="#type-callback_mode">
-	    callback_mode
-	  </seealso>
+	  If the
+	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
 	  is <c>state_functions</c>,
 	  the state has to be of this type.
 	</p>
@@ -499,7 +496,7 @@ handle_event(_, _, State, Data) ->
       <name name="callback_mode" />
       <desc>
 	<p>
-	  The <c>callback_mode</c> is selected when starting the
+	  The <em>callback mode</em> is selected when starting the
 	  <c>gen_statem</c> using the return value from
 	  <seealso marker="#Module:init/1">Module:init/1</seealso>
 	  or when calling
@@ -1277,7 +1274,7 @@ handle_event(_, _, State, Data) ->
           return <c>{CallbackMode,State,Data}</c> or
 	  <c>{CallbackMode,State,Data,Actions}</c>.
 	  <c>CallbackMode</c> selects the
-	  <seealso marker="#type-callback_mode">callback_mode()</seealso>.
+	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>.
 	  of the <c>gen_statem</c>.
 	  <c>State</c> is the initial
 	  <seealso marker="#type-state">state()</seealso>
@@ -1344,8 +1341,8 @@ handle_event(_, _, State, Data) ->
 	  Whenever a <c>gen_statem</c> receives an event from
           <seealso marker="#call/2">call/2</seealso>,
           <seealso marker="#cast/2">cast/2</seealso> or
-	  as a normal process message one of these functions is called.
-	  If <seealso marker="#type-callback_mode">callback_mode</seealso>
+	  as a normal process message one of these functions is called.  If
+	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
 	  is <c>state_functions</c> then <c>Module:StateName/3</c> is called,
 	  and if it is <c>handle_event_function</c>
 	  then <c>Module:handle_event/4</c> is called.
@@ -1468,7 +1465,11 @@ handle_event(_, _, State, Data) ->
         <v>&nbsp;&nbsp;Vsn = term()</v>
         <v>OldState = NewState = term()</v>
         <v>Extra = term()</v>
-	<v>Result = {ok,NewState,NewData} | Reason</v>
+	<v>Result = {NewCallbackMode,NewState,NewData} | Reason</v>
+	<v>
+	  NewCallbackMode =
+	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	</v>
 	<v>
 	  OldState = NewState =
 	  <seealso marker="#type-state">state()</seealso>
@@ -1484,8 +1485,9 @@ handle_event(_, _, State, Data) ->
 	  This function is called by a <c>gen_statem</c> when it should
           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 given in
-          the <c>appup</c> file. See
+          where <c>Change={advanced,Extra}</c> is given in the
+	  <seealso marker="sasl:appup"><c>appup</c></seealso>
+	  file. See
           <seealso marker="doc/design_principles:release_handling#instr">
 	    OTP Design Principles
 	  </seealso>
@@ -1499,6 +1501,21 @@ handle_event(_, _, State, Data) ->
           <c>Module</c>. If no such attribute is defined, the version
           is the checksum of the BEAM file.
 	</p>
+	<note>
+	  <p>
+	    If you would dare to change
+	    <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
+	    during release upgrade/downgrade, the upgrade is no problem
+	    since the new code surely knows what <em>callback mode</em>
+	    it needs, but for a downgrade this function will have to
+	    know from the <c>Extra</c> argument that comes from the
+	    <seealso marker="sasl:appup"><c>appup</c></seealso>
+	    file what <em>callback mode</em> the old code did use.
+	    It may also be possible to figure this out
+	    from the <c>{down,Vsn}</c> argument since <c>Vsn</c>
+	    in effect defines the old callback module version.
+	  </p>
+	</note>
         <p>
 	  <c>OldState</c> and <c>OldData</c> is the internal state
 	  of the <c>gen_statem</c>.
@@ -1510,7 +1527,7 @@ handle_event(_, _, State, Data) ->
         <p>
 	  If successful, the function shall return the updated
           internal state in an
-	  <c>{ok,NewState,NewData}</c> tuple.
+	  <c>{NewCallbackMode,NewState,NewData}</c> tuple.
 	</p>
 	<p>
 	  If the function returns <c>Reason</c>, the ongoing
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index b3a149a569..c85c521d8e 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -219,7 +219,9 @@
 	    OldState :: state(),
 	    OldData :: data(),
 	    Extra :: term()) ->
-    {ok, NewState :: state(), NewData :: data()}.
+    {NewCallbackMode :: callback_mode(),
+     NewState :: state(),
+     NewData :: data()}.
 
 %% Format the callback module state in some sensible that is
 %% often condensed way.  For StatusOption =:= 'normal' the perferred
@@ -491,17 +493,10 @@ enter_loop(Module, Opts, CallbackMode, State, Data, Server_or_Actions) ->
 	Actions :: [action()] | action()) ->
 			no_return().
 enter_loop(Module, Opts, CallbackMode, State, Data, Server, Actions) ->
-    case is_atom(Module) andalso callback_mode(CallbackMode) of
-	true ->
-	    Parent = gen:get_parent(),
-	    enter(
-	      Module, Opts, CallbackMode, State, Data, Server,
-	      Actions, Parent);
-	false ->
-	    error(
-	      badarg,
-	      [Module,Opts,CallbackMode,State,Data,Server,Actions])
-    end.
+    is_atom(Module) orelse error({atom,Module}),
+    callback_mode(CallbackMode) orelse error({callback_mode,CallbackMode}),
+    Parent = gen:get_parent(),
+    enter(Module, Opts, CallbackMode, State, Data, Server, Actions, Parent).
 
 %%---------------------------------------------------------------------------
 %% API helpers
@@ -580,15 +575,13 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
     case Result of
 	{CallbackMode,State,Data} ->
 	    case callback_mode(CallbackMode) of
-		true
-		  when CallbackMode =:= state_functions, is_atom(State);
-		       CallbackMode =/= state_functions ->
+		true ->
 		    proc_lib:init_ack(Starter, {ok,self()}),
 		    enter(
 		      Module, Opts, CallbackMode, State, Data,
 		      ServerRef, [], Parent);
 		false ->
-		    Error = {bad_return_value,Result},
+		    Error = {callback_mode,CallbackMode},
 		    proc_lib:init_ack(Starter, {error,Error}),
 		    exit(Error)
 	    end;
@@ -600,7 +593,7 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) ->
 		      Module, Opts, CallbackMode, State, Data,
 		      ServerRef, Actions, Parent);
 		false ->
-		    Error = {bad_return_value,Result},
+		    Error = {callback_mode,CallbackMode},
 		    proc_lib:init_ack(Starter, {error,Error}),
 		    exit(Error)
 	    end;
@@ -638,11 +631,12 @@ system_code_change(
 	    Result -> Result
 	end
     of
-	{ok,NewState,NewData} ->
-	    {ok,
-	     S#{
-	       state := NewState,
-	       data := NewData}};
+	{NewCallbackMode,NewState,NewData} ->
+	    callback_mode(NewCallbackMode) orelse
+		error({callback_mode,NewCallbackMode}),
+	    {ok,S#{state := NewState, data := NewData}};
+	{ok,_} = Error ->
+	    error({case_clause,Error});
 	Error ->
 	    Error
     end.
@@ -825,6 +819,18 @@ loop_events(
 	Result ->
 	    loop_event_result(
 	      Parent, Debug, S, Events, Event, Result);
+	error:badarg when CallbackMode =:= state_functions ->
+	    case erlang:get_stacktrace() of
+		[{erlang,apply,[Module,State,_],_}|Stacktrace] ->
+		    Args = [Type,Content,Data],
+		    terminate(
+		      error,
+		      {undef_state_function,{Module,State,Args}},
+		      Stacktrace,
+		      Debug, S, Q);
+		Stacktrace ->
+		    terminate(error, badarg, Stacktrace, Debug, S, Q)
+	    end;
 	error:undef ->
 	    %% Process an undef to check for the simple mistake
 	    %% of calling a nonexistent state function
@@ -861,7 +867,7 @@ loop_events(
 %% Interpret all callback return variants
 loop_event_result(
   Parent, Debug,
-  #{callback_mode := CallbackMode, state := State, data := Data} = S,
+  #{state := State, data := Data} = S,
   Events, Event, Result) ->
     case Result of
 	stop ->
@@ -887,15 +893,11 @@ loop_event_result(
 		  exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
 	    %% Since we got back here Replies was bad
 	    terminate(Class, NewReason, Stacktrace, NewDebug, NewS, Q);
-	{next_state,NextState,NewData}
-	  when CallbackMode =:= state_functions, is_atom(NextState);
-	       CallbackMode =/= state_functions ->
+	{next_state,NextState,NewData} ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NextState, NewData, []);
-	{next_state,NextState,NewData,Actions}
-	  when CallbackMode =:= state_functions, is_atom(NextState);
-	       CallbackMode =/= state_functions ->
+	{next_state,NextState,NewData,Actions} ->
 	    loop_event_actions(
 	      Parent, Debug, S, Events, Event,
 	      State, NextState, NewData, Actions);
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index 27fb7d9650..3deb5fd986 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -637,9 +637,9 @@ code_change(Config) ->
     {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []),
     {idle,data} = sys:get_state(Pid),
     sys:suspend(Pid),
-    sys:change_code(Pid, ?MODULE, old_vsn, extra),
+    sys:change_code(Pid, ?MODULE, old_vsn, state_functions),
     sys:resume(Pid),
-    {idle,{old_vsn,data,extra}} = sys:get_state(Pid),
+    {idle,{old_vsn,data,state_functions}} = sys:get_state(Pid),
     stop_it(Pid).
 
 call_format_status(Config) ->
@@ -1561,8 +1561,8 @@ wrap_result(Result) ->
 
 
 
-code_change(OldVsn, State, Data, Extra) ->
-    {ok,State,{OldVsn,Data,Extra}}.
+code_change(OldVsn, State, Data, CallbackMode) ->
+    {CallbackMode,State,{OldVsn,Data,CallbackMode}}.
 
 format_status(terminate, [_Pdict,State,Data]) ->
     {formatted,State,Data};
-- 
cgit v1.2.3


From b54d82fea10c24359d2a315668b6176fc47963b7 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 22 Apr 2016 15:18:07 +0200
Subject: Promote gen_statem over gen_fsm

---
 lib/stdlib/doc/src/gen_fsm.xml    |  16 +++-
 lib/stdlib/doc/src/gen_server.xml |   3 +-
 lib/stdlib/doc/src/gen_statem.xml | 187 ++++++++++++++++++++++++--------------
 3 files changed, 137 insertions(+), 69 deletions(-)

(limited to 'lib/stdlib')

diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 4d594b8eb2..835e252704 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2014</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -31,12 +31,23 @@
   <module>gen_fsm</module>
   <modulesummary>Generic Finite State Machine Behaviour</modulesummary>
   <description>
+    <note>
+      <p>
+	There is a new behaviour
+	<seealso marker="gen_statem"><c>gen_statem</c></seealso>
+	that is intended to replace <c>gen_fsm</c> for new code.
+	It has the same features and add some really useful.
+	This module will not be removed for the foreseeable future
+	to keep old state machine implementations running.
+      </p>
+    </note>
     <p>A behaviour module for implementing a finite state machine.
       A generic finite state machine process (gen_fsm) implemented
       using this module will have a standard set of interface functions
       and include functionality for tracing and error reporting. It will
       also fit into an OTP supervision tree. Refer to
-      <seealso marker="doc/design_principles:fsm">OTP Design Principles</seealso> for more information.</p>
+      <seealso marker="doc/design_principles:fsm">OTP Design Principles</seealso> for more information.
+    </p>
     <p>A gen_fsm assumes all specific parts to be located in a callback
       module exporting a pre-defined set of functions. The relationship
       between the behaviour functions and the callback functions can be
@@ -848,6 +859,7 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
     <title>SEE ALSO</title>
     <p><seealso marker="gen_event">gen_event(3)</seealso>,
       <seealso marker="gen_server">gen_server(3)</seealso>,
+      <seealso marker="gen_statem">gen_statem(3)</seealso>,
       <seealso marker="supervisor">supervisor(3)</seealso>,
       <seealso marker="proc_lib">proc_lib(3)</seealso>,
       <seealso marker="sys">sys(3)</seealso></p>
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 6d04771cd4..10dc978afc 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2014</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -715,6 +715,7 @@ gen_server:abcast     -----> Module:handle_cast/2
     <title>SEE ALSO</title>
     <p><seealso marker="gen_event">gen_event(3)</seealso>,
       <seealso marker="gen_fsm">gen_fsm(3)</seealso>,
+      <seealso marker="gen_statem">gen_statem(3)</seealso>,
       <seealso marker="supervisor">supervisor(3)</seealso>,
       <seealso marker="proc_lib">proc_lib(3)</seealso>,
       <seealso marker="sys">sys(3)</seealso></p>
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index adca3673be..91332fbdde 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -34,12 +34,40 @@
     <p>
       A behaviour module for implementing a state machine. Two
       <seealso marker="#type-callback_mode"><em>callback modes</em></seealso>
-      are supported.  One for a finite state
-      machine like <seealso marker="gen_fsm">gen_fsm</seealso>
-      that requires the state to be an atom and use that state as
-      the name of the callback function for a particular state,
+      are supported.  One for finite state machines
+      (<seealso marker="gen_fsm"><c>gen_fsm</c></seealso> like)
+      that requires the state to be an atom and uses that state as
+      the name of the current callback function,
       and one without restriction on the state data type
-      that uses the same callback function for all states.
+      that uses one callback function for all states.
+    </p>
+    <p>
+      This is a new behaviour in OTP-19.0.
+      It has been thoroughly reviewed, is stable enough
+      to be used by at least two heavy OTP applications, and is here to stay.
+      But depending on user feedback, we do not expect
+      but might find it necessary to make minor
+      not backwards compatible changes into OTP-20.0,
+      so its state can be designated as "not quite experimental"...
+    </p>
+    <p>
+      The <c>gen_statem</c> behaviour is intended to replace
+      <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> for new code.
+      It has the same features and add some really useful:
+    </p>
+    <list type="bulleted">
+      <item>State code is gathered</item>
+      <item>The state can be any term</item>
+      <item>Events can be postponed</item>
+      <item>Events can be self generated</item>
+      <item>A reply can be sent from a later state</item>
+      <item>There can be multiple sys traceable replies</item>
+    </list>
+    <p>
+      The callback model(s) for <c>gen_statem</c> differs from
+      the one for <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>,
+      but it is still fairly easy to rewrite
+      from <c>gen_fsm</c> to <c>gen_statem</c>.
     </p>
     <p>
       A generic state machine process (<c>gen_statem</c>) implemented
@@ -148,15 +176,15 @@ erlang:'!'            -----> Module:StateName/3
       to the state function.  That is: as if it is
       the oldest incoming event.  There is a dedicated
       <seealso marker="#type-event_type">
-        <c>event_type()</c> <c>internal</c>
+        <c>event_type()</c>
       </seealso>
-      that can be used for such events making them impossible
+      <c>internal</c> that 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 <seealso marker="gen_fsm">gen_fsm</seealso>
+      resort to in for example <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
       to force processing an inserted event before others.
       A warning, though: if you in <c>gen_statem</c> for example
       postpone an event in one state and then call some other state function of yours,
@@ -172,9 +200,8 @@ erlang:'!'            -----> Module:StateName/3
     </p>
     <p>
       A <c>gen_statem</c> handles system messages as documented in
-      <seealso marker="sys">sys</seealso>.
-      The <seealso marker="sys">sys</seealso> module
-      can be used for debugging a <c>gen_statem</c>.
+      <seealso marker="sys"><c>sys</c></seealso>.
+      The <c>sys</c>module can be used for debugging a <c>gen_statem</c>.
     </p>
     <p>
       Note that a <c>gen_statem</c> does not trap exit signals
@@ -354,7 +381,7 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  Server specification to use when addressing
 	  a <c>gen_statem</c> server.
-	  See <seealso marker="#call/2">call/2</seealso> and
+	  See <seealso marker="#call/2"><c>call/2</c></seealso> and
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
 	  </seealso>
@@ -397,7 +424,7 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  Debug option that can be used when starting
 	  a <c>gen_statem</c> server through for example
-	  <seealso marker="#enter_loop/5">enter_loop/5</seealso>.
+	  <seealso marker="#enter_loop/5"><c>enter_loop/5</c></seealso>.
 	</p>
 	<p>
 	  For every entry in <c><anno>Dbgs</anno></c>
@@ -412,7 +439,7 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  Options that can be used when starting
 	  a <c>gen_statem</c> server through for example
-	  <seealso marker="#start_link/3">start_link/3</seealso>.
+	  <seealso marker="#start_link/3"><c>start_link/3</c></seealso>.
 	</p>
       </desc>
     </datatype>
@@ -421,7 +448,7 @@ handle_event(_, _, State, Data) ->
       <desc>
 	<p>
 	  Return value from the start functions for_example
-	  <seealso marker="#start_link/3">start_link/3</seealso>.
+	  <seealso marker="#start_link/3"><c>start_link/3</c></seealso>.
 	</p>
       </desc>
     </datatype>
@@ -432,10 +459,11 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  Destination to use when replying through for example the
 	  <seealso marker="#type-action">
-	    action() {reply,From,Reply}
+	    <c>action()</c>
 	  </seealso>
+	  <c>{reply,From,Reply}</c>
 	  to a process that has called the <c>gen_statem</c> server using
-	  <seealso marker="#call/2">call/2</seealso>.
+	  <seealso marker="#call/2"><c>call/2</c></seealso>.
 	</p>
       </desc>
     </datatype>
@@ -465,7 +493,7 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  A term in which the state machine implementation
 	  should store any server data it needs.  The difference between
-	  this and the <seealso marker="#type-state">state()</seealso>
+	  this and the <seealso marker="#type-state"><c>state()</c></seealso>
 	  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
@@ -498,9 +526,13 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  The <em>callback mode</em> is selected when starting the
 	  <c>gen_statem</c> using the return value from
-	  <seealso marker="#Module:init/1">Module:init/1</seealso>
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
 	  or when calling
-	  <seealso marker="#enter_loop/5">enter_loop/5-7</seealso>.
+	  <seealso marker="#enter_loop/5"><c>enter_loop/5-7</c></seealso>,
+	  and with the return value from
+	  <seealso marker="#Module:code_change/4">
+	    <c>Module:code_change/4</c>.
+	  </seealso>
 	</p>
 	<taglist>
 	  <tag><c>state_functions</c></tag>
@@ -536,7 +568,7 @@ handle_event(_, _, State, Data) ->
 	<list type="ordered">
 	  <item>
 	    All
-            <seealso marker="#type-action"><c>actions</c></seealso>
+            <seealso marker="#type-action">actions</seealso>
 	    are processed in order of appearance.
 	  </item>
 	  <item>
@@ -554,20 +586,22 @@ handle_event(_, _, State, Data) ->
 	  <item>
 	    All events stored with
 	    <seealso marker="#type-action">
-	      <c>action() next_event</c>
+	      <c>action()</c>
 	    </seealso>
+	    <c>next_event</c>
 	    are inserted in the queue to be processed before
 	    all other events.
 	  </item>
 	  <item>
 	    If an
             <seealso marker="#type-event_timeout">
-	      <em><c>event_timeout()</c></em>
+	      <c>event_timeout()</c>
 	    </seealso>
 	    is set through
             <seealso marker="#type-action">
-	      <c>action() timeout</c>
+	      <c>action()</c>
 	    </seealso>
+	    <c>timeout</c>
 	    an event timer may be started or a timeout zero event
 	    may be enqueued.
 	  </item>
@@ -622,7 +656,8 @@ handle_event(_, _, State, Data) ->
       <desc>
 	<p>
 	  Generate an event of
-	  <seealso marker="#type-event_type">type <c>timeout</c></seealso>
+	  <seealso marker="#type-event_type"><c>event_type()</c></seealso>
+	  <c>timeout</c>
 	  after this time (in milliseconds) unless some other
 	  event arrives in which case this timeout is cancelled.
 	  Note that a retried or inserted event
@@ -652,9 +687,9 @@ handle_event(_, _, State, Data) ->
 	  These state transition actions may be invoked by
 	  returning them from the
 	  <seealso marker="#state_function">state function</seealso>,
-	  from <seealso marker="#Module:init/1">Module:init/1</seealso>
+	  from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
 	  or by giving them to
-	  <seealso marker="#enter_loop/6">enter_loop/6,7</seealso>.
+	  <seealso marker="#enter_loop/6"><c>enter_loop/6,7</c></seealso>.
 	</p>
 	<p>
 	  Actions are executed in the containing list order.
@@ -677,20 +712,26 @@ handle_event(_, _, State, Data) ->
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() postpone()</c>
+	      <c>transition_option()</c>
+	    </seealso>
+	    <seealso marker="#type-postpone">
+	      <c>postpone()</c>
 	    </seealso>
 	    for this state transition.
 	    This action is ignored when returned from
-	    <seealso marker="#Module:init/1">Module:init/1</seealso>
+	    <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
 	    or given to
-	    <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>
+	    <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>
 	    since there is no event to postpone in those cases.
 	  </item>
 	  <tag><c>hibernate</c></tag>
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() hibernate()</c>
+	      <c>transition_option()</c>
+	    </seealso>
+	    <seealso marker="#type-hibernate">
+	      <c>hibernate()</c>
 	    </seealso>
 	    for this state transition.
 	  </item>
@@ -703,13 +744,17 @@ handle_event(_, _, State, Data) ->
 	    return value <c>{next_state,NextState,NewData,Timeout}</c>
 	    allowed like for
 	    <seealso marker="gen_fsm#Module:StateName/2">
-	      gen_fsm Module:StateName/2</seealso>.
+	      <c>gen_fsm Module:StateName/2</c>.
+	    </seealso>
 	  </item>
 	  <tag><c>timeout</c></tag>
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() event_timeout()</c>
+	      <c>transition_option()</c>
+	    </seealso>
+	    <seealso marker="#type-event_timeout">
+	      <c>event_timeout()</c>
 	    </seealso>
 	    to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>.
 	  </item>
@@ -906,7 +951,7 @@ handle_event(_, _, State, Data) ->
 	  If the option <c>{spawn_opt,SpawnOpts}</c> is present in
 	  <c><anno>Opts</anno></c>, <c>SpawnOpts</c> will be passed
 	  as option list to
-          <seealso marker="erts:erlang#spawn_opt/2">spawn_opt/2</seealso>
+          <seealso marker="erts:erlang#spawn_opt/2"><c>spawn_opt/2</c></seealso>
 	  which is used to spawn the <c>gen_statem</c> process.
 	</p>
         <note>
@@ -967,7 +1012,7 @@ handle_event(_, _, State, Data) ->
 	  to start a child.
 	</p>
         <p>
-	  See <seealso marker="#start_link/3">start_link/3,4</seealso>
+	  See <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>
           for a description of arguments and return values.
 	</p>
       </desc>
@@ -979,7 +1024,9 @@ handle_event(_, _, State, Data) ->
       <desc>
 	<p>
 	  The same as
-	  <seealso marker="#stop/3"><c>stop(<anno>ServerRef</anno>, normal, infinity)</c></seealso>.
+	  <seealso marker="#stop/3">
+	    <c>stop(<anno>ServerRef</anno>, normal, infinity)</c>.
+	  </seealso>
 	</p>
       </desc>
     </func>
@@ -996,7 +1043,7 @@ handle_event(_, _, State, Data) ->
 	  and waits for it to terminate.
 	  The <c>gen_statem</c> will call
           <seealso marker="#Module:terminate/3">
-	    Module:terminate/3
+	    <c>Module:terminate/3</c>
 	  </seealso>
 	  before exiting.
 	</p>
@@ -1005,7 +1052,9 @@ handle_event(_, _, State, Data) ->
 	  with the expected reason. Any other reason than <c>normal</c>,
           <c>shutdown</c>, or <c>{shutdown,Term}</c> will cause an
           error report to be issued through
-          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.
+          <seealso marker="kernel:error_logger#format/2">
+	    <c>error_logger:format/2</c>.
+	  </seealso>
 	  The default <c><anno>Reason</anno></c> is <c>normal</c>.
 	</p>
 	<p>
@@ -1125,7 +1174,7 @@ handle_event(_, _, State, Data) ->
 	<note>
 	  <p>
 	    A reply sent with this function will not be visible
-	    in <seealso marker="sys">sys</seealso> debug output.
+	    in <seealso marker="sys"><c>sys</c></seealso> debug output.
 	  </p>
 	</note>
       </desc>
@@ -1194,7 +1243,9 @@ handle_event(_, _, State, Data) ->
 	  <c><anno>Module</anno></c>, <c><anno>Opts</anno></c> and
 	  <c><anno>Server</anno></c> have the same meanings
 	  as when calling
-          <seealso marker="#start_link/3"><c>gen_statem</c>:start[_link]/3,4</seealso>.
+          <seealso marker="#start_link/3">
+	    <c>gen_statem:start[_link]/3,4</c>.
+	  </seealso>
           However, the
 	  <seealso marker="#type-server_name">
 	    <c>server_name()</c>
@@ -1205,7 +1256,7 @@ handle_event(_, _, State, Data) ->
 	  <c><anno>CallbackMode</anno></c>, <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
-          <seealso marker="#Module:init/1">Module:init/1</seealso>.
+          <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>.
           Also, the callback module <c><anno>Module</anno></c>
 	  does not need to export an <c>init/1</c> function.
 	</p>
@@ -1259,9 +1310,9 @@ handle_event(_, _, State, Data) ->
 	<marker id="Module:init-1" />
         <p>
 	  Whenever a <c>gen_statem</c> is started using
-          <seealso marker="#start_link/3">start_link/3,4</seealso>
+          <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>
 	  or
-          <seealso marker="#start/3">start/3,4</seealso>,
+          <seealso marker="#start/3"><c>start/3,4</c></seealso>,
           this function is called by the new process to initialize
 	  the implementation state and server data.
 	</p>
@@ -1277,9 +1328,9 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>.
 	  of the <c>gen_statem</c>.
 	  <c>State</c> is the initial
-	  <seealso marker="#type-state">state()</seealso>
+	  <seealso marker="#type-state"><c>state()</c></seealso>
 	  and <c>Data</c> the initial server
-	  <seealso marker="#type-data">data()</seealso>.
+	  <seealso marker="#type-data"><c>data()</c></seealso>.
 	</p>
 	<p>
 	  The <seealso marker="#type-action"><c>Actions</c></seealso>
@@ -1291,11 +1342,11 @@ handle_event(_, _, State, Data) ->
 	  If something goes wrong during the initialization
           the function should return <c>{stop,Reason}</c>
 	  or <c>ignore</c>. See
-          <seealso marker="#start_link/3">start_link/3,4</seealso>.
+          <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.
 	</p>
 	<p>
 	  This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
+	  <seealso marker="erts:erlang#throw/1"><c>throw/1</c></seealso>
 	  to return <c>Result</c>.
 	</p>
       </desc>
@@ -1339,8 +1390,8 @@ handle_event(_, _, State, Data) ->
       <desc>
         <p>
 	  Whenever a <c>gen_statem</c> receives an event from
-          <seealso marker="#call/2">call/2</seealso>,
-          <seealso marker="#cast/2">cast/2</seealso> or
+          <seealso marker="#call/2"><c>call/2</c></seealso>,
+          <seealso marker="#cast/2"><c>cast/2</c></seealso> or
 	  as a normal process message one of these functions is called.  If
 	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
 	  is <c>state_functions</c> then <c>Module:StateName/3</c> is called,
@@ -1354,8 +1405,8 @@ handle_event(_, _, State, Data) ->
 	  from this or from any other
 	  <seealso marker="#state_function">state function</seealso>
 	  by returning with <c>{reply,From,Reply}</c> in
-	  <seealso marker="#type-action">Actions</seealso>, in
-	  <seealso marker="#type-reply_action">Replies</seealso>
+	  <seealso marker="#type-action"><c>Actions</c></seealso>, in
+	  <seealso marker="#type-reply_action"><c>Replies</c></seealso>
 	  or by calling
 	  <seealso marker="#reply/2"><c>reply(From, Reply)</c></seealso>.
 	</p>
@@ -1371,13 +1422,13 @@ handle_event(_, _, State, Data) ->
 	  there is no restriction on the next state.
 	</p>
 	<p>
-	  See <seealso marker="#type-action">action()</seealso>
+	  See <seealso marker="#type-action"><c>action()</c></seealso>
 	  for options that can be set and actions that can be done
 	  by <c>gen_statem</c> after returning from this function.
 	</p>
 	<p>
 	  These functions may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>,
+	  <seealso marker="erts:erlang#throw/1"><c>throw/1</c></seealso>,
 	  to return the result.
 	</p>
       </desc>
@@ -1402,7 +1453,7 @@ handle_event(_, _, State, Data) ->
           value is ignored.</p>
         <p>
 	  <c>Reason</c> is a term denoting the stop reason and
-          <seealso marker="#type-state">State</seealso>
+          <seealso marker="#type-state"><c>State</c></seealso>
 	  is the internal state of the <c>gen_statem</c>.
 	</p>
         <p>
@@ -1410,7 +1461,7 @@ handle_event(_, _, State, Data) ->
 	  is terminating.
           If it is because another callback function has returned a
           stop tuple <c>{stop,Reason}</c> in
-	  <seealso marker="#type-action">Actions</seealso>,
+	  <seealso marker="#type-action"><c>Actions</c></seealso>,
 	  <c>Reason</c> will have the value specified in that tuple.
 	  If it is due to a failure, <c>Reason</c> is the error reason.
 	</p>
@@ -1445,11 +1496,13 @@ handle_event(_, _, State, Data) ->
           <c>shutdown</c>, or <c>{shutdown,Term}</c>
 	  the <c>gen_statem</c> is assumed to terminate due to an error
 	  and an error report is issued using
-          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.
+          <seealso marker="kernel:error_logger#format/2">
+	    <c>error_logger:format/2</c>.
+	  </seealso>
 	</p>
 	<p>
 	  This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
+	  <seealso marker="erts:erlang#throw/1"><c>throw/1</c></seealso>
 	  to return <c>Ignored</c>, which is ignored anyway.
 	</p>
       </desc>
@@ -1504,7 +1557,9 @@ handle_event(_, _, State, Data) ->
 	<note>
 	  <p>
 	    If you would dare to change
-	    <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>
+	    <seealso marker="#type-callback_mode">
+	      <em>callback mode</em>
+	    </seealso>
 	    during release upgrade/downgrade, the upgrade is no problem
 	    since the new code surely knows what <em>callback mode</em>
 	    it needs, but for a downgrade this function will have to
@@ -1534,7 +1589,7 @@ handle_event(_, _, State, Data) ->
 	  upgrade will fail and roll back to the old release.</p>
 	<p>
 	  This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
+	  <seealso marker="erts:erlang#throw/1"><c>throw/1</c></seealso>
 	  to return <c>Result</c> or <c>Reason</c>.
 	</p>
       </desc>
@@ -1640,7 +1695,7 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<p>
 	  This function may use
-	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
+	  <seealso marker="erts:erlang#throw/1"><c>throw/1</c></seealso>
 	  to return <c>Status</c>.
 	</p>
       </desc>
@@ -1650,11 +1705,11 @@ handle_event(_, _, State, Data) ->
 
   <section>
     <title>SEE ALSO</title>
-    <p><seealso marker="gen_event">gen_event</seealso>,
-      <seealso marker="gen_fsm">gen_fsm</seealso>,
-      <seealso marker="gen_server">gen_server</seealso>,
-      <seealso marker="supervisor">supervisor</seealso>,
-      <seealso marker="proc_lib">proc_lib</seealso>,
-      <seealso marker="sys">sys</seealso></p>
+    <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>,
+      <seealso marker="gen_fsm"><c>gen_fsm(3)</c></seealso>,
+      <seealso marker="gen_server"><c>gen_server(3)</c></seealso>,
+      <seealso marker="supervisor"><c>supervisor(3)</c></seealso>,
+      <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>,
+      <seealso marker="sys"><c>sys(3)</c></seealso></p>
   </section>
 </erlref>
-- 
cgit v1.2.3