aboutsummaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2018-03-20 03:34:23 -0700
committerRaimo Niskanen <[email protected]>2018-03-22 12:18:11 +0100
commitd86fd35ca0c65069955a34d6ae9fbc33b9663eb0 (patch)
tree81c804acf4e080541bd8fc008c71bcbf4ee0e0be /lib
parentea1963553ffb06eb1bda636f328718f91136ed9c (diff)
downloadotp-d86fd35ca0c65069955a34d6ae9fbc33b9663eb0.tar.gz
otp-d86fd35ca0c65069955a34d6ae9fbc33b9663eb0.tar.bz2
otp-d86fd35ca0c65069955a34d6ae9fbc33b9663eb0.zip
Update User's Guide and pointers to it
Diffstat (limited to 'lib')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml89
1 files changed, 62 insertions, 27 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index be0d64feba..252a8370ad 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -32,39 +32,43 @@
<modulesummary>Generic state machine behavior.</modulesummary>
<description>
<p>
- This behavior module provides a state machine. Two
- <seealso marker="#type-callback_mode"><em>callback modes</em></seealso>
- are supported:
+ <c>gen_statem</c> provides a generic state machine behaviour
+ and replaces its predecessor
+ <seealso marker="gen_fsm"><c>gen_fsm</c> </seealso>
+ since Erlang/OTP 20.0.
+ </p>
+ <p>
+ This reference manual describes types generated from the types
+ in the <c>gen_statem</c> source code, so they are correct.
+ However, the generated descriptions also reflect the type hiearchy,
+ which makes them kind of hard to read.
+ </p>
+ <p>
+ To get an overview of the concepts and operation of <c>gen_statem</c>,
+ do read the
+ <seealso marker="doc/design_principles:statem">User's Guide</seealso>.
+ It frequently links back to this reference manual to avoid containing
+ detailed facts that may rot by age.
</p>
- <list type="bulleted">
- <item>
- <p>One for finite-state machines
- (<seealso marker="gen_fsm"><c>gen_fsm</c></seealso> like),
- which requires the state to be an atom and uses that state as
- the name of the current callback function
- </p>
- </item>
- <item>
- <p>One without restriction on the state data type
- that uses one callback function for all states
- </p>
- </item>
- </list>
<note>
<p>
- This is a new behavior in Erlang/OTP 19.0.
- It has been thoroughly reviewed, is stable enough
- to be used by at least two heavy OTP applications,
- and is here to stay.
- Depending on user feedback, we do not expect
- but can find it necessary to make minor
- not backward compatible changes into Erlang/OTP 20.0.
+ This behavior appeared in Erlang/OTP 19.0.
+ In OTP 19.1 a backwards incompatible change of
+ the return tuple from
+ <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+ was made and the mandatory callback function
+ <seealso marker="#Module:callback_mode/0">
+ <c>Module:callback_mode/0</c>
+ </seealso>
+ was introduced. In OTP 20.0 the
+ <seealso marker="#type-generic_timeout"><c>generic timeouts</c></seealso>
+ were added.
</p>
</note>
<p>
- The <c>gen_statem</c> behavior replaces
- <seealso marker="gen_fsm"><c>gen_fsm</c> </seealso> in Erlang/OTP 20.0.
- It has the same features and adds some really useful:
+ <c>gen_statem</c> has got the same features that
+ <seealso marker="gen_fsm"><c>gen_fsm</c> </seealso>
+ had and adds some really useful:
</p>
<list type="bulleted">
<item>Gathered state code.</item>
@@ -78,6 +82,27 @@
<item>Reply from other state than the request.</item>
<item>Multiple <c>sys</c> traceable replies.</item>
</list>
+
+
+ <p>
+ Two
+ <seealso marker="#type-callback_mode"><em>callback modes</em></seealso>
+ are supported:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>One for finite-state machines
+ (<seealso marker="gen_fsm"><c>gen_fsm</c></seealso> like),
+ which requires the state to be an atom and uses that state as
+ the name of the current callback function
+ </p>
+ </item>
+ <item>
+ <p>One without restriction on the state data type
+ that uses one callback function for all states
+ </p>
+ </item>
+ </list>
<p>
The callback model(s) for <c>gen_statem</c> differs from
the one for <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>,
@@ -252,6 +277,16 @@ erlang:'!' -----> Module:StateName/3
to use after every event; see
<seealso marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seealso>.
</p>
+ <p>
+ There is also a server start option
+ <seealso marker="#type-hibernate_after_opt">
+ <c>{hibernate_after, Timeout}</c>
+ </seealso>
+ for
+ <seealso marker="#start/3"><c>start/3,4</c></seealso> or
+ <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>
+ that may be used to automatically hibernate the server.
+ </p>
</description>
<section>