aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-09-30 11:17:22 +0200
committerRaimo Niskanen <[email protected]>2016-10-04 16:45:27 +0200
commit800265f49f912dcf66846b13aa8032bf2f380caf (patch)
treeef3768768f9f8309f660a59f89fd61b24c63d9d4
parent04d40c5cd18aca449606c19608e8044f593ee99e (diff)
downloadotp-800265f49f912dcf66846b13aa8032bf2f380caf.tar.gz
otp-800265f49f912dcf66846b13aa8032bf2f380caf.tar.bz2
otp-800265f49f912dcf66846b13aa8032bf2f380caf.zip
Improve docs and types
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml77
-rw-r--r--lib/stdlib/src/gen_statem.erl38
-rw-r--r--system/doc/design_principles/statem.xml17
3 files changed, 101 insertions, 31 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index aa34f53d29..bba2de5e77 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -674,6 +674,9 @@ handle_event(_, _, State, Data) ->
they are merged with the current
That is: <c>hibernate</c> and <c>timeout</c> overrides
the current and <c>reply</c> sends a reply.
+ This has the same effect as if you would have appended
+ the actions from this state enter call to the actions
+ returned by the state function that changed states.
</p>
</item>
<item>
@@ -1002,28 +1005,42 @@ handle_event(_, _, State, Data) ->
</desc>
</datatype>
<datatype>
- <name name="common_state_callback_result"/>
+ <name name="keep_state_callback_result"/>
<desc>
<taglist>
- <tag><c>stop</c></tag>
+ <tag><c>keep_state</c></tag>
<item>
<p>
- Terminates the <c>gen_statem</c> by calling
- <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
- with <c>Reason</c> and
- <c><anno>NewData</anno></c>, if specified.
+ The <c>gen_statem</c> keeps the current state, or
+ does a state transition to the current state if you like,
+ sets <c><anno>NewData</anno></c>,
+ and executes all <c><anno>Actions</anno></c>.
+ This is the same as
+ <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>.
</p>
</item>
- <tag><c>stop_and_reply</c></tag>
+ <tag><c>keep_state_and_data</c></tag>
<item>
<p>
- Sends all <c><anno>Replies</anno></c>,
- then terminates the <c>gen_statem</c> by calling
- <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
- with <c>Reason</c> and
- <c><anno>NewData</anno></c>, if specified.
+ The <c>gen_statem</c> keeps the current state or
+ does a state transition to the current state if you like,
+ keeps the current server data,
+ and executes all <c><anno>Actions</anno></c>.
+ This is the same as
+ <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>.
</p>
</item>
+ </taglist>
+ <p>
+ All these terms are tuples or atoms and this property
+ will hold in any future version of <c>gen_statem</c>.
+ </p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="keep_state_callback_enter_result"/>
+ <desc>
+ <taglist>
<tag><c>keep_state</c></tag>
<item>
<p>
@@ -1053,6 +1070,36 @@ handle_event(_, _, State, Data) ->
</p>
</desc>
</datatype>
+ <datatype>
+ <name name="common_state_callback_result"/>
+ <desc>
+ <taglist>
+ <tag><c>stop</c></tag>
+ <item>
+ <p>
+ Terminates the <c>gen_statem</c> by calling
+ <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
+ with <c>Reason</c> and
+ <c><anno>NewData</anno></c>, if specified.
+ </p>
+ </item>
+ <tag><c>stop_and_reply</c></tag>
+ <item>
+ <p>
+ Sends all <c><anno>Replies</anno></c>,
+ then terminates the <c>gen_statem</c> by calling
+ <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
+ with <c>Reason</c> and
+ <c><anno>NewData</anno></c>, if specified.
+ </p>
+ </item>
+ </taglist>
+ <p>
+ All these terms are tuples or atoms and this property
+ will hold in any future version of <c>gen_statem</c>.
+ </p>
+ </desc>
+ </datatype>
</datatypes>
<funcs>
@@ -1462,7 +1509,7 @@ handle_event(_, _, State, Data) ->
CallbackMode =
<seealso marker="#type-callback_mode">callback_mode()</seealso> |
[ <seealso marker="#type-callback_mode">callback_mode()</seealso>
- | <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso> ]
+ | <seealso marker="#type-state_enter">state_enter()</seealso> ]
</v>
</type>
<desc>
@@ -1490,9 +1537,9 @@ handle_event(_, _, State, Data) ->
</p>
<p>
The <c>CallbackMode</c> is either just
- <seealso marker="#type-callback_mode">callback_mode()</seealso>
+ <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso>
or a list containing
- <seealso marker="#type-callback_mode">callback_mode()</seealso>
+ <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso>
and possibly the atom
<seealso marker="#type-state_enter"><c>state_enter</c></seealso>.
</p>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index aedcfc932f..9f5573af86 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -142,7 +142,7 @@
NextStateName :: state_name(),
NewData :: data(),
Actions :: [action()] | action()} |
- common_state_callback_result().
+ keep_state_callback_result().
-type state_function_enter_result() ::
{'next_state', % {next_state,NextStateName,NewData,[]}
NextStateName :: state_name(),
@@ -151,7 +151,7 @@
NextStateName :: state_name(),
NewData :: data(),
Actions :: [enter_action()] | enter_action()} |
- common_state_callback_result().
+ keep_state_callback_enter_result().
-type handle_event_result() ::
{'next_state', % {next_state,NextState,NewData,[]}
@@ -161,7 +161,7 @@
NextState :: state(),
NewData :: data(),
Actions :: [action()] | action()} |
- common_state_callback_result().
+ keep_state_callback_result().
-type handle_event_enter_result() ::
{'next_state', % {next_state,NextState,NewData,[]}
NextState :: state(),
@@ -170,6 +170,28 @@
NextState :: state(),
NewData :: data(),
Actions :: [enter_action()] | enter_action()} |
+ keep_state_callback_enter_result().
+
+-type keep_state_callback_result() ::
+ {'keep_state', % {keep_state,NewData,[]}
+ NewData :: data()} |
+ {'keep_state', % Keep state, change data
+ NewData :: data(),
+ Actions :: [action()] | action()} |
+ 'keep_state_and_data' | % {keep_state_and_data,[]}
+ {'keep_state_and_data', % Keep state and data -> only actions
+ Actions :: [action()] | action()} |
+ common_state_callback_result().
+
+-type keep_state_callback_enter_result() ::
+ {'keep_state', % {keep_state,NewData,[]}
+ NewData :: data()} |
+ {'keep_state', % Keep state, change data
+ NewData :: data(),
+ Actions :: [enter_action()] | enter_action()} |
+ 'keep_state_and_data' | % {keep_state_and_data,[]}
+ {'keep_state_and_data', % Keep state and data -> only actions
+ Actions :: [enter_action()] | enter_action()} |
common_state_callback_result().
-type common_state_callback_result() ::
@@ -185,15 +207,7 @@
{'stop_and_reply', % Reply then stop the server
Reason :: term(),
Replies :: [reply_action()] | reply_action(),
- NewData :: data()} |
- {'keep_state', % {keep_state,NewData,[]}
- NewData :: data()} |
- {'keep_state', % Keep state, change data
- NewData :: data(),
- Actions :: [ActionType] | ActionType} |
- 'keep_state_and_data' | % {keep_state_and_data,[]}
- {'keep_state_and_data', % Keep state and data -> only actions
- Actions :: [ActionType] | ActionType}.
+ NewData :: data()}.
%% The state machine init function. It is called only once and
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index d2a9b23570..69d1e8e9fa 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -29,7 +29,7 @@
<rev></rev>
<file>statem.xml</file>
</header>
- <marker id="gen_statem behaviour"></marker>
+ <marker id="gen_statem Behaviour"></marker>
<p>
This section is to be read with the
<seealso marker="stdlib:gen_statem"><c>gen_statem(3)</c></seealso>
@@ -199,7 +199,10 @@ handle_event(EventType, EventContent, State, Data) ->
<title>State Enter Calls</title>
<p>
The <c>gen_statem</c> behavior can regardless of callback mode
- automatically call the state function
+ automatically
+ <seealso marker="stdlib:gen_statem#type-state_enter">
+ call the state function
+ </seealso>
with special arguments whenever the state changes
so you can write state entry actions
near the rest of the state transition rules.
@@ -214,8 +217,13 @@ StateName(EventType, EventContent, Data) ->
{next_state, NewStateName, NewData}.</pre>
<p>
Depending on how your state machine is specified,
- this can be a very useful feature, but if you use it
- you will have to handle the state enter call in all states.
+ this can be a very useful feature,
+ but it forces you to handle the state enter calls in all states.
+ See also the
+ <seealso marker="#State Entry Actions">
+ State Entry Actions
+ </seealso>
+ chapter.
</p>
</section>
@@ -964,6 +972,7 @@ do_unlock() ->
<!-- =================================================================== -->
<section>
+ <marker id="State Entry Actions"></marker>
<title>State Entry Actions</title>
<p>
Say you have a state machine specification