path: root/lib/stdlib/doc/src/pool.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2013</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 name="start" arity="1"/>
      <name name="start" arity="2"/>
      <fsummary>>Start a new pool</fsummary>
      <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><anno>Name</anno></c> and, if provided,
          <c><anno>Args</anno></c>.
          <c><anno>Name</anno></c> is used as the first part of the node names,
          <c><anno>Args</anno></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 name="attach" arity="1"/>
      <fsummary>Ensure that a pool master is running</fsummary>
      <desc>
        <p>This function ensures that a pool master is running and
          includes <c><anno>Node</anno></c> in the pool master's pool of nodes.</p>
      </desc>
    </func>
    <func>
      <name name="stop" arity="0"/>
      <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 name="get_nodes" arity="0"/>
      <fsummary>Return a list of the current member nodes of the pool</fsummary>
      <desc>
        <p>Returns a list of the current member nodes of the pool.</p>
      </desc>
    </func>
    <func>
      <name name="pspawn" arity="3"/>
      <fsummary>Spawn a process on the pool node with expected lowest future load</fsummary>
      <desc>
        <p>Spawns a process on the pool node which is expected to have
          the lowest future load.</p>
      </desc>
    </func>
    <func>
      <name name="pspawn_link" arity="3"/>
      <fsummary>Spawn and link to a process on the pool node with expected lowest future load</fsummary>
      <desc>
        <p>Spawn links a process on the pool node which is expected to
          have the lowest future load.</p>
      </desc>
    </func>
    <func>
      <name name="get_node" arity="0"/>
      <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>