aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-02-24 09:41:34 +0100
committerRaimo Niskanen <[email protected]>2016-02-24 09:41:34 +0100
commit1958b93b4aa90883be5102d465f67f167549dea9 (patch)
tree409de86a9656caaa475003d5cbd6c0819c4d3701 /lib/stdlib/doc
parent2b3a82ae44b222ce1146badcff972abb539d40ca (diff)
downloadotp-1958b93b4aa90883be5102d465f67f167549dea9.tar.gz
otp-1958b93b4aa90883be5102d465f67f167549dea9.tar.bz2
otp-1958b93b4aa90883be5102d465f67f167549dea9.zip
Ditch State so StateName/5 -> StateName/4
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml64
1 files changed, 36 insertions, 28 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 096be3025e..8934d912c6 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -62,7 +62,7 @@ gen_statem:stop -----> Module:terminate/2
gen_statem:call
gen_statem:cast
erlang:send
-erlang:'!' -----> Module:StateName/5
+erlang:'!' -----> Module:StateName/4
Module:handle_event/5
- -----> Module:terminate/3
@@ -84,18 +84,28 @@ erlang:'!' -----> Module:StateName/5
in a <c>gen_statem</c> is the callback function that is called
for all events in this state, and is selected depending on
<seealso marker="#type-callback_mode">callback_mode</seealso>
- that the implementation selects during <c>gen_statem</c> init.
+ that the implementation specifies during <c>gen_statem</c> init.
</p>
<p>When
<seealso marker="#type-callback_mode">callback_mode</seealso>
is <c>state_functions</c> the state has to be an atom and
is used as the state function name.
See
- <seealso marker="#Module:StateName/5">
- <c>Module:StateName/5</c>
+ <seealso marker="#Module:StateName/4">
+ <c>Module:StateName/4</c>
</seealso>.
This gathers all code for a specific state
in one function and hence dispatches on state first.
+ Note that in this mode the callback function
+ <seealso marker="#Module:code_change/4">
+ <c>Module:code_change/4</c>
+ </seealso> makes the state name <c>code_change</c>
+ unusable. Actually you might get away with using it
+ as a state name but you will have to find a way to separate
+ the two callback roles e.g by observing that you can force
+ argument 3 into having different types for the different roles.
+ This is a slippery slope, though. It is easier
+ to simply not use <c>code_change</c> as a state name.
</p>
<p>When
<seealso marker="#type-callback_mode">callback_mode</seealso>
@@ -110,13 +120,11 @@ 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 <c>gen_statem</c> 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>There is a small gotcha in both callback modes regarding
+ the state <c>undefined</c> that is used as the previous state
+ when the first state function is called. So either do not
+ use <c>undefined</c> as a state, or figure out
+ the implications yourself.
</p>
<p>The <c>gen_statem</c> enqueues incoming events in order of arrival
and presents these to the
@@ -181,7 +189,7 @@ erlang:'!' -----> Module:StateName/5
for a long time. However use this feature with care
since hibernation implies at least two garbage collections
(when hibernating and shortly after waking up) and that is not
- something you'd want to do between each event on a busy server.
+ something you would want to do between each event on a busy server.
</p>
</description>
@@ -350,13 +358,20 @@ erlang:'!' -----> Module:StateName/5
<datatype>
<name name="callback_mode" />
<desc>
+ <p>
+ The <c>callback_mode</c> is selected when starting the
+ <c>gen_statem</c> using the return value from
+ <seealso marker="#Module:init/1">Module:init/1</seealso>
+ or when calling
+ <seealso marker="#enter_loop/5">enter_loop/5-7</seealso>.
+ </p>
<taglist>
<tag><c>state_functions</c></tag>
<item>The state has to be of type
<seealso marker="#type-state_name"><c>state_name()</c></seealso>
and one callback function per state that is
- <seealso marker="#Module:StateName/5">
- <c>Module:StateName/5</c>
+ <seealso marker="#Module:StateName/4">
+ <c>Module:StateName/4</c>
</seealso> is used. This is the default.
</item>
<tag><c>handle_event_function</c></tag>
@@ -384,7 +399,7 @@ erlang:'!' -----> Module:StateName/5
<seealso marker="#state_function">state function</seealso>,
from <seealso marker="#Module:init/1">Module:init/1</seealso>
or given to
- <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
+ <seealso marker="#enter_loop/6">enter_loop/6,7</seealso>.
</p>
<p>The processing order for a state change is:</p>
<list type="ordered">
@@ -990,7 +1005,7 @@ erlang:'!' -----> Module:StateName/5
<func>
<name>Module:StateName(EventType, EventContent,
- PrevStateName, StateName, Data) -> Result
+ PrevStateName, Data) -> Result
</name>
<name>Module:handle_event(EventType, EventContent,
PrevState, State, Data) -> Result
@@ -1004,9 +1019,6 @@ erlang:'!' -----> Module:StateName/5
<v>PrevStateName =
<seealso marker="#type-state_name">state_name()</seealso>
</v>
- <v>StateName =
- <seealso marker="#type-state_name">state_name()</seealso>
- </v>
<v>PrevState = State =
<seealso marker="#type-state">state()</seealso>
</v>
@@ -1023,10 +1035,9 @@ erlang:'!' -----> Module:StateName/5
<p>Whenever a <c>gen_statem</c> receives an event from
<seealso marker="#call/2">call/2</seealso>,
<seealso marker="#cast/2">cast/2</seealso> or
- as a normal process message this function is called.
- If
- <seealso marker="#type-callback_mode">callback_mode</seealso>
- is <c>state_functions</c> then <c>Module:StateName/5</c> is called,
+ as a normal process message one of these functions is called.
+ If <seealso marker="#type-callback_mode">callback_mode</seealso>
+ is <c>state_functions</c> then <c>Module:StateName/4</c> is called,
and if it is <c>handle_event_function</c>
then <c>Module:handle_event/5</c> is called.
</p>
@@ -1043,13 +1054,10 @@ erlang:'!' -----> Module:StateName/5
<c>reply(Caller, Reply)</c>
</seealso>.
</p>
- <p><c>StateName</c> is useful in some odd cases for example
- if you call a common event handling function from your state
- function then you might want to pass <c>StateName</c>.
- </p>
<p><c>PrevStateName</c> and <c>PrevState</c> are useful
in some odd cases for example when you want to do something
- only at the first event in a state.
+ only at the first event in a state, or when you need to
+ handle events differently depending on the previous state.
Note that when <c>gen_statem</c> enters its first state
this is set to <c>undefined</c>.
</p>