Provided by: erlang-manpages_22.2.7+dfsg-1_all bug

NAME

       rpc - Remote Procedure Call services.

DESCRIPTION

       This  module  contains  services  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

       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.

       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  that  does  not  suspend  the
              caller  until the result is finished. Instead, a key is returned, which can be used
              later 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 node Node.

          Note:
              yield/1  and  nb_yield/1,2  must  be  called  by  the  same process from which this
              function was made otherwise they will never yield correctly.

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

              Types:

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

              Same as 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.

              See the note in call/4 for more details of the return value.

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

              Types:

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

              Same as block_call/4, but with a time-out value in the same manner as call/5.

              See the note in call/4 for more details of the return value.

       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 node Node and returns the  corresponding
              value Res, or {badrpc, Reason} if the call fails.

          Note:
              Here follows the details of what exactly is returned.

              {badrpc, Reason} will be returned in the following circumstances:

                * The called function fails with an exit exception.

                * The called function fails with an error exception.

                * The called function returns a term that matches {'EXIT', _}.

                * The called function throws a term that matches {'EXIT', _}.

              Res is returned in the following circumstances:

                * The  called  function  returns  normally  with  a  term  that  does  not  match
                  {'EXIT',_}.

                * The called function throws a term that does not  match {'EXIT',_}.

       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 node Node and returns the  corresponding
              value  Res,  or  {badrpc, Reason} if the call fails. Timeout is a time-out value in
              milliseconds. If the call times out, Reason is timeout. See the note in call/4  for
              more details of the return value.

              If the reply arrives after the call times out, no message contaminates the caller's
              message queue, as 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.

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

              Types:

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

              Evaluates apply(Module, Function, Args) on 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.

       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()]

              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 one of the following:

                * A list of the nodes that do not exist

                * A list of the nodes where the server does not exist

                * A list of the nodes where the server terminated before sending any reply.

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

              Types:

                 Module = module()
                 Function = atom()
                 Args = [term()]
                 ResL = [Res :: term() | {badrpc, Reason :: 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 = [term()]
                 ResL = [Res :: term() | {badrpc, Reason :: 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 = [Res :: term() | {badrpc, Reason :: 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 = [Res :: term() | {badrpc, Reason :: term()}]
                 BadNodes = [node()]

              In  contrast  to  an  RPC, a multicall is an RPC that is sent concurrently from one
              client to multiple servers. This is useful for collecting 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 do not exist, and ResL is a list  of  the  return  values,  or  {badrpc,
              Reason}  for  failing  calls.  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 indicates some side effects that RPCs can 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.

       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()}

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

              See the note in call/4 for more details of Val.

          Note:
              This function must be called by the same process from which async_call/4  was  made
              otherwise it will only return timeout.

       parallel_eval(FuncCalls) -> ResL

              Types:

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

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

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

              Types:

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

              Location transparent version of the BIF erlang:process_info/1 in ERTS.

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

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

              Types:

                 Pid = pid()
                 Item = atom()
                 ItemList = [Item]
                 Info = term()

              Location transparent version of the BIF erlang:process_info/2 in ERTS.

       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.

       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 that 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 processed the message.

              Any  further  messages  sent  to the servers, after this function has returned, are
              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

              Can be used when interacting with a server called Name on 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}.

       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.

          Note:
              This  function  must be called by the same process from which async_call/4 was made
              otherwise it will never return.

              See the note in call/4 for more details of the return value.