The R13B03 release.OTP_R13B03

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>
+