aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/pool.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/pool.xml')
-rw-r--r--lib/stdlib/doc/src/pool.xml148
1 files changed, 148 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/pool.xml b/lib/stdlib/doc/src/pool.xml
new file mode 100644
index 0000000000..2b890352eb
--- /dev/null
+++ b/lib/stdlib/doc/src/pool.xml
@@ -0,0 +1,148 @@
+<?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>pool</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>pool</module>
+ <modulesummary>Load Distribution Facility</modulesummary>
+ <description>
+ <p><c>pool</c> can be used to run a set of Erlang nodes as a pool
+ of computational processors. It is organized as a master and a
+ set of slave nodes and includes the following features:</p>
+ <list type="bulleted">
+ <item>The slave nodes send regular reports to the master about
+ their current load.</item>
+ <item>Queries can be sent to the master to determine which node
+ will have the least load.</item>
+ </list>
+ <p>The BIF <c>statistics(run_queue)</c> is used for estimating
+ future loads. It returns the length of the queue of ready to run
+ processes in the Erlang runtime system.</p>
+ <p>The slave nodes are started with the <c>slave</c> module. This
+ effects, tty IO, file IO, and code loading.</p>
+ <p>If the master node fails, the entire pool will exit.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>start(Name) -></name>
+ <name>start(Name, Args) -> Nodes</name>
+ <fsummary>>Start a new pool</fsummary>
+ <type>
+ <v>Name = atom()</v>
+ <v>Args = string()</v>
+ <v>Nodes = [node()]</v>
+ </type>
+ <desc>
+ <p>Starts a new pool. The file <c>.hosts.erlang</c> is read to
+ find host names where the pool nodes can be started. See
+ section <seealso marker="#files">Files</seealso> below. The
+ start-up procedure fails if the file is not found.</p>
+ <p>The slave nodes are started with <c>slave:start/2,3</c>,
+ passing along <c>Name</c> and, if provided, <c>Args</c>.
+ <c>Name</c> is used as the first part of the node names,
+ <c>Args</c> is used to specify command line arguments. See
+ <seealso marker="slave#start/2">slave(3)</seealso>.</p>
+ <p>Access rights must be set so that all nodes in the pool have
+ the authority to access each other.</p>
+ <p>The function is synchronous and all the nodes, as well as
+ all the system servers, are running when it returns a value.</p>
+ </desc>
+ </func>
+ <func>
+ <name>attach(Node) -> already_attached | attached</name>
+ <fsummary>Ensure that a pool master is running</fsummary>
+ <type>
+ <v>Node = node()</v>
+ </type>
+ <desc>
+ <p>This function ensures that a pool master is running and
+ includes <c>Node</c> in the pool master's pool of nodes.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop() -> stopped</name>
+ <fsummary>Stop the pool and kill all the slave nodes</fsummary>
+ <desc>
+ <p>Stops the pool and kills all the slave nodes.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_nodes() -> Nodes</name>
+ <fsummary>Return a list of the current member nodes of the pool</fsummary>
+ <type>
+ <v>Nodes = [node()]</v>
+ </type>
+ <desc>
+ <p>Returns a list of the current member nodes of the pool.</p>
+ </desc>
+ </func>
+ <func>
+ <name>pspawn(Mod, Fun, Args) -> pid()</name>
+ <fsummary>Spawn a process on the pool node with expected lowest future load</fsummary>
+ <type>
+ <v>Mod = Fun = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Spawns a process on the pool node which is expected to have
+ the lowest future load.</p>
+ </desc>
+ </func>
+ <func>
+ <name>pspawn_link(Mod, Fun, Args) -> pid()</name>
+ <fsummary>Spawn and link to a process on the pool node with expected lowest future load</fsummary>
+ <type>
+ <v>Mod = Fun = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Spawn links a process on the pool node which is expected to
+ have the lowest future load.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_node() -> node()</name>
+ <fsummary>Return the node with the expected lowest future load</fsummary>
+ <desc>
+ <p>Returns the node with the expected lowest future load.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="files"></marker>
+ <title>Files</title>
+ <p><c>.hosts.erlang</c> is used to pick hosts where nodes can
+ be started. See
+ <seealso marker="kernel:net_adm#host_file/0">net_adm(3)</seealso>
+ for information about format and location of this file.</p>
+ <p><c>$HOME/.erlang.slave.out.HOST</c> is used for all additional IO
+ that may come from the slave nodes on standard IO. If the start-up
+ procedure does not work, this file may indicate the reason.</p>
+ </section>
+</erlref>
+