Merge branch 'maint'

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