aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-04-26 16:49:47 +0200
committerRaimo Niskanen <[email protected]>2016-04-27 09:01:00 +0200
commit471a50ef1391f6399664f8b992da7a67c32c8b86 (patch)
treed68e1a3ab621ee15b39422dd1452a3e5270c2edc /lib/stdlib/doc
parent7d000278728f5f8940d02fe9798735820baa79e5 (diff)
downloadotp-471a50ef1391f6399664f8b992da7a67c32c8b86.tar.gz
otp-471a50ef1391f6399664f8b992da7a67c32c8b86.tar.bz2
otp-471a50ef1391f6399664f8b992da7a67c32c8b86.zip
Fix hibernation subtlety
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml35
1 files changed, 22 insertions, 13 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 91332fbdde..ec7f267c64 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -216,19 +216,23 @@ erlang:'!' -----> Module:StateName/3
if bad arguments are given.
</p>
<p>
- The <c>gen_statem</c> process can go into hibernation (see
- <seealso marker="erts:erlang#hibernate/3">
- <c>erlang:hibernate/3</c>
- </seealso>) if a
+ The <c>gen_statem</c> process can go into hibernation; see
+ <seealso marker="proc_lib#hibernate/3">
+ <c>proc_lib:hibernate/3</c>.
+ </seealso>
+ It is done when a
<seealso marker="#state_function">state function</seealso> or
<seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
specifies <c>hibernate</c> in the returned
<seealso marker="#type-action"><c>Actions</c></seealso>
- list. This might be useful if the server is expected to be idle
- 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 would want to do between each event on a busy server.
+ list. This feature might be useful to reclaim process heap memory
+ while the server is expected to be idle for a long time.
+ However, use this feature with care
+ since hibernation can be too costly
+ to use after every event; see
+ <seealso marker="erts:erlang#hibernate/3">
+ <c>erlang:hibernate/3</c>.
+ </seealso>
</p>
</description>
@@ -619,7 +623,8 @@ handle_event(_, _, State, Data) ->
to wait for the next message. In hibernation the next
non-system event awakens the <c>gen_statem</c>, or rather
the next incoming message awakens the <c>gen_statem</c>
- but if it is a system event it goes back into hibernation.
+ but if it is a system event
+ it goes right back into hibernation.
</item>
</list>
</desc>
@@ -645,9 +650,13 @@ handle_event(_, _, State, Data) ->
</seealso>
before going into <c>receive</c>
to wait for a new external event.
- If there are enqueued events the <c>hibernate</c>
- is ignored as if an event just arrived and awakened
- the <c>gen_statem</c>.
+ If there are enqueued events,
+ to prevent receiving any new event; a
+ <seealso marker="erts:erlang#garbage_collect/0">
+ <c>garbage_collect/0</c>
+ </seealso> is done instead to simulate
+ that the <c>gen_statem</c> entered hibernation
+ and immediately got awakened by the oldest enqueued event.
</p>
</desc>
</datatype>