aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-02-18 16:38:57 +0100
committerRaimo Niskanen <[email protected]>2016-02-18 16:38:57 +0100
commit26a7af61fbffae90c0968d945ae8b146582ba068 (patch)
treef12f35150ed1ae57054d6a66810db72363a54e2d /lib/stdlib/doc
parent82f34a7a9de85b4afc0dac4c9c426939264c5039 (diff)
downloadotp-26a7af61fbffae90c0968d945ae8b146582ba068.tar.gz
otp-26a7af61fbffae90c0968d945ae8b146582ba068.tar.bz2
otp-26a7af61fbffae90c0968d945ae8b146582ba068.zip
Change initial PrevState to 'undefined'
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml27
1 files changed, 24 insertions, 3 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 5fbedb12f8..9d98763973 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -110,6 +110,14 @@ erlang:'!' -----> Module:StateName/5
states so you do not accidentally postpone one event
forever creating an infinite busy loop.
</p>
+ <p>Any state name or any state value (depending on
+ <seealso marker="#type-callback_mode">callback_mode</seealso>)
+ is permitted with a small gotcha regarding the state
+ <c>undefined</c> that is used as the previous state when
+ the first gen_statem state function is called.
+ You might need to know about this faked state if you
+ inspect the previous state argument in your state functions.
+ </p>
<p>The gen_statem enqueues incoming events in order of arrival
and presents these to the
<seealso marker="#state_function">state function</seealso>
@@ -118,6 +126,12 @@ erlang:'!' -----> Module:StateName/5
After a state change all enqueued events (including postponed)
are again presented to the state function.
</p>
+ <p>The gen_statem event queue model is sufficient to emulate
+ the normal process message queue and selective receive
+ with postponing an event corresponding to not matching
+ it in a receive statement and changing states corresponding
+ to entering a new receive statement.
+ </p>
<p>The
<seealso marker="#state_function">state function</seealso>
can insert events using the
@@ -133,6 +147,15 @@ erlang:'!' -----> Module:StateName/5
that can be used for such events making it impossible
to mistake for an external event.
</p>
+ <p>Inserting an event replaces the trick of calling your own
+ state handling functions that you often would have to
+ resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
+ to force processing a faked event before others.
+ If you for example in gen_statem postpone an event
+ in one state and then call some other state function of yours,
+ you have not changed states and hence the postponed event
+ will not be retried, which is logical but might be confusing.
+ </p>
<p>A gen_statem handles system messages as documented in
<seealso marker="sys">sys</seealso>.
The <seealso marker="sys">sys</seealso> module
@@ -1011,7 +1034,6 @@ erlang:'!' -----> Module:StateName/5
<v>EventContent = term()</v>
<v>PrevStateName =
<seealso marker="#type-state_name">state_name()</seealso>
- | reference()
</v>
<v>StateName =
<seealso marker="#type-state_name">state_name()</seealso>
@@ -1060,8 +1082,7 @@ erlang:'!' -----> Module:StateName/5
in some odd cases for example when you want to do something
only at the first event in a state.
Note that when gen_statem enters its first state
- this is set to a <c>reference()</c>
- since that can not match equal to any state.
+ this is set to <c>undefined</c>.
</p>
<p>If this function returns with a new state that
does not match equal (<c>=/=</c>) to the current state