From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/slave.xml | 215 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 lib/stdlib/doc/src/slave.xml (limited to 'lib/stdlib/doc/src/slave.xml') diff --git a/lib/stdlib/doc/src/slave.xml b/lib/stdlib/doc/src/slave.xml new file mode 100644 index 0000000000..168d83f301 --- /dev/null +++ b/lib/stdlib/doc/src/slave.xml @@ -0,0 +1,215 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + slave + + + + +
+ slave + Functions to Starting and Controlling Slave Nodes + +

This module provides functions for starting Erlang slave nodes. + All slave nodes which are started by a master will terminate + automatically when the master terminates. All TTY output produced + at the slave will be sent back to the master node. File I/O is + done via the master.

+

Slave nodes on other hosts than the current one are started with + the program rsh. The user must be allowed to rsh to + the remote hosts without being prompted for a password. This can + be arranged in a number of ways (refer to the rsh + documentation for details). A slave node started on the same host + as the master inherits certain environment values from the master, + such as the current directory and the environment variables. For + what can be assumed about the environment when a slave is started + on another host, read the documentation for the rsh + program.

+

An alternative to the rsh program can be specified on + the command line to erl as follows: -rsh Program.

+

The slave node should use the same file system at the master. At + least, Erlang/OTP should be installed in the same place on both + computers and the same version of Erlang should be used.

+

Currently, a node running on Windows NT can only start slave + nodes on the host on which it is running.

+

The master node must be alive.

+ + + + start(Host) -> + start(Host, Name) -> + start(Host, Name, Args) -> {ok, Node} | {error, Reason} + Start a slave node on a host + + Host = Name = atom() + Args = string() + Node = node() + Reason = timeout | no_rsh | {already_running, Node} + + +

Starts a slave node on the host Host. Host names need + not necessarily be specified as fully qualified names; short + names can also be used. This is the same condition that + applies to names of distributed Erlang nodes.

+

The name of the started node will be Name@Host. If no + name is provided, the name will be the same as the node which + executes the call (with the exception of the host name part of + the node name).

+

The slave node resets its user process so that all + terminal I/O which is produced at the slave is automatically + relayed to the master. Also, the file process will be relayed + to the master.

+

The Args argument is used to set erl command + line arguments. If provided, it is passed to the new node and + can be used for a variety of purposes. See + erl(1)

+

As an example, suppose that we want to start a slave node at + host H with the node name Name@H, and we also + want the slave node to have the following properties:

+ + +

directory Dir should be added to the code path;

+ + +

the Mnesia directory should be set to M;

+ + +

the unix DISPLAY environment variable should 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). +

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

+ + timeout + +

The master node failed to get in contact with the slave + node. This can happen 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 + +

There is no rsh program on the computer.

+ + {already_running, Node} + +

A node with the name Name@Host already exists.

+ + + + + + start_link(Host) -> + start_link(Host, Name) -> + start_link(Host, Name, Args) -> {ok, Node} | {error, Reason} + Start and link to a slave node on a host + + Host = Name = atom() + 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.

+

See start/1,2,3 for a description of arguments and + return values.

+ + + + stop(Node) -> ok + Stop (kill) a node + + Node = node() + + +

Stops (kills) a node.

+ + + + pseudo([Master | ServerList]) -> ok + Start a number of pseudo servers + + Master = node() + ServerList = [atom()] + + +

Calls pseudo(Master, ServerList). If we want to start + a node from the command line and set up a number of pseudo + servers, an Erlang runtime system can be started as + follows:

+ 
+% erl -name abc -s slave pseudo klacke@super x --
+ + + + pseudo(Master, ServerList) -> ok + Start a number of pseudo servers + + Master = node() + ServerList = [atom()] + + +

Starts a number of pseudo servers. A pseudo server is a + server with a registered name which does absolutely nothing + but pass on all message to the real server which executes at a + master node. A pseudo server is an intermediary which only has + the same registered name as the real server.

+

For example, if we have started a slave node N and + want to execute pxw graphics code on this node, we can + start the server pxw_server as a pseudo server at + the slave node. The following code illustrates:

+ +rpc:call(N, slave, pseudo, [node(), [pxw_server]]). + + + + relay(Pid) + Run a pseudo server + + Pid = pid() + + +

Runs a pseudo server. This function never returns any value + and the process which executes the function will receive + messages. All messages received will simply be passed on to + Pid.

+ + + + + -- cgit v1.2.3