aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/heart.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/heart.xml')
-rw-r--r--lib/kernel/doc/src/heart.xml174
1 files changed, 82 insertions, 92 deletions
diff --git a/lib/kernel/doc/src/heart.xml b/lib/kernel/doc/src/heart.xml
index 9da4773f2d..5b5b71e521 100644
--- a/lib/kernel/doc/src/heart.xml
+++ b/lib/kernel/doc/src/heart.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2013</year>
+ <year>1996</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -29,93 +29,84 @@
<rev>A</rev>
</header>
<module>heart</module>
- <modulesummary>Heartbeat Monitoring of an Erlang Runtime System</modulesummary>
+ <modulesummary>Heartbeat monitoring of an Erlang runtime system.</modulesummary>
<description>
<p>This modules contains the interface to the <c>heart</c> process.
<c>heart</c> sends periodic heartbeats to an external port
program, which is also named <c>heart</c>. The purpose of
- the heart port program is to check that the Erlang runtime system
+ the <c>heart</c> port program is to check that the Erlang runtime system
it is supervising is still running. If the port program has not
received any heartbeats within <c>HEART_BEAT_TIMEOUT</c> seconds
- (default is 60 seconds), the system can be rebooted. Also, if
- the system is equipped with a hardware watchdog timer and is
- running Solaris, the watchdog can be used to supervise the entire
- system.</p>
- <p>An Erlang runtime system to be monitored by a heart program,
- should be started with the command line flag <c>-heart</c> (see
- also <seealso marker="erts:erl">erl(1)</seealso>). The <c>heart</c>
- process is then started automatically:</p>
+ (defaults to 60 seconds), the system can be rebooted.</p>
+ <p>An Erlang runtime system to be monitored by a heart program
+ is to be started with command-line flag <c>-heart</c> (see
+ also <seealso marker="erts:erl"><c>erl(1)</c></seealso>).
+ The <c>heart</c> process is then started automatically:</p>
<pre>
% <input>erl -heart ...</input></pre>
- <p>If the system should be rebooted because of missing heart-beats,
- or a terminated Erlang runtime system, the environment variable
- <c>HEART_COMMAND</c> has to be set before the system is started.
- If this variable is not set, a warning text will be printed but
- the system will not reboot. However, if the hardware watchdog is
- used, it will trigger a reboot <c>HEART_BEAT_BOOT_DELAY</c>
- seconds later nevertheless (default is 60).</p>
- <p>To reboot on the WINDOWS platform <c>HEART_COMMAND</c> can be
+ <p>If the system is to be rebooted because of missing heartbeats,
+ or a terminated Erlang runtime system, environment variable
+ <c>HEART_COMMAND</c> must be set before the system is started.
+ If this variable is not set, a warning text is printed but
+ the system does not reboot.</p>
+ <p>To reboot on Windows, <c>HEART_COMMAND</c> can be
set to <c>heart -shutdown</c> (included in the Erlang delivery)
- or of course to any other suitable program which can activate a
- reboot.</p>
- <p>The hardware watchdog will not be started under Solaris if
- the environment variable <c>HW_WD_DISABLE</c> is set.</p>
- <p>The <c>HEART_BEAT_TIMEOUT</c> and <c>HEART_BEAT_BOOT_DELAY</c>
- environment variables can be used to configure the heart timeouts,
- they can be set in the operating system shell before Erlang is
- started or be specified at the command line:</p>
+ or to any other suitable program that can activate a reboot.</p>
+ <p>The environment variable <c>HEART_BEAT_TIMEOUT</c>
+ can be used to configure the heart
+ time-outs; it can be set in the operating system shell before Erlang
+ is started or be specified at the command line:</p>
<pre>
% <input>erl -heart -env HEART_BEAT_TIMEOUT 30 ...</input></pre>
<p>The value (in seconds) must be in the range 10 &lt; X &lt;= 65535.</p>
- <p>It should be noted that if the system clock is adjusted with
- more than <c>HEART_BEAT_TIMEOUT</c> seconds, <c>heart</c> will
- timeout and try to reboot the system. This can happen, for
- example, if the system clock is adjusted automatically by use of
- NTP (Network Time Protocol).</p>
-
- <p> If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> will <em>not</em> be written
- unless the environment variable <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set.
- </p>
-
+ <p>Notice that if the system clock is adjusted with
+ more than <c>HEART_BEAT_TIMEOUT</c> seconds, <c>heart</c>
+ times out and tries to reboot the system. This can occur, for
+ example, if the system clock is adjusted automatically by use of the
+ Network Time Protocol (NTP).</p>
+ <p>If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> is <em>not</em>
+ written unless environment variable
+ <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set:</p>
<pre>
% <input>erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...</input></pre>
-
- <p> If a regular core dump is wanted, let heart know by setting the kill signal to abort
- using the environment variable <c><![CDATA[HEART_KILL_SIGNAL=SIGABRT]]></c>.
- If unset, or not set to <c><![CDATA[SIGABRT]]></c>, the default behaviour will be a kill
- signal using <c><![CDATA[SIGKILL]]></c>.
- </p>
-
+ <p>If a regular core dump is wanted, let <c>heart</c> know by setting
+ the kill signal to abort using environment variable
+ <c><![CDATA[HEART_KILL_SIGNAL=SIGABRT]]></c>. If unset, or not set to
+ <c><![CDATA[SIGABRT]]></c>, the default behavior is a kill signal using
+ <c><![CDATA[SIGKILL]]></c>:</p>
<pre>
% <input>erl -heart -env HEART_KILL_SIGNAL SIGABRT ...</input></pre>
-
- <p>
- Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the following behaviour on
- <c>heart</c>:
+ <p> If heart should <em>not</em> kill the Erlang runtime system, this can be indicated
+ using the environment variable <c><![CDATA[HEART_NO_KILL=TRUE]]></c>.
+ This can be useful if the command executed by heart takes care of this,
+ for example as part of a specific cleanup sequence.
+ If unset, or not set to <c><![CDATA[TRUE]]></c>, the default behaviour
+ will be to kill as described above.
</p>
- <taglist>
- <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
- <item><p>
- Suppresses the writing a crash dump file entirely,
- thus rebooting the runtime system immediately.
- This is the same as not setting the environment variable.
- </p>
- </item>
- <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
- <item><p> Setting the environment variable to a negative value will not reboot
- the runtime system until the crash dump file has been completly written.
- </p>
- </item>
- <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
- <item><p>
- Heart will wait for <c>S</c> seconds to let the crash dump file be written.
- After <c>S</c> seconds <c>heart</c> will reboot the runtime system regardless of
- the crash dump file has been written or not.
- </p>
- </item>
- </taglist>
- <p>In the following descriptions, all function fails with reason
+ <pre>
+% <input>erl -heart -env HEART_NO_KILL 1 ...</input></pre>
+
+ <p>Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the
+ following behavior on <c>heart</c>:</p>
+ <taglist>
+ <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
+ <item><p>Suppresses the writing of a crash dump file entirely,
+ thus rebooting the runtime system immediately.
+ This is the same as not setting the environment variable.</p>
+ </item>
+ <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
+ <item><p>Setting the environment variable to a negative value does not
+ reboot the runtime system until the crash dump file is completly
+ written.</p>
+ </item>
+ <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
+ <item><p><c>heart</c> waits for <c>S</c> seconds to let the crash dump
+ file be written. After <c>S</c> seconds, <c>heart</c> reboots the
+ runtime system, whether the crash dump file is written or not.</p>
+ </item>
+ </taglist>
+ <p>In the following descriptions, all functions fail with reason
<c>badarg</c> if <c>heart</c> is not started.</p>
</description>
@@ -128,37 +119,36 @@
<funcs>
<func>
<name name="set_cmd" arity="1"/>
- <fsummary>Set a temporary reboot command</fsummary>
+ <fsummary>Set a temporary reboot command.</fsummary>
<desc>
- <p>Sets a temporary reboot command. This command is used if
+ <p>Sets a temporary reboot command. This command is used if
a <c>HEART_COMMAND</c> other than the one specified with
- the environment variable should be used in order to reboot
- the system. The new Erlang runtime system will (if it
- misbehaves) use the environment variable
- <c>HEART_COMMAND</c> to reboot.</p>
-
- <p>Limitations: The <c><anno>Cmd</anno></c> command string
- will be sent to the heart program as a ISO-latin-1 or UTF-8
- encoded binary depending on the file name encoding mode of the
- emulator (see
- <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>).
- The size of the encoded binary must be less than 2047 bytes.</p>
+ the environment variable is to be used to reboot
+ the system. The new Erlang runtime system uses (if it misbehaves)
+ environment variable <c>HEART_COMMAND</c> to reboot.</p>
+ <p>Limitations: Command string <c><anno>Cmd</anno></c> is sent to the
+ <c>heart</c> program as an ISO Latin-1 or UTF-8 encoded binary,
+ depending on the filename encoding mode of the emulator (see
+ <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>).
+ The size of the encoded binary must be less than 2047 bytes.</p>
</desc>
</func>
+
<func>
<name name="clear_cmd" arity="0"/>
- <fsummary>Clear the temporary boot command</fsummary>
+ <fsummary>Clear the temporary boot command.</fsummary>
<desc>
<p>Clears the temporary boot command. If the system terminates,
the normal <c>HEART_COMMAND</c> is used to reboot.</p>
</desc>
</func>
+
<func>
<name name="get_cmd" arity="0"/>
- <fsummary>Get the temporary reboot command</fsummary>
+ <fsummary>Get the temporary reboot command.</fsummary>
<desc>
- <p>Get the temporary reboot command. If the command is cleared,
- the empty string will be returned.</p>
+ <p>Gets the temporary reboot command. If the command is cleared,
+ the empty string is returned.</p>
</desc>
</func>
@@ -166,12 +156,12 @@
<name name="set_callback" arity="2"/>
<fsummary>Set a validation callback</fsummary>
<desc>
- <p> This validation callback will be executed before any heartbeat sent
- to the port program. For the validation to succeed it needs to return
- with the value <c>ok</c>.
+ <p> This validation callback will be executed before any
+ heartbeat is sent to the port program. For the validation to
+ succeed it needs to return with the value <c>ok</c>.
</p>
- <p> An exception within the callback will be treated as a validation failure. </p>
- <p> The callback will be removed if the system reboots. </p>
+ <p>An exception within the callback will be treated as a validation failure.</p>
+ <p>The callback will be removed if the system reboots.</p>
</desc>
</func>
<func>