Merge branch 'raimo/new-gen-state-machine/OTP-13065'

* raimo/new-gen-state-machine/OTP-13065: (52 commits)
  Add section on state filtering
  Promote gen_statem over gen_fsm
  Modify code_change/4 to return CallbackMode
  Use ?NAME macro in examples
  Introduce Fred Herbert suggested additions
  Introduce corrections from Fred Hebert and Ingela
  Use .png pictures instead of .gif
  Write Design Principles chapter
  Fix missing short forms for event timeout
  Do more intricate Fred Hebert doc changes
  Change Caller -> From as suggested by Fred Hebert
  Do documentation improvements from Fred Hebert
  Fix broken documenation reference
  Rename state_timeout -> event_timeout
  Fix most of the system docs and emacs mode
  Change code_change/4 to {ok,State,Data}
  Fixup sharpened test suite
  Sharpen test suite
  Remove the remove_event action and all alike
  Relax caller() type check and cleanup
  ...

Conflicts:
	lib/stdlib/src/gen.erl
	lib/stdlib/src/gen_event.erl
	lib/stdlib/src/gen_fsm.erl
	lib/stdlib/src/gen_server.erl
	lib/stdlib/test/error_logger_forwarder.erl

1 files changed, 118 insertions, 0 deletions

diff --git a/lib/tools/emacs/erlang-skels.el b/lib/tools/emacs/erlang-skels.el
index 3bb1dda6db..ce26c83295 100644
--- a/lib/tools/emacs/erlang-skels.el
+++ b/lib/tools/emacs/erlang-skels.el
@@ -56,6 +56,8 @@
      erlang-skel-gen-event erlang-skel-header)
     ("gen_fsm" "gen-fsm"
      erlang-skel-gen-fsm erlang-skel-header)
+    ("gen_statem" "gen-statem"
+     erlang-skel-gen-statem erlang-skel-header)
     ("wx_object" "wx-object"
      erlang-skel-wx-object erlang-skel-header)
     ("Library module" "gen-lib"
@@ -858,6 +860,122 @@ Please see the function `tempo-define-template'.")
   "*The template of a gen_fsm.
 Please see the function `tempo-define-template'.")
 
+(defvar erlang-skel-gen-statem
+  '((erlang-skel-include erlang-skel-large-header)
+    "-behaviour(gen_statem)." n n
+
+    "%% API" n
+    "-export([start_link/0])." n
+    n
+    "%% gen_statem callbacks" n
+    "-export([init/1, terminate/3, code_change/4])." n
+    "-export([state_name/3])." n
+    "-export([handle_event/4])." n
+    n
+    "-define(SERVER, ?MODULE)." n
+    n
+    "-record(data, {})." n
+    n
+    (erlang-skel-double-separator-start 3)
+    "%%% API" n
+    (erlang-skel-double-separator-end 3) n
+    (erlang-skel-separator-start 2)
+    "%% @doc" n
+    "%% Creates a gen_statem process which calls Module:init/1 to" n
+    "%% initialize. To ensure a synchronized start-up procedure, this" n
+    "%% function does not return until Module:init/1 has returned." n
+    "%%" n
+    (erlang-skel-separator-end 2)
+    "-spec start_link() ->" n>
+    "{ok, Pid :: pid()} |" n>
+    "ignore |" n>
+    "{error, Error :: term()}." n
+    "start_link() ->" n>
+    "gen_statem:start_link({local, ?SERVER}, ?MODULE, [], [])." n
+    n
+    (erlang-skel-double-separator-start 3)
+    "%%% gen_statem callbacks" n
+    (erlang-skel-double-separator-end 3) n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% Whenever a gen_statem is started using gen_statem:start/[3,4] or" n
+    "%% gen_statem:start_link/[3,4], this function is called by the new" n
+    "%% process to initialize." n
+    (erlang-skel-separator-end 2)
+    "-spec init(Args :: term()) -> " n>
+    "{gen_statem:callback_mode()," n>
+    "State :: term(), Data :: term()} |" n>
+    "{gen_statem:callback_mode()," n>
+    "State :: term(), Data :: term()," n>
+    "[gen_statem:action()] | gen_statem:action()} |" n>
+    "ignore |" n>
+    "{stop, Reason :: term()}." n
+    "init([]) ->" n>
+    "{state_functions, state_name, #data{}}." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% If the gen_statem runs with CallbackMode =:= state_functions" n
+    "%% there should be one instance of this function for each possible" n
+    "%% state name. Whenever a gen_statem receives an event," n
+    "%% the instance of this function with the same name" n
+    "%% as the current state name StateName is called to" n
+    "%% handle the event." n
+    (erlang-skel-separator-end 2)
+    "-spec state_name(" n>
+    "gen_statem:event_type(), Msg :: term()," n>
+    "Data :: term()) ->" n>
+    "gen_statem:state_function_result(). " n
+    "state_name({call,Caller}, _Msg, Data) ->" n>
+    "{next_state, state_name, Data, [{reply,Caller,ok}]}." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% If the gen_statem runs with CallbackMode =:= handle_event_function" n
+    "%% this function is called for every event a gen_statem receives." n
+    (erlang-skel-separator-end 2)
+    "-spec handle_event(" n>
+    "gen_statem:event_type(), Msg :: term()," n>
+    "State :: term(), Data :: term()) ->" n>
+    "gen_statem:handle_event_result(). " n
+    "handle_event({call,From}, _Msg, State, Data) ->" n>
+    "{next_state, State, Data, [{reply,From,ok}]}." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% This function is called by a gen_statem when it is about to" n
+    "%% terminate. It should be the opposite of Module:init/1 and do any" n
+    "%% necessary cleaning up. When it returns, the gen_statem terminates with" n
+    "%% Reason. The return value is ignored." n
+    (erlang-skel-separator-end 2)
+    "-spec terminate(Reason :: term(), State :: term(), Data :: term()) ->" n>
+    "any()." n
+    "terminate(_Reason, _State, _Data) ->" n>
+    "void." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% Convert process state when code is changed" n
+    (erlang-skel-separator-end 2)
+    "-spec code_change(" n>
+    "OldVsn :: term() | {down,term()}," n>
+    "State :: term(), Data :: term(), Extra :: term()) ->" n>
+    "{ok, NewState :: term(), NewData :: term()}." n
+    "code_change(_OldVsn, State, Data, _Extra) ->" n>
+    "{ok, State, Data}." n
+    n
+    (erlang-skel-double-separator-start 3)
+    "%%% Internal functions" n
+    (erlang-skel-double-separator-end 3)
+    )
+  "*The template of a gen_statem.
+Please see the function `tempo-define-template'.")
+
 (defvar erlang-skel-wx-object
   '((erlang-skel-include erlang-skel-large-header)
     "-behaviour(wx_object)." n n