NAME

       pool - Load Distribution Facility

DESCRIPTION

       pool 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:

         * The slave nodes send regular reports to the master about their current load.

         * Queries can be sent to the master to determine which node will have the least load.

       The BIF statistics(run_queue) is used for estimating future loads. It returns  the  length
       of the queue of ready to run processes in the Erlang runtime system.

       The slave nodes are started with the slave module. This effects, tty IO, file IO, and code
       loading.

       If the master node fails, the entire pool will exit.

EXPORTS

       start(Name) -> Nodes

       start(Name, Args) -> Nodes

              Types:

                 Name = atom()
                 Args = string()
                 Nodes = [node()]

              Starts a new pool. The file .hosts.erlang is read to find host names where the pool
              nodes  can be started. See section Files below. The start-up procedure fails if the
              file is not found.

              The slave nodes are started  with  slave:start/2,3,  passing  along  Name  and,  if
              provided,  Args.  Name is used as the first part of the node names, Args is used to
              specify command line arguments. See slave(3erl).

              Access rights must be set so that all nodes in  the  pool  have  the  authority  to
              access each other.

              The  function  is synchronous and all the nodes, as well as all the system servers,
              are running when it returns a value.

       attach(Node) -> already_attached | attached

              Types:

                 Node = node()

              This function ensures that a pool master is running and includes Node in  the  pool
              master's pool of nodes.

       stop() -> stopped

              Stops the pool and kills all the slave nodes.

       get_nodes() -> [node()]

              Returns a list of the current member nodes of the pool.

       pspawn(Mod, Fun, Args) -> pid()

              Types:

                 Mod = module()
                 Fun = atom()
                 Args = [term()]

              Spawns a process on the pool node which is expected to have the lowest future load.

       pspawn_link(Mod, Fun, Args) -> pid()

              Types:

                 Mod = module()
                 Fun = atom()
                 Args = [term()]

              Spawn  links a process on the pool node which is expected to have the lowest future
              load.

       get_node() -> node()

              Returns the node with the expected lowest future load.

FILES

       .hosts.erlang is used to pick hosts where nodes can  be  started.  See  net_adm(3erl)  for
       information about format and location of this file.

       $HOME/.erlang.slave.out.HOST  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.