slave(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💅 slave — bestie, let's talk 💅

okay so you opened the manual page for slave from Erlang's stdlib, section 3, and honestly? iconic module, kind of a cursed name, we move. 🎀

✨ NAME ✨

slave — this module is literally just the functions for starting Erlang slave nodes. that's it, that's the whole vibe. 🦋

🌸 DESCRIPTION 🌸

okay so here's the tea, bestie, listen up:

  • Every single slave node you start with a master automatically terminates when the master terminates. no lingering, no ghosting, periodt. 💀
  • All terminal output produced at the slave gets sent right back to the master node. 🫶
  • File I/O? done through the master. yes queen, delegation. 👑

Slave nodes on hosts that aren't the current one get started with the ssh program. The user has to be allowed to ssh to the remote hosts without being prompted for a password. You can arrange that in a number of ways (for the details, go read the ssh documentation, iykyk). A slave node started on the same host as the master inherits certain environment values from the master, like the current directory and the environment variables. And for what you can assume about the environment when a slave is started on another host? that's also in the documentation for the ssh program. 📚

You can specify an alternative to the ssh program on the command line to erl(1), like this:

-rsh Program
⚠️ Heads up bestie — the command you pass with the -rsh flag is treated as a file name which may contain spaces. So it is not possible to include any command line options. The remote node gets launched as "$RSH" "$REMOTE_HOSTNAME" erl -detached -noinput ..., which means the erl command must be found in the path on the remote host. no shortcuts, sorry babe. 😭

The slave node is supposed to use the same file system as the master. At minimum, Erlang/OTP is to be installed in the same place on both computers, and the same version of Erlang is to be used. matching set, no mix and match. 🔥

A node running on Windows can only start slave nodes on the host on which it is running. windows stays local, that's the rule. 🪟

And the master node must be alive. that's the whole plot twist. don't try it otherwise. 🌈

👑 FUNCTIONS 👑

  • pseudo([Master :: node() | (ServerList :: [atom()])]) -> ok.
🙈 Deprecated: slave:pseudo/1 is deprecated; use the peer module instead.

Calls pseudo(Master, ServerList). And if you want to start a node from the command line and set up a number of pseudo servers, you can start an Erlang runtime system like this:

% erl -name abc -s slave pseudo klacke@super x --
  • pseudo(Master, ServerList) -> ok with Master :: node(), ServerList :: [atom()].
🙈 Deprecated: slave:pseudo/2 is deprecated; use the peer module instead.

Starts a number of pseudo servers. And what even is a pseudo server, you ask? bestie it's a server with a registered name that does literally nothing except pass on all messages to the real server that executes at a master node. A pseudo server is an intermediary that only has the same registered name as the real server. it's giving stand-in, it's giving understudy energy, it's giving main character's body double. 💅

Example time: say you started a slave node N and you want to execute pxw graphics code on this node. You can start server pxw_server as a pseudo server at the slave node, illustrated like this:

rpc:call(N, slave, pseudo, [node(), [pxw_server]]).
  • relay(Pid) -> no_return() when Pid :: pid().
🙈 Deprecated: slave:relay/1 is deprecated; use the peer module instead.

Runs a pseudo server. This function never returns any value, and the process that executes the function receives messages. All messages received are simply passed on to Pid. no thoughts, head empty, just forwarding. ✨

  • start(Host) -> {ok, Node} | {error, Reason} with Host :: inet:hostname(), Node :: node(), Reason :: timeout | no_rsh | {already_running, Node}.
🙈 Deprecated: slave:start/1 is deprecated; use the peer module instead.

Equivalent to start(Host, Name) where Name is the same as the node that executes this call.

start(Host) -> {ok, Node} | {error, Reason}
               when
                   Host :: inet:hostname(),
                   Node :: node(),
                   Reason :: timeout | no_rsh | {already_running, Node}.
  • start(Host, Name, Args) -> {ok, Node} | {error, Reason} with Host :: inet:hostname(), Name :: atom() | string(), Args :: string(), Node :: node(), Reason :: timeout | no_rsh | {already_running, Node}.
🙈 Deprecated: slave:start/3 is deprecated; use the peer module instead.
start(Host, Name, Args) -> {ok, Node} | {error, Reason}
               when
                   Host :: inet:hostname(),
                   Name :: atom() | string(),
                   Args :: string(),
                   Node :: node(),
                   Reason :: timeout | no_rsh | {already_running, Node}.

Starts a slave node on host Host. Bestie, host names do not need to necessarily be specified as fully qualified names — short names work too. same condition that applies to names of distributed Erlang nodes, so you know the drill. 🦋

The name of the started node becomes Name@Host.

The slave node resets its io:user/0 process so that all terminal I/O produced at the slave is automatically relayed to the master. Also, the file server is relayed to the master. everything comes home to mama. 🏠

Argument Args is used to set erl command-line arguments. It's passed to the new node and can be used for a variety of purposes; see erl(1).

Okay example time, because this one ate. Suppose you want to start a slave node at host H with node name Name@H and you want the slave node to have these properties:

  • Directory Dir is to be added to the code path.
  • The Mnesia directory is to be set to M.
  • The Unix DISPLAY environment variable is to be set to the display of the master node.

The following code is executed to achieve this:

E = " -env DISPLAY " ++ net_adm:localhost() ++ ":0 ",
Arg = "-mnesia_dir " ++ M ++ " -pa " ++ Dir ++ E,
slave:start(H, Name, Arg).

The function returns {ok, Node}, where Node is the name of the new node. Otherwise {error, Reason}, where Reason can be one of:

  • timeout — The master node failed to get in contact with the slave node. This can occur in a number of circumstances:
    • Erlang/OTP is not installed on the remote host.
    • The file system on the other host has a different structure to the the master.
    • The Erlang nodes have different cookies.
  • no_rsh — No remote shell program was found on the computer. Note that ssh is used by default, but this can be overridden with the -rsh flag.
  • {already_running, Node} — A node with name Name@Host already exists.
  • start_link(Host, Name, Args) -> {ok, Node} | {error, Reason} with Host :: inet:hostname(), Name :: atom() | string(), Args :: string(), Node :: node(), Reason :: timeout | no_rsh | {already_running, Node}.
🙈 Deprecated: slave:start_link/3 is deprecated; use the peer module instead.
start_link(Host, Name, Args) -> {ok, Node} | {error, Reason}
                    when
                        Host :: inet:hostname(),
                        Name :: atom() | string(),
                        Args :: string(),
                        Node :: node(),
                        Reason ::
                            timeout | no_rsh | {already_running, Node}.

Starts a slave node in the same way as start/1,2,3, except that the slave node is linked to the currently executing process. If that process terminates, the slave node also terminates. ride or die, fr fr. 💀

For a description of arguments and return values, see start/1,2,3.

  • stop(Node) -> ok when Node :: node().
🙈 Deprecated: slave:stop/1 is deprecated; use the peer module instead.

Stops (kills) a node. that's the whole thing. brutal, efficient, iconic. 🎀

and that's the page, bestie!! this gem was brought to you by Ericsson AB, running stdlib 8.0.4, and yes, it's the slave(3) manual page. mwah. 💖✨

📦 where this page comes from