aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/slave.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/stdlib/doc/src/slave.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/stdlib/doc/src/slave.xml')
-rw-r--r--lib/stdlib/doc/src/slave.xml215
1 files changed, 215 insertions, 0 deletions
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+
+ </legalnotice>
+
+ <title>slave</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>slave</module>
+ <modulesummary>Functions to Starting and Controlling Slave Nodes</modulesummary>
+ <description>
+ <p>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.</p>
+ <p>Slave nodes on other hosts than the current one are started with
+ the program <c>rsh</c>. The user must be allowed to <c>rsh</c> to
+ the remote hosts without being prompted for a password. This can
+ be arranged in a number of ways (refer to the <c>rsh</c>
+ 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 <c>rsh</c>
+ program.</p>
+ <p>An alternative to the <c>rsh</c> program can be specified on
+ the command line to <c>erl</c> as follows: <c>-rsh Program</c>.</p>
+ <p>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.</p>
+ <p>Currently, a node running on Windows NT can only start slave
+ nodes on the host on which it is running.</p>
+ <p>The master node must be alive.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>start(Host) -></name>
+ <name>start(Host, Name) -></name>
+ <name>start(Host, Name, Args) -> {ok, Node} | {error, Reason}</name>
+ <fsummary>Start a slave node on a host</fsummary>
+ <type>
+ <v>Host = Name = atom()</v>
+ <v>Args = string()</v>
+ <v>Node = node()</v>
+ <v>Reason = timeout | no_rsh | {already_running, Node}</v>
+ </type>
+ <desc>
+ <p>Starts a slave node on the host <c>Host</c>. 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.</p>
+ <p>The name of the started node will be <c>Name@Host</c>. 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).</p>
+ <p>The slave node resets its <c>user</c> 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.</p>
+ <p>The <c>Args</c> argument is used to set <c>erl</c> command
+ line arguments. If provided, it is passed to the new node and
+ can be used for a variety of purposes. See
+ <seealso marker="erts:erl#erl">erl(1)</seealso></p>
+ <p>As an example, suppose that we want to start a slave node at
+ host <c>H</c> with the node name <c>Name@H</c>, and we also
+ want the slave node to have the following properties:</p>
+ <list type="bulleted">
+ <item>
+ <p>directory <c>Dir</c> should be added to the code path;</p>
+ </item>
+ <item>
+ <p>the Mnesia directory should be set to <c>M</c>;</p>
+ </item>
+ <item>
+ <p>the unix <c>DISPLAY</c> environment variable should be
+ set to the display of the master node.</p>
+ </item>
+ </list>
+ <p>The following code is executed to achieve this:</p>
+ <code type="none">
+E = " -env DISPLAY " ++ net_adm:localhost() ++ ":0 ",
+Arg = "-mnesia_dir " ++ M ++ " -pa " ++ Dir ++ E,
+slave:start(H, Name, Arg).</code>
+ <p>If successful, the function returns <c>{ok, Node}</c>,
+ where <c>Node</c> is the name of the new node. Otherwise it
+ returns <c>{error, Reason}</c>, where <c>Reason</c> can be
+ one of:</p>
+ <taglist>
+ <tag><c>timeout</c></tag>
+ <item>
+ <p>The master node failed to get in contact with the slave
+ node. This can happen in a number of circumstances:</p>
+ <list type="bulleted">
+ <item>Erlang/OTP is not installed on the remote host</item>
+ <item>the file system on the other host has a different
+ structure to the the master</item>
+ <item>the Erlang nodes have different cookies.</item>
+ </list>
+ </item>
+ <tag><c>no_rsh</c></tag>
+ <item>
+ <p>There is no <c>rsh</c> program on the computer.</p>
+ </item>
+ <tag><c>{already_running, Node}</c></tag>
+ <item>
+ <p>A node with the name <c>Name@Host</c> already exists.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>start_link(Host) -></name>
+ <name>start_link(Host, Name) -></name>
+ <name>start_link(Host, Name, Args) -> {ok, Node} | {error, Reason}</name>
+ <fsummary>Start and link to a slave node on a host</fsummary>
+ <type>
+ <v>Host = Name = atom()</v>
+ <v>Args = string()</v>
+ <v>Node = node()</v>
+ <v>Reason = timeout | no_rsh | {already_running, Node}</v>
+ </type>
+ <desc>
+ <p>Starts a slave node in the same way as <c>start/1,2,3</c>,
+ except that the slave node is linked to the currently
+ executing process. If that process terminates, the slave node
+ also terminates.</p>
+ <p>See <c>start/1,2,3</c> for a description of arguments and
+ return values.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop(Node) -> ok</name>
+ <fsummary>Stop (kill) a node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ </type>
+ <desc>
+ <p>Stops (kills) a node.</p>
+ </desc>
+ </func>
+ <func>
+ <name>pseudo([Master | ServerList]) -> ok</name>
+ <fsummary>Start a number of pseudo servers</fsummary>
+ <type>
+ <v>Master = node()</v>
+ <v>ServerList = [atom()]</v>
+ </type>
+ <desc>
+ <p>Calls <c>pseudo(Master, ServerList)</c>. 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:</p>
+ <pre>
+% erl -name abc -s slave pseudo klacke@super x --</pre>
+ </desc>
+ </func>
+ <func>
+ <name>pseudo(Master, ServerList) -> ok</name>
+ <fsummary>Start a number of pseudo servers</fsummary>
+ <type>
+ <v>Master = node()</v>
+ <v>ServerList = [atom()]</v>
+ </type>
+ <desc>
+ <p>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.</p>
+ <p>For example, if we have started a slave node <c>N</c> and
+ want to execute <c>pxw</c> graphics code on this node, we can
+ start the server <c>pxw_server</c> as a pseudo server at
+ the slave node. The following code illustrates:</p>
+ <code type="none">
+rpc:call(N, slave, pseudo, [node(), [pxw_server]]).</code>
+ </desc>
+ </func>
+ <func>
+ <name>relay(Pid)</name>
+ <fsummary>Run a pseudo server</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>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
+ <c>Pid</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+