diff options
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 33 | ||||
| -rw-r--r-- | system/doc/design_principles/statem.xml | 22 |
2 files changed, 35 insertions, 20 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index a4c5438a08..944e9ab13b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -583,6 +583,20 @@ handle_event(_, _, State, Data) -> <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> + <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> + <p> + Note that a state entry event <em>will</em> be inserted + when 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 an actual state change. + </p> </desc> </datatype> <datatype> @@ -1335,7 +1349,7 @@ handle_event(_, _, State, Data) -> CallbackMode = <seealso marker="#type-callback_mode">callback_mode()</seealso> | [ <seealso marker="#type-callback_mode">callback_mode()</seealso> - | state_entry_events ] + | <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso> ] </v> </type> <desc> @@ -1368,23 +1382,6 @@ handle_event(_, _, State, Data) -> 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 return an inline constant diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 8090016b54..43359829b2 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -989,7 +989,17 @@ do_unlock() -> from your state machine to itself. </p> <p> - One example of using self-generated events can be when you have + One example for this is to pre-process incoming data, for example + decrypting chunks or collecting characters up to a line break. + This could be modelled with a separate state machine that sends + the pre-processed events to the main state machine, or to decrease + overhead the small pre-processing state machine can be implemented + in the common state event handling of the main state machine + using a few state data variables and then send the pre-processed + events as internal events to the main state machine. + </p> + <p> + Another example of using self-generated events can be when you have a state machine specification that uses state entry actions. You can code that using a dedicated function to do the state transition. But if you want that code to be @@ -1050,7 +1060,15 @@ enter(Tag, State, Data) -> <seealso marker="#state_entry_events">state entry events</seealso>. You will have to handle the state entry events in every state. If you want state entry code in just a few states the previous - example may be more suitable. + example may be more suitable, especially to only send internal + events when entering just those few states. + </p> + <p> + You can also in the previous example choose to generate + events looking just like the events you get from using + <seealso marker="#state_entry_events">state entry events</seealso>. + This may be confusing, or practical, + depending on your point of view. </p> <code type="erl"><![CDATA[ ... |