From 6ee0aefd8a0ea9c165211c42d5244182b5aa9210 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 13 Sep 2016 14:00:04 +0200
Subject: Implement state entry events

---
 lib/stdlib/doc/src/gen_statem.xml | 82 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 76 insertions(+), 6 deletions(-)

(limited to 'lib/stdlib/doc/src')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 17f1526a21..a4c5438a08 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -70,6 +70,7 @@
       <item>The state can be any term.</item>
       <item>Events can be postponed.</item>
       <item>Events can be self-generated.</item>
+      <item>Automatic state entry events can be generated.</item>
       <item>A reply can be sent from a later state.</item>
       <item>There can be multiple <c>sys</c> traceable replies.</item>
     </list>
@@ -193,6 +194,12 @@ erlang:'!'            -----> Module:StateName/3
       <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
       to force processing an inserted event before others.
     </p>
+    <p>
+      The <c>gen_statem</c> engine can automatically insert
+      a special event whenever a new state is entered; see 
+      <seealso marker="#type-state_entry_mode"><c>state_entry_mode()</c></seealso>.
+      This makes it easy to handle code common to all state entries.
+    </p>
     <note>
       <p>If you in <c>gen_statem</c>, for example, postpone
         an event in one state and then call another state function
@@ -515,7 +522,7 @@ handle_event(_, _, State, Data) ->
 	  Type <c>info</c> originates from regular process messages sent
 	  to the <c>gen_statem</c>. Also, the state machine
 	  implementation can generate events of types
-	  <c>timeout</c> and <c>internal</c> to itself.
+	  <c>timeout</c>, <c>enter</c> and <c>internal</c> to itself.
 	</p>
       </desc>
     </datatype>
@@ -550,6 +557,34 @@ handle_event(_, _, State, Data) ->
 	</taglist>
       </desc>
     </datatype>
+    <datatype>
+      <name name="state_entry_mode"/>
+      <desc>
+	<p>
+	  The <em>state entry mode</em> 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>
+	<p>
+	  If 
+	  <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>
+	  returns a list containing <c>state_entry_events</c>,
+	  the <c>gen_statem</c> engine will, at every state change,
+	  insert an event of type
+	  <seealso marker="#type-event_type">enter</seealso>
+	  with content <c>OldState</c>.  This event will be inserted
+	  before all other events such as those generated by
+	  <seealso marker="#type-action"><c>action()</c></seealso>
+	  <c>next_event</c>.
+	</p>
+	<p>
+	  If 
+	  <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>
+	  does not return such a list, no state entry events are inserted.
+	</p>
+      </desc>
+    </datatype>
     <datatype>
       <name name="transition_option"/>
       <desc>
@@ -590,6 +625,16 @@ handle_event(_, _, State, Data) ->
 	      all other events.
             </p>
 	  </item>
+	  <item>
+            <p>
+	      If the state changes or is the initial state, and the 
+	      <seealso marker="#type-state_entry_mode"><em>state entry mode</em></seealso>
+	      is <c>state_entry_events</c>, an event of type
+	      <seealso marker="#type-event_type">enter</seealso>
+	      with content <c>OldState</c> is inserted
+	      to be processed before all other events including those above.
+            </p>
+	  </item>
 	  <item>
 	    <p>
 	      If an
@@ -1288,7 +1333,9 @@ handle_event(_, _, State, Data) ->
       <type>
 	<v>
 	  CallbackMode =
-	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	  <seealso marker="#type-callback_mode">callback_mode()</seealso> |
+	  [ <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	  | state_entry_events ]
 	</v>
       </type>
       <desc>
@@ -1313,12 +1360,35 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
 	  returns.
 	</p>
+	<p>
+	  The <c>CallbackMode</c> is either just
+	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	  or a list containing
+	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	  and possibly the atom
+	  <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso>.
+	</p>
+	<p>
+	  If the atom <c>state_entry_events</c> is present in the list,
+	  the <c>gen_statem</c> engine will, at every state change,
+	  insert an event of type
+	  <seealso marker="#type-event_type">enter</seealso>
+	  with content <c>OldState</c>.  This event will be inserted
+	  before all other events such as those generated by
+	  <seealso marker="#type-action"><c>action()</c></seealso>
+	  <c>next_event</c>.
+	</p>
+	<p>
+	  No state entry event will be inserted after a
+	  <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
+	  since transforming the state to a newer version is regarded
+	  as staying in the same state even if the newer version state
+	  should have a different name.
+	</p>
 	<note>
 	  <p>
-	    If this function's body does not consist of solely one of two
-	    possible
-	    <seealso marker="#type-callback_mode">atoms</seealso>
-	    the callback module is doing something strange.
+	    If this function's body does not return an inline constant
+	    value the callback module is doing something strange.
 	  </p>
 	</note>
       </desc>
-- 
cgit v1.2.3