Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all 
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.
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.
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.
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.
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 terminatd before sending any reply.
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 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 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 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.
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.