heart(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💖 heart(3) 💖 — the Erlang Module Definition, bestie edition

okay so bestie, gather round, because today we're talking about heart — an Erlang module, yes, and it is so much more than a cute name. it lives in the kernel application, it's part of the Erlang module definitions, and it's about to be your new favorite thing for keeping a runtime system alive. let's get into it 💅

✨ NAME ✨

heart — heartbeat monitoring of an Erlang runtime system. literally the cardiologist of your node 🫶

🌸 DESCRIPTION 🌸

okay so this module? it's the interface to the heart process. and what does heart do? it sends periodic heartbeats to an external port program, which is also named heart. iconic name reuse, we love a family business. 👑

and the whole point of that port program? it checks that the Erlang runtime system it's supervising is still running. if the port program hasn't received any heartbeats within HEART_BEAT_TIMEOUT seconds (and that defaults to 60 seconds, no cap), the system can be rebooted. it's giving "you haven't texted me back in an hour so i'm assuming the worst" energy 😭

so, an Erlang runtime system that you want monitored by a heart program has to be started with the command-line flag -heart (peep also erl(1)). once you do that, the heart process starts automatically, like it was already invited to the party:

% erl -heart ...

now — if the system is gonna be rebooted because of missing heartbeats, or because the Erlang runtime system terminated, the environment variable HEART_COMMAND must be set before the system is started. if that variable isn't set, a warning text gets printed but the system does not reboot. so like, it'll tell you it's sad but it won't actually do anything about it 🙈

for real for real: set HEART_COMMAND first, or the reboot just... doesn't happen.

to reboot on Windows, HEART_COMMAND can be set to heart -shutdown (that one's included in the Erlang delivery, you're welcome) or to any other suitable program that can activate a reboot. your choice, your moment ✨

the environment variable HEART_BEAT_TIMEOUT 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:

% erl -heart -env HEART_BEAT_TIMEOUT 30 ...

the value is in seconds, and it must be in the range 10 < X <= 65535. yes, strictly greater than 10, we're not doing that.

when running on OSs lacking support for monotonic time, heart is susceptible to system clock adjustments of more than HEART_BEAT_TIMEOUT seconds. when this happens, heart 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). so basically the clock does a little jig and heart panics. clock drama. 💀

if a crash occurs, an erl_crash.dump is not written unless environment variable ERL_CRASH_DUMP_SECONDS is set:

% erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...

if a regular core dump is wanted, let heart know by setting the kill signal to abort using environment variable HEART_KILL_SIGNAL=SIGABRT. if unset, or not set to SIGABRT, the default behavior is a kill signal using SIGKILL:

% erl -heart -env HEART_KILL_SIGNAL SIGABRT ...

if heart should not kill the Erlang runtime system, this can be indicated using the environment variable HEART_NO_KILL=TRUE. 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 TRUE, the default behaviour will be to kill as described above. so like, you can tell it hands off, but only if you say the magic word 🪄

% erl -heart -env HEART_NO_KILL 1 ...

furthermore, ERL_CRASH_DUMP_SECONDS has the following behavior on heart — and bestie, pay attention, these three are a whole vibe check:

  • ERL_CRASH_DUMP_SECONDS=0 — 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.
  • ERL_CRASH_DUMP_SECONDS=-1 — setting the environment variable to a negative value does not reboot the runtime system until the crash dump file is completely written. patience, queen.
  • ERL_CRASH_DUMP_SECONDS=S — heart waits for S seconds to let the crash dump file be written. after S seconds, heart reboots the runtime system, whether the crash dump file is written or not. clock's ticking either way, no exceptions 🕰️

in the following descriptions, all functions fail with reason badarg if heart is not started. so like, start heart first, or everything's just gonna be errors. rude, but fair.

🦋 DATA TYPES 🦋

  • heart_option() :: check_schedulers.

🎀 FUNCTIONS 🎀

clear_callback() -> ok.

removes the validation callback call before heartbeats. bye bestie, your callback's gone 👋

clear_cmd() -> ok.

clears the temporary boot command. if the system terminates, the normal HEART_COMMAND is used to reboot. back to the original plan, slay.

get_callback() -> {ok, {Module, Function}} | none with Module :: atom(), Function :: atom().

get the validation callback. if the callback is cleared, none will be returned. honestly the most honest return value.

get_cmd() -> {ok, Cmd} with Cmd :: string().

gets the temporary reboot command. if the command is cleared, the empty string is returned. (that's "", an empty little string, a void where a command used to be 💀)

get_options() -> {ok, Options} | none with Options :: [atom()].

returns {ok, Options} where Options is a list of current options enabled for heart. if the callback is cleared, none will be returned. (yes, it says callback here. we're just telling you what it says. 🫶)

set_callback(Module, Function) -> ok | {error, {bad_callback, {Module, Function}}} with Module :: atom(), Function :: atom().

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 ok. so like, if your callback comes back with anything but ok, no heartbeat for you.

an exception within the callback will be treated as a validation failure. no second chances, no retries, straight to the fail pile 😭

the callback will be removed if the system reboots. so it's not forever-forever, it's just for now.

set_cmd(Cmd) -> ok | {error, {bad_cmd, Cmd}} with Cmd :: string().

sets a temporary reboot command. this command is used if a HEART_COMMAND other than the one specified with the environment variable is to be used to reboot the system. the new Erlang runtime system uses (if it misbehaves) environment variable HEART_COMMAND to reboot.

Limitations: command string Cmd is sent to the heart program as an ISO Latin-1 or UTF-8 encoded binary, depending on the filename encoding mode of the emulator (see file:native_name_encoding/0). the size of the encoded binary must be less than 2047 bytes. so keep it snappy, bestie, 2046 bytes or less 🔥

set_options(Options) -> ok | {error, {bad_options, Options}} with Options :: [heart_option()].

valid options for set_options are:

  • check_schedulers — if enabled, a signal will be sent to each scheduler to check its responsiveness. the system check occurs before any heartbeat sent to the port program. if any scheduler is not responsive enough, the heart program will not receive its heartbeat and thus eventually terminate the node. drama, but make it scheduled.

returns with the value ok if the options are valid. ✅

👑 SEE ALSO 👑

erl(1), file:native_name_encoding/0 — go read those too, iykyk. (peep the references in the Description and in set_cmd above, they're both right there 🫶)

and that's the whole page, bestie!! this one came from Ericsson AB, it's part of kernel 11.0.3, and it's filed under heart(3) 💅 go forth and monitor those heartbeats, you main character ✨🦋💖

📦 where this page comes from