aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-09-16 10:15:22 +0200
committerRaimo Niskanen <[email protected]>2016-09-16 10:50:25 +0200
commit4ebdabdca2c964887115f21405993f3916843d10 (patch)
tree29494e175d60748402cdc5635bb5bd5a3f6137fe
parent6ee0aefd8a0ea9c165211c42d5244182b5aa9210 (diff)
downloadotp-4ebdabdca2c964887115f21405993f3916843d10.tar.gz
otp-4ebdabdca2c964887115f21405993f3916843d10.tar.bz2
otp-4ebdabdca2c964887115f21405993f3916843d10.zip
Improve docs
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml33
-rw-r--r--system/doc/design_principles/statem.xml22
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[
...