File 2186-Clarify-handling-of-Actions.patch of Package erlang
From e806c75e897b100649f1e14f85526408c66d34a3 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 31 Jul 2019 14:28:19 +0200
Subject: [PATCH 1/2] Clarify handling of Actions
---
lib/stdlib/doc/src/gen_statem.xml | 69 +++++++++++++++++++++++----------------
1 file changed, 41 insertions(+), 28 deletions(-)
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index ef548ad643..5513b7d649 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -720,7 +720,9 @@ handle_event(_, _, State, Data) ->
the <c>gen_statem</c> engine will, at every <em>state change</em>,
call the
<seealso marker="#state callback">state callback</seealso>
- with arguments <c>(enter, OldState, Data)</c>.
+ with arguments <c>(enter, OldState, Data)</c> or
+ <c>(enter, OldState, State, Data)</c>, depending on the
+ <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>.
This may look like an event but is really a call
performed after the previous
<seealso marker="#state callback"><em>state callback</em></seealso>
@@ -775,45 +777,54 @@ handle_event(_, _, State, Data) ->
Here are the sequence of steps for a <em>state transition</em>:
</p>
<list type="ordered">
+ <item>
+ <p>
+ All returned
+ <seealso marker="#type-action">actions</seealso>
+ are processed in order of appearance.
+ In this step all replies generated by any
+ <seealso marker="#type-reply_action"><c>reply_action()</c></seealso>
+ are sent. Other actions set <c>transition_option()</c>s
+ that come into play in subsequent steps.
+ </p>
+ </item>
<item>
<p>
If
<seealso marker="#type-state_enter">
<em>state enter calls</em>
</seealso>
- are used, and either:
- the state changes, it is the initial state,
- or one of the callback results
+ are used, and either
+ it is the initial state or one of the callback results
<seealso marker="#type-state_callback_result">
- <c>repeat_state</c>
+ <c>repeat_state_and_data</c>
</seealso>
or
<seealso marker="#type-state_callback_result">
<c>repeat_state_and_data</c>
</seealso>
- is used; the <c>gen_statem</c> calls
- the new state callback with arguments
- <seealso marker="#type-state_enter"><c>(enter, OldState, Data)</c></seealso>.
+ is used the <c>gen_statem</c> engine calls
+ the current state callback with arguments
+ <seealso marker="#type-state_enter"><c>(enter, State, Data)</c></seealso>
+ or
+ <seealso marker="#type-state_enter"><c>(enter, State, State, Data)</c></seealso>
+ (depending on <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>)
+ and when it returns starts again from the top of this sequence.
</p>
- <p>
- Any
- <seealso marker="#type-enter_action">actions</seealso>
- returned from this call are handled as if they were
- appended to the actions
- returned by the state callback that caused the state entry.
+ <p>
+ If
+ <seealso marker="#type-state_enter">
+ <em>state enter calls</em>
+ </seealso>
+ are used, and the state changes
+ the <c>gen_statem</c> engine calls
+ the new state callback with arguments
+ <seealso marker="#type-state_enter"><c>(enter, OldState, Data)</c></seealso>
+ or
+ <seealso marker="#type-state_enter"><c>(enter, OldState, State, Data)</c></seealso>
+ (depending on <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>)
+ and when it returns starts again from the top of this sequence.
</p>
- <p>
- Should this <em>state enter call</em> return any of
- the mentioned <c>repeat_*</c> callback results
- it is repeated again, with the updated <c>Data</c>.
- </p>
- </item>
- <item>
- <p>
- All
- <seealso marker="#type-action">actions</seealso>
- are processed in order of appearance.
- </p>
</item>
<item>
<p>
@@ -863,7 +874,9 @@ handle_event(_, _, State, Data) ->
A <em>state change</em> cancels a
<seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
and any new transition option of this type
- belongs to the new state.
+ belongs to the new state, that is; a
+ <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
+ applies to the state the state machine enters.
</p>
</item>
<item>
@@ -872,7 +885,7 @@ handle_event(_, _, State, Data) ->
<seealso marker="#state callback"><em>state callback</em></seealso>
for the possibly new state
is called with the oldest enqueued event,
- and we start again from the top of this list.
+ and we start again from the top of this sequence.
</p>
</item>
<item>
--
2.16.4
