diff options
author | Raimo Niskanen <raimo@erlang.org> | 2019-09-09 13:59:00 +0200 |
---|---|---|
committer | Raimo Niskanen <raimo@erlang.org> | 2019-09-09 13:59:00 +0200 |
commit | 253349fd37db625a287e276ee1fc32bbb6638076 (patch) | |
tree | f611e7ceec8f7d09a4039bb047c6d73a4cff422a | |
parent | 4909281d7ba01db12d04281d8b4679e35b6adf8c (diff) | |
parent | 22db0a0d909692f3995760d9eaf1def1aaff14a5 (diff) | |
download | erlang-253349fd37db625a287e276ee1fc32bbb6638076.tar.gz |
Merge branch 'raimo/doc-cleanup' into maint
* raimo/doc-cleanup:
Mention action handling details in user's guide
Clarify handling of Actions
-rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 69 | ||||
-rw-r--r-- | system/doc/design_principles/statem.xml | 12 |
2 files changed, 53 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> @@ -776,44 +778,53 @@ handle_event(_, _, State, Data) -> </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> diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 23e9054547..81a0c617f1 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -624,6 +624,18 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> and set a time-out to use absolute instead of relative time (using the <c>Opts</c> field). </p> + <p> + Among these <em>transition actions</em> only to reply to a caller + is an immediate action. The others are collected and handled + later during the <em>state transition</em>. + <seealso marker="#Inserted Events">Inserted Events</seealso> + are stored and inserted all together, + and the rest set transition options + where the last of a specific type override the previous. + See the description of a <em>state transition</em> + in the <c>gen_statem(3)</c> manual page for type + <seealso marker="stdlib:gen_statem#type-transition_option"><c>transition_option()</c></seealso>. + </p> </section> <!-- =================================================================== --> |