Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
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.