Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       rpc - Remote Procedure Call Services

DESCRIPTION

       This  module  contains  services  which  are  similar  to  remote procedure calls. It also
       contains broadcast facilities and parallel evaluators. A remote procedure call is a method
       to  call  a  function  on  a remote node and collect the answer. It is used for collecting
       information on a remote node, or for running a function with some specific side effects on
       the remote node.

DATA TYPES

       key()

              As returned by async_call/4.

EXPORTS

       call(Node, Module, Function, Args) -> Res | {badrpc, Reason}

              Types:

                 Node = node()
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Res = Reason = term()

              Evaluates   apply(Module,  Function,  Args)  on  the  node  Node  and  returns  the
              corresponding value Res, or {badrpc, Reason} if the call fails.

       call(Node, Module, Function, Args, Timeout) ->
               Res | {badrpc, Reason}

              Types:

                 Node = node()
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Res = Reason = term()
                 Timeout = timeout()

              Evaluates  apply(Module,  Function,  Args)  on  the  node  Node  and  returns   the
              corresponding  value  Res,  or  {badrpc,  Reason}  if  the call fails. Timeout is a
              timeout value in milliseconds. If the call times out, Reason is timeout.

              If the reply arrives after the call times out,  no  message  will  contaminate  the
              caller's  message  queue, since this function spawns off a middleman process to act
              as (a void) destination for such an orphan reply.  This  feature  also  makes  this
              function more expensive than call/4 at the caller's end.

       block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}

              Types:

                 Node = node()
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Res = Reason = term()

              Like  call/4,  but  the  RPC  server  at Node does not create a separate process to
              handle the call. Thus, this function can be used if the intention of the call is to
              block  the  RPC  server from any other incoming requests until the request has been
              handled. The function can also be used for efficiency reasons when very small  fast
              functions are evaluated, for example BIFs that are guaranteed not to suspend.

       block_call(Node, Module, Function, Args, Timeout) ->
                     Res | {badrpc, Reason}

              Types:

                 Node = node()
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Res = Reason = term()
                 Timeout = timeout()

              Like block_call/4, but with a timeout value in the same manner as call/5.

       async_call(Node, Module, Function, Args) -> Key

              Types:

                 Node = node()
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Key = key()

              Implements  call  streams  with  promises, a type of RPC which does not suspend the
              caller until the result is finished. Instead, a key is returned which can  be  used
              at  a  later  stage  to  collect  the  value. The key can be viewed as a promise to
              deliver the answer.

              In this case, the key Key is returned, which can be used in a  subsequent  call  to
              yield/1 or nb_yield/1,2 to retrieve the value of evaluating apply(Module, Function,
              Args) on the node Node.

       yield(Key) -> Res | {badrpc, Reason}

              Types:

                 Key = key()
                 Res = Reason = term()

              Returns the promised  answer  from  a  previous  async_call/4.  If  the  answer  is
              available,  it is returned immediately. Otherwise, the calling process is suspended
              until the answer arrives from Node.

       nb_yield(Key) -> {value, Val} | timeout

              Types:

                 Key = key()
                 Val = (Res :: term()) | {badrpc, Reason :: term()}

              Equivalent to nb_yield(Key, 0).

       nb_yield(Key, Timeout) -> {value, Val} | timeout

              Types:

                 Key = key()
                 Timeout = timeout()
                 Val = (Res :: term()) | {badrpc, Reason :: term()}

              This is a non-blocking version of yield/1. It returns the tuple {value,  Val}  when
              the computation has finished, or timeout when Timeout milliseconds has elapsed.

       multicall(Module, Function, Args) -> {ResL, BadNodes}

              Types:

                 Module = module()
                 Function = atom()
                 Args = ResL = [term()]
                 BadNodes = [node()]

              Equivalent to multicall([node()|nodes()], Module, Function, Args, infinity).

       multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}

              Types:

                 Nodes = [node()]
                 Module = module()
                 Function = atom()
                 Args = ResL = [term()]
                 BadNodes = [node()]

              Equivalent to multicall(Nodes, Module, Function, Args, infinity).

       multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}

              Types:

                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Timeout = timeout()
                 ResL = [term()]
                 BadNodes = [node()]

              Equivalent to multicall([node()|nodes()], Module, Function, Args, Timeout).

       multicall(Nodes, Module, Function, Args, Timeout) ->
                    {ResL, BadNodes}

              Types:

                 Nodes = [node()]
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Timeout = timeout()
                 ResL = [term()]
                 BadNodes = [node()]

              In  contrast  to  an RPC, a multicall is an RPC which is sent concurrently from one
              client to multiple servers. This is useful for collecting some information  from  a
              set  of  nodes,  or  for  calling a function on a set of nodes to achieve some side
              effects. It is semantically the same as iteratively making a series of RPCs on  all
              the  nodes,  but  the  multicall is faster as all the requests are sent at the same
              time and are collected one by one as they come back.

              The function evaluates apply(Module, Function, Args) on  the  specified  nodes  and
              collects  the answers. It returns {ResL, BadNodes}, where BadNodes is a list of the
              nodes that terminated or timed out during computation, and ResL is a  list  of  the
              return values. Timeout is a time (integer) in milliseconds, or infinity.

              The  following  example is useful when new object code is to be loaded on all nodes
              in the network, and also indicates some side effects RPCs may produce:

              %% Find object code for module Mod
              {Mod, Bin, File} = code:get_object_code(Mod),

              %% and load it on all nodes including this one
              {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),

              %% and then maybe check the ResL list.

       cast(Node, Module, Function, Args) -> true

              Types:

                 Node = node()
                 Module = module()
                 Function = atom()
                 Args = [term()]

              Evaluates apply(Module, Function, Args) on the node Node. No response is  delivered
              and  the  calling  process is not suspended until the evaluation is complete, as is
              the case with call/4,5.

       eval_everywhere(Module, Function, Args) -> abcast

              Types:

                 Module = module()
                 Function = atom()
                 Args = [term()]

              Equivalent to eval_everywhere([node()|nodes()], Module, Function, Args).

       eval_everywhere(Nodes, Module, Function, Args) -> abcast

              Types:

                 Nodes = [node()]
                 Module = module()
                 Function = atom()
                 Args = [term()]

              Evaluates apply(Module, Function, Args) on the  specified  nodes.  No  answers  are
              collected.

       abcast(Name, Msg) -> abcast

              Types:

                 Name = atom()
                 Msg = term()

              Equivalent to abcast([node()|nodes()], Name, Msg).

       abcast(Nodes, Name, Msg) -> abcast

              Types:

                 Nodes = [node()]
                 Name = atom()
                 Msg = term()

              Broadcasts  the  message  Msg  asynchronously to the registered process Name on the
              specified nodes.

       sbcast(Name, Msg) -> {GoodNodes, BadNodes}

              Types:

                 Name = atom()
                 Msg = term()
                 GoodNodes = BadNodes = [node()]

              Equivalent to sbcast([node()|nodes()], Name, Msg).

       sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}

              Types:

                 Name = atom()
                 Msg = term()
                 Nodes = GoodNodes = BadNodes = [node()]

              Broadcasts the message Msg synchronously to the  registered  process  Name  on  the
              specified nodes.

              Returns {GoodNodes, BadNodes}, where GoodNodes is the list of nodes which have Name
              as a registered process.

              The function is synchronous in the sense that it is known  that  all  servers  have
              received  the  message  when  the call returns. It is not possible to know that the
              servers have actually processed the message.

              Any further messages sent to the servers, after this function has returned, will be
              received by all servers after this message.

       server_call(Node, Name, ReplyWrapper, Msg) ->
                      Reply | {error, Reason}

              Types:

                 Node = node()
                 Name = atom()
                 ReplyWrapper = Msg = Reply = term()
                 Reason = nodedown

              This  function can be used when interacting with a server called Name at node Node.
              It is assumed that the server receives messages  in  the  format  {From,  Msg}  and
              replies using From ! {ReplyWrapper, Node, Reply}. This function makes such a server
              call and ensures that the entire call is packed into an  atomic  transaction  which
              either succeeds or fails. It never hangs, unless the server itself hangs.

              The  function  returns  the answer Reply as produced by the server Name, or {error,
              Reason}.

       multi_server_call(Name, Msg) -> {Replies, BadNodes}

              Types:

                 Name = atom()
                 Msg = term()
                 Replies = [Reply :: term()]
                 BadNodes = [node()]

              Equivalent to multi_server_call([node()|nodes()], Name, Msg).

       multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}

              Types:

                 Nodes = [node()]
                 Name = atom()
                 Msg = term()
                 Replies = [Reply :: term()]
                 BadNodes = [node()]

              This function can be  used  when  interacting  with  servers  called  Name  on  the
              specified  nodes.  It  is  assumed  that the servers receive messages in the format
              {From, Msg} and reply using From ! {Name, Node, Reply}, where Node is the  name  of
              the  node  where  the  server is located. The function returns {Replies, BadNodes},
              where Replies is a list of all Reply values and BadNodes is a  list  of  the  nodes
              which  did  not  exist,  or  where  the  server  did not exist, or where the server
              terminated before sending any reply.

       safe_multi_server_call(Name, Msg) -> {Replies, BadNodes}

       safe_multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}

              Types:

                 Nodes = [node()]
                 Name = atom()
                 Msg = term()
                 Replies = [Reply :: term()]
                 BadNodes = [node()]

          Warning:
              This function is deprecated. Use multi_server_call/2,3 instead.

              In Erlang/OTP R6B and earlier releases, multi_server_call/2,3 could not handle  the
              case where the remote node exists, but there is no server called Name. Instead this
              function had to be used.  In  Erlang/OTP  R7B  and  later  releases,  however,  the
              functions are equivalent, except for this function being slightly slower.

       parallel_eval(FuncCalls) -> ResL

              Types:

                 FuncCalls = [{Module, Function, Args}]
                 Module = module()
                 Function = atom()
                 Args = ResL = [term()]

              For  every tuple in FuncCalls, evaluates apply(Module, Function, Args) on some node
              in the network. Returns the list  of  return  values,  in  the  same  order  as  in
              FuncCalls.

       pmap(FuncSpec, ExtraArgs, List1) -> List2

              Types:

                 FuncSpec = {Module, Function}
                 Module = module()
                 Function = atom()
                 ExtraArgs = [term()]
                 List1 = [Elem :: term()]
                 List2 = [term()]

              Evaluates  apply(Module,  Function,  [Elem|ExtraArgs]),  for  every element Elem in
              List1, in parallel. Returns the list of return values, in  the  same  order  as  in
              List1.

       pinfo(Pid) -> [{Item, Info}] | undefined

              Types:

                 Pid = pid()
                 Item = atom()
                 Info = term()

              Location transparent version of the BIF process_info/1.

       pinfo(Pid, Item) -> {Item, Info} | undefined | []

              Types:

                 Pid = pid()
                 Item = atom()
                 Info = term()

              Location transparent version of the BIF process_info/2.