Merge branch 'raimo/kernel/gen_statem-progress/OTP-14114' into maint

* raimo/kernel/gen_statem-progress/OTP-14114:
  Make code_change/4 optional
  Implement fallback for terminate/3
  Clarify code_change and callback mode change
  Stop pampering with stacktraces
  Clean up timer handling
  Remove event timer optimization
  Clean up timer handling
  Reduce number of loop variables hence code mass
  Optimize by using async cancel_timer
  Bugfix: callback mode not cached after code change
  Implement repeat_state and repeat_state_and_data
  Correct type checking function for action {next_event,,}
  Change arity of type to init_result/1

1 files changed, 121 insertions, 46 deletions

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index fd498ee82e..5eb13db1aa 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2016</year>
+      <year>2016-2017</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -587,8 +587,8 @@ handle_event(_, _, State, Data) ->
       <name name="state_enter"/>
       <desc>
 	<p>
-	  If the state machine should use <em>state enter calls</em>
-	  is selected when starting the  <c>gen_statem</c>
+	  Whether the state machine should use <em>state enter calls</em>
+	  or not is selected when starting the  <c>gen_statem</c>
 	  and after code change using the return value from
 	  <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>.
 	</p>
@@ -606,7 +606,16 @@ handle_event(_, _, State, Data) ->
 	  See
 	  <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>
 	  and
-	      <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>.
+	  <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>.
+	  Such a call can be repeated by returning a
+	  <seealso marker="#type-state_callback_result">
+	    <c>repeat_state</c>
+	  </seealso>
+	  or
+	  <seealso marker="#type-state_callback_result">
+	    <c>repeat_state_and_data</c>
+	  </seealso>
+	  tuple from the state callback.
 	</p>
 	<p>
 	  If 
@@ -625,7 +634,8 @@ handle_event(_, _, State, Data) ->
 	  right before entering the initial state even though this
 	  formally is not a state change.
 	  In this case <c>OldState</c> will be the same as <c>State</c>,
-	  which can not happen for a subsequent state change.
+	  which can not happen for a subsequent state change,
+	  but will happen when repeating the state enter call.
 	</p>
       </desc>
     </datatype>
@@ -640,7 +650,15 @@ handle_event(_, _, State, Data) ->
 	<list type="ordered">
 	  <item>
             <p>
-	      If the state changes or is the initial state, and
+	      If the state changes, is the initial state,
+	      <seealso marker="#type-state_callback_result">
+		<c>repeat_state</c>
+	      </seealso>
+	      or
+	      <seealso marker="#type-state_callback_result">
+		<c>repeat_state_and_data</c>
+	      </seealso>
+	      is used, and also
 	      <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>
 	      are used, the <c>gen_statem</c> calls
 	      the new state callback with arguments
@@ -983,6 +1001,33 @@ handle_event(_, _, State, Data) ->
       </desc>
     </datatype>
     <datatype>
+      <name name="init_result"/>
+      <desc>
+	<p>
+	  For a succesful initialization,
+	  <c><anno>State</anno></c> is the initial
+	  <seealso marker="#type-state"><c>state()</c></seealso>
+	  and <c><anno>Data</anno></c> the initial server
+	  <seealso marker="#type-data"><c>data()</c></seealso>
+	  of the <c>gen_statem</c>.
+	</p>
+	<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 callback">state callback</seealso>,
+	  except that the action <c>postpone</c> is forced to
+	  <c>false</c> since there is no event to postpone.
+	</p>
+	<p>
+	  For an unsuccesful initialization,
+          <c>{stop,<anno>Reason</anno>}</c>
+	  or <c>ignore</c> should be used; see
+          <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="state_enter_result"/>
       <desc>
 	<p>
@@ -1068,6 +1113,37 @@ handle_event(_, _, State, Data) ->
 	      <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>.
 	    </p>
 	  </item>
+	  <tag><c>repeat_state</c></tag>
+	  <item>
+	    <p>
+	      The <c>gen_statem</c> keeps the current state, or
+	      does a state transition to the current state if you like,
+	      sets <c><anno>NewData</anno></c>,
+	      and executes all <c><anno>Actions</anno></c>.
+	      If the <c>gen_statem</c> runs with
+	      <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>,
+	      the state enter call is repeated, see type
+	      <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>,
+	      otherwise <c>repeat_state</c> is the same as
+	      <c>keep_state</c>.
+	    </p>
+	  </item>
+	  <tag><c>repeat_state_and_data</c></tag>
+	  <item>
+	    <p>
+	      The <c>gen_statem</c> keeps the current state and data, or
+	      does a state transition to the current state if you like,
+	      and executes all <c><anno>Actions</anno></c>.
+	      This is the same as
+	      <c>{repeat_state,CurrentData,<anno>Actions</anno>}</c>.
+	      If the <c>gen_statem</c> runs with
+	      <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>,
+	      the state enter call is repeated, see type
+	      <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>,
+	      otherwise <c>repeat_state_and_data</c> is the same as
+	      <c>keep_state_and_data</c>.
+	    </p>
+	  </item>
 	  <tag><c>stop</c></tag>
 	  <item>
 	    <p>
@@ -1609,29 +1685,33 @@ handle_event(_, _, State, Data) ->
 	  It is recommended to use an atom as <c>Reason</c> since
 	  it will be wrapped in an <c>{error,Reason}</c> tuple.
 	</p>
+	<p>
+	  Also note when upgrading a <c>gen_statem</c>,
+	  this function and hence
+	  the <c>Change={advanced,Extra}</c> parameter in the
+	  <seealso marker="sasl:appup"><c>appup</c></seealso> file
+	  is not only needed to update the internal state
+	  or to act on the <c>Extra</c> argument.
+	  It is also needed if an upgrade or downgrade should change 
+	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>,
+	  or else the callback mode after the code change
+	  will not be honoured,
+	  most probably causing a server crash.
+	</p>
       </desc>
     </func>
 
     <func>
-      <name>Module:init(Args) -> Result</name>
+      <name>Module:init(Args) -> Result(StateType)</name>
       <fsummary>
 	Optional function for initializing process and internal state.
       </fsummary>
       <type>
         <v>Args = term()</v>
-        <v>Result = {ok,State,Data}</v>
-	<v>&nbsp;| {ok,State,Data,Actions}</v>
-        <v>&nbsp;| {stop,Reason} | ignore</v>
-	<v>State = <seealso marker="#type-state">state()</seealso></v>
-	<v>
-	  Data = <seealso marker="#type-data">data()</seealso>
-	</v>
 	<v>
-	  Actions =
-	  [<seealso marker="#type-action">action()</seealso>] |
-	  <seealso marker="#type-action">action()</seealso>
+	  Result(StateType) =
+	  <seealso marker="#type-init_result">init_result(StateType)</seealso>
 	</v>
-	<v>Reason = term()</v>
       </type>
       <desc>
 	<marker id="Module:init-1"/>
@@ -1644,30 +1724,9 @@ handle_event(_, _, State, Data) ->
 	  the implementation state and server data.
 	</p>
 	<p>
-	  <c>Args</c> is the <c>Args</c> argument provided to the start
+	  <c>Args</c> is the <c>Args</c> argument provided to that start
 	  function.
 	</p>
-	<p>
-	  If the initialization is successful, the function is to
-	  return <c>{ok,State,Data}</c> or
-	  <c>{ok,State,Data,Actions}</c>.
-	  <c>State</c> is the initial
-	  <seealso marker="#type-state"><c>state()</c></seealso>
-	  and <c>Data</c> the initial server
-	  <seealso marker="#type-data"><c>data()</c></seealso>.
-	</p>
-	<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 callback">state callback</seealso>.
-	</p>
-	<p>
-	  If the initialization fails,
-          the function is to return <c>{stop,Reason}</c>
-	  or <c>ignore</c>; see
-          <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.
-	</p>
         <note>
 	  <p>
 	    This callback is optional, so a callback module does not need
@@ -1873,22 +1932,33 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#type-enter_action">actions</seealso>
 	  that may be returned:
 	  <seealso marker="#type-postpone"><c>postpone()</c></seealso>
-	  and 
+	  is not allowed since a <em>state enter call</em> is not
+	  an event so there is no event to postpone, and 
 	  <seealso marker="#type-action"><c>{next_event,_,_}</c></seealso>
-	  are not allowed.
+	  is not allowed since using <em>state enter calls</em>
+	  should not affect how events are consumed and produced.
 	  You may also not change states from this call.
 	  Should you return <c>{next_state,NextState, ...}</c>
 	  with <c>NextState =/= State</c> the <c>gen_statem</c> crashes.
-	  You are advised to use <c>{keep_state,...}</c> or
-	  <c>keep_state_and_data</c>.
+	  It is possible to use <c>{repeat_state, ...}</c>,
+	  <c>{repeat_state_and_data,_}</c> or
+	  <c>repeat_state_and_data</c> but all of them makes little
+	  sense since you immediately will be called again with a new
+	  <em>state enter call</em> making this just a weird way
+	  of looping, and there are better ways to loop in Erlang.
+	  You are advised to use <c>{keep_state,...}</c>,
+	  <c>{keep_state_and_data,_}</c> or
+	  <c>keep_state_and_data</c> since you can not change states
+	  from a <em>state enter call</em> anyway.
 	</p>
 	<p>
 	  Note the fact that you can use
 	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
 	  to return the result, which can be useful.
 	  For example to bail out with <c>throw(keep_state_and_data)</c>
-	  from deep within complex code that is in no position to
-	  return <c>{next_state,State,Data}</c>.
+	  from deep within complex code that can not
+	  return <c>{next_state,State,Data}</c> because
+	  <c>State</c> or <c>Data</c> is no longer in scope.
 	</p>
       </desc>
     </func>
@@ -1903,6 +1973,11 @@ handle_event(_, _, State, Data) ->
 	<v>Ignored = term()</v>
       </type>
       <desc>
+        <note>
+          <p>This callback is optional, so callback modules need not
+          export it. The <c>gen_statem</c> module provides a default
+          implementation without cleanup.</p>
+        </note>
 	<p>
 	  This function is called by a <c>gen_statem</c>
 	  when it is about to terminate. It is to be the opposite of