aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/gen_statem.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/gen_statem.xml')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml82
1 files changed, 76 insertions, 6 deletions
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>
@@ -551,6 +558,34 @@ handle_event(_, _, State, Data) ->
</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>
<p>
@@ -591,6 +626,16 @@ handle_event(_, _, State, Data) ->
</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
<seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>
@@ -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>