rpc - Remote Procedure Call services.
Please see following description for synopsis
rpc(3) Erlang Module Definition rpc(3)
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 col-
lect 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.
Note:
rpc:call() and friends makes it quite hard to distinguish between suc-
cessful results, raised exceptions, and other errors. This cannot be
changed due to compatibility reasons. As of OTP 23, a new module erpc
was introduced in order to provide an API that makes it possible to
distingush between the different results. The erpc module provides a
subset (however, the central subset) of the functionality available in
the rpc module. The erpc implementation also provides a more scalable
implementation with better performance than the original rpc implemen-
tation. However, since the introduction of erpc, the rpc module imple-
ments large parts of its central functionality using erpc, so the rpc
module wont not suffer scalability wise and performance wise compared
to erpc.
DATA TYPES
key()
Opaque value 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:
If you want the ability to distinguish between results, you may
want to consider using the erpc:send_request() function from the
erpc module instead. This also gives you the ability retrieve
the results in other useful ways.
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.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be an rpc server, another server, or a
freshly spawned process.
block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
The same as calling rpc:block_call(Node, Module, Function, Args,
infinity).
block_call(Node, Module, Function, Args, Timeout) ->
Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = 0..4294967295 | infinity
The same as calling rpc:call(Node, Module, Function, Args, Time-
out) with the exception that it also blocks other
rpc:block_call() operations from executing concurrently on the
node Node.
Warning:
Note that it also blocks other operations than just
rpc:block_call() operations, so use it with care.
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. The same as calling rpc:call(Node, Module, Function,
Args, infinity).
call(Node, Module, Function, Args, Timeout) ->
Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = 0..4294967295 | infinity
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 con-
taminates the caller's message queue.
Note:
If you want the ability to distinguish between results, you may
want to consider using the erpc:call() function from the erpc
module instead.
Note:
Here follows the details of what exactly is returned.
{badrpc, Reason} will be returned in the following circum-
stances:
* 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',_}.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be the calling process itself, an rpc
server, another server, or a freshly spawned process.
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.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be an rpc server, another server, or a
freshly spawned process.
eval_everywhere(Module, Function, Args) -> abcast
Types:
Module = module()
Function = atom()
Args = [term()]
Equivalent to eval_everywhere([node()|nodes()], Module, Func-
tion, 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 fol-
lowing:
* 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 send-
ing 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, infin-
ity).
multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
Types:
Module = module()
Function = atom()
Args = [term()]
Timeout = 0..4294967295 | infinity
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 = 0..4294967295 | infinity
ResL = [Res :: term() | {badrpc, Reason :: term()}]
BadNodes = [node()]
In contrast to an RPC, a multicall is an RPC that is sent con-
currently 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, Rea-
son} for failing calls. Timeout is a time (integer) in millisec-
onds, 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.
Note:
If you want the ability to distinguish between results, you may
want to consider using the erpc:multicall() function from the
erpc module instead.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be the calling process itself, an rpc
server, another server, or a freshly spawned process.
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 = 0..4294967295 | infinity
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 mes-
sage.
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.
Ericsson AB kernel 8.2 rpc(3)