aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-03-17 15:41:26 +0100
committerRaimo Niskanen <[email protected]>2016-03-17 15:41:26 +0100
commit0eddc557de9b0a996ab42aefd66f3229a06f6675 (patch)
tree21f2a67df2f9f2b59506864b7239610526d385db
parent65d2eecef2dedb012abcc76c855b8da90934f10c (diff)
downloadotp-0eddc557de9b0a996ab42aefd66f3229a06f6675.tar.gz
otp-0eddc557de9b0a996ab42aefd66f3229a06f6675.tar.bz2
otp-0eddc557de9b0a996ab42aefd66f3229a06f6675.zip
Do documentation improvements from Fred Hebert
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml66
1 files changed, 54 insertions, 12 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 4708fc1301..90d2326954 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -35,10 +35,10 @@
A behaviour module for implementing a state machine.
Two callback modes are supported. One for a finite state
machine like <seealso marker="gen_fsm">gen_fsm</seealso>
- that require the state to be an atom and use that state as
+ that requires the state to be an atom and use that state as
the name of the callback function for a particular state,
- and one without restriction on the state that use the same
- callback function for all states.
+ and one without restriction on the state data type
+ that uses the same callback function for all states.
</p>
<p>
A generic state machine process (<c>gen_statem</c>) implemented
@@ -96,7 +96,7 @@ erlang:'!' -----> Module:StateName/3
<p>
When
<seealso marker="#type-callback_mode">callback_mode</seealso>
- is <c>state_functions</c> the state has to be an atom and
+ 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/3">
<c>Module:StateName/3</c>
@@ -127,8 +127,8 @@ erlang:'!' -----> Module:StateName/3
<seealso marker="#state_function">state function</seealso>
in that order. The state function can postpone an event
so it is not retried in the current state.
- After a state change all enqueued events (including postponed)
- are again presented to the state function.
+ After a state change all enqueued events (including postponed ones)
+ are presented again to the state function.
</p>
<p>
The <c>gen_statem</c> event queue model is sufficient
@@ -177,8 +177,10 @@ erlang:'!' -----> Module:StateName/3
</p>
<p>
Note that a <c>gen_statem</c> does not trap exit signals
- automatically, this must be explicitly initiated by
- the callback module.
+ automatically, this must be explicitly initiated in
+ the callback module (by calling
+ <seealso marker="erts:erlang#process_flag/2">
+ <c>process_flag(trap_exit, true)</c></seealso>.
</p>
<p>
Unless otherwise stated, all functions in this module fail if
@@ -293,6 +295,42 @@ ok
in function gen:do_for_proc/2 (gen.erl, line 261)
in call from gen_statem:call/3 (gen_statem.erl, line 386)
</pre>
+
+ <p>
+ And just to compare styles here is the same example using
+ <seealso marker="#type-callback_mode">
+ <c>callback_mode</c>
+ </seealso>
+ <c>state_functions</c>, or rather here is code to replace
+ from the <c>init/1</c> function of the <c>pushbutton</c>
+ example module above:
+ </p>
+ <code type="erl">
+init([]) ->
+ %% Set the callback mode and initial state + data.
+ %% Data is used only as a counter.
+ State = off, Data = 0,
+ {handle_event_function,State,Data}.
+
+
+%%% Event handling
+
+handle_event({call,Caller}, push, off, Data) ->
+ %% Go to 'on', increment count and reply
+ %% that the resulting status is 'on'
+ {next_state,on,Data+1,[{reply,Caller,on}]};
+handle_event({call,Caller}, push, on, Data) ->
+ %% Go to 'off' and reply that the resulting status is 'off'
+ {next_state,off,Data,[{reply,Caller,off}]};
+%%
+%% Event handling common to all states
+handle_event({call,Caller}, get_count, State, Data) ->
+ %% Reply with the current count
+ {next_state,State,Data,[{reply,Caller,Data}]};
+handle_event(_, _, State, Data) ->
+ %% Ignore all other events
+ {next_state,State,Data}.
+ </code>
</section>
<datatypes>
@@ -564,8 +602,8 @@ ok
<desc>
<p>
If <c>true</c> postpone the current event and retry
- it when the state changes that is:
- <c>NextState =/= State</c>.
+ it when the state changes
+ (<c>NextState =/= State</c>).
</p>
</desc>
</datatype>
@@ -778,14 +816,18 @@ ok
The <c>gen_statem</c> will keep the current state, or
do a state transition to the current state if you like,
set <c><anno>NewData</anno></c>
- and execute all <c><anno>Actions</anno></c>
+ and execute all <c><anno>Actions</anno></c>.
+ This is the same as
+ <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>.
</item>
<tag><c>keep_state_and_data</c></tag>
<item>
The <c>gen_statem</c> will keep the current state or
do a state transition to the current state if you like,
keep the current server data,
- and execute all <c><anno>Actions</anno></c>
+ and execute all <c><anno>Actions</anno></c>.
+ This is the same as
+ <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>.
</item>
</taglist>
<p>