diff options
Diffstat (limited to 'lib/stdlib/doc/src')
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 82 |
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> |