aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-04-27 09:07:23 +0200
committerRaimo Niskanen <[email protected]>2016-04-27 09:07:23 +0200
commit75fa8578cb847c15a10360523ecdbaabf507128d (patch)
tree3c80052636fd0184aff6336ffb7627a4a64d1665 /system/doc
parent77e4a18ef12bddeafc3533de76a4096538ad6655 (diff)
parent471a50ef1391f6399664f8b992da7a67c32c8b86 (diff)
downloadotp-75fa8578cb847c15a10360523ecdbaabf507128d.tar.gz
otp-75fa8578cb847c15a10360523ecdbaabf507128d.tar.bz2
otp-75fa8578cb847c15a10360523ecdbaabf507128d.zip
Merge branch 'raimo/polish-gen_statem/OTP-13065'
* raimo/polish-gen_statem/OTP-13065: Fix hibernation subtlety
Diffstat (limited to 'system/doc')
-rw-r--r--system/doc/design_principles/statem.xml71
1 files changed, 71 insertions, 0 deletions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index a4b8fb06a0..ca0fce55e2 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -1448,4 +1448,75 @@ format_status(Opt, [_PDict,State,Data]) ->
</p>
</section>
+<!-- =================================================================== -->
+
+ <section>
+ <title>Hibernation</title>
+ <p>
+ If you have many servers in one node
+ and they have some state(s) in their lifetime in which
+ the servers can be expected to idle for a while,
+ and the amount of heap memory all these servers need
+ is a problem; then it is possible to minimize
+ the memory footprint of a server by hibernating it through
+ <seealso marker="stdlib:proc_lib#hibernate/3">
+ <c>proc_lib:hibernate/3</c>.
+ </seealso>
+ </p>
+ <note>
+ <p>
+ To hibernate a process is rather costly. See
+ <seealso marker="erts:erlang#hibernate/3">
+ <c>erlang:hibernate/3</c>.
+ </seealso>
+ It is in general not something you want to do
+ after every event.
+ </p>
+ </note>
+ <p>
+ We can in this example hibernate in the <c>{open,_}</c> state
+ since what normally happens in that state is that
+ the state timeout after a while
+ triggers a transition to <c>{locked,_}</c>:
+ </p>
+ <code type="erl"><![CDATA[
+...
+handle_event(
+ EventType, EventContent,
+ {open,LockButton}, #{timer := Timer} = Data) ->
+ case {EventType,EventContent} of
+ {internal,enter} ->
+ Tref = erlang:start_timer(10000, self(), lock),
+ do_unlock(),
+ {keep_state,Data#{timer := Tref},[hibernate]};
+...
+ ]]></code>
+ <p>
+ The
+ <seealso marker="stdlib:gen_statem#type-hibernate">
+ <c>[hibernate]</c>
+ </seealso>
+ action list on the last line
+ when entering the <c>{open,_}</c> state is the only change.
+ If any event arrives in the <c>{open,_},</c> state we
+ do not bother to re-hibernate, so the server stays
+ awake after any event.
+ </p>
+ <p>
+ To change that we would need to insert
+ the <c>hibernate</c> action in more places,
+ for example for the state independent <c>set_lock_button</c>
+ and <c>code_length</c> operations that then would have to
+ be aware of using <c>hibernate</c> while in the
+ <c>{open,_}</c> state which would clutter the code.
+ </p>
+ <p>
+ This server probably does not use an amount of
+ heap memory worth hibernating for.
+ To gain anything from hibernation your server would
+ have to actually produce some garbage during callback execution,
+ for which this example server may serve as a bad example.
+ </p>
+ </section>
+
</chapter>