rpc
(kernel)Remote Procedure Call Services
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.
Functions
call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
Node = node()
Module = Function = atom()
Args = [term()]
Res = term()
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}
Node = node()
Module = Function = atom()
Args = [term()]
Res = term()
Reason = timeout | term()
Timeout = int() | infinity
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}
Node = node()
Module = Function = atom()
Args = [term()]
Res = term()
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}
Node = node()
Module = Function = atom()
Args = [term()]
Timeout = int() | infinity
Res = term()
Reason = term()
Like block_call/4
, but with a timeout value in
the same manner as call/5
.
async_call(Node, Module, Function, Args) -> Key
Node = node()
Module = Function = atom()
Args = [term()]
Key -- see below
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}
Key -- see async_call/4
Res = term()
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
Key -- see async_call/4
Val = Res | {badrpc, Reason}
Res = term()
Reason = term()
Equivalent to nb_yield(Key, 0)
.
nb_yield(Key, Timeout) -> {value, Val} | timeout
Key -- see async_call/4
Timeout = int() | infinity
Val = Res | {badrpc, Reason}
Res = term()
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}
Module = Function = atom()
Args = [term()]
ResL = [term()]
BadNodes = [node()]
Equivalent to multicall([node()|nodes()], Module, Function, Args, infinity)
.
multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
Nodes = [node()]
Module = Function = atom()
Args = [term()]
ResL = [term()]
BadNodes = [node()]
Equivalent to multicall(Nodes, Module, Function, Args, infinity)
.
multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
Module = Function = atom()
Args = [term()]
Timeout = int() | infinity
ResL = [term()]
BadNodes = [node()]
Equivalent to multicall([node()|nodes()], Module, Function, Args, Timeout)
.
multicall(Nodes, Module, Function, Args, Timeout) -> {ResL, BadNodes}
Nodes = [node()]
Module = Function = atom()
Args = [term()]
Timeout = int() | infinity
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, Bin, File,]), %% and then maybe check the ResL list.
cast(Node, Module, Function, Args) -> void()
Node = node()
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, Funtion, Args) -> void()
Module = Function = atom()
Args = [term()]
Equivalent to eval_everywhere([node()|nodes()], Module, Function, Args)
.
eval_everywhere(Nodes, Module, Function, Args) -> void()
Nodes = [node()]
Module = Function = atom()
Args = [term()]
Evaluates apply(Module, Function, Args)
on
the specified nodes. No answers are collected.
abcast(Name, Msg) -> void()
Name = atom()
Msg = term()
Equivalent to abcast([node()|nodes()], Name, Msg)
.
abcast(Nodes, Name, Msg) -> void()
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}
Name = atom()
Msg = term()
GoodNodes = BadNodes = [node()]
Equivalent to sbcast([node()|nodes()], Name, Msg)
.
sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
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}
Node = node()
Name = atom()
ReplyWrapper = Msg = Reply = term()
Reason = term()
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}
Name = atom()
Msg = term()
Replies = [Reply]
Reply = term()
BadNodes = [node()]
Equivalent to multi_server_call([node()|nodes()], Name, Msg)
.
multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
Nodes = [node()]
Name = atom()
Msg = term()
Replies = [Reply]
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}
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
FuncCalls = [{Module, Function, Args}]
Module = Function = atom()
Args = [term()]
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({Module, Function}, ExtraArgs, List2) -> List1
Module = Function = atom()
ExtraArgs = [term()]
List1 = [Elem]
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
Pid = pid()
Item, Info -- see erlang:process_info/1
Location transparent version of the BIF
process_info/1
.
pinfo(Pid, Item) -> {Item, Info} | undefined | []
Pid = pid()
Item, Info -- see erlang:process_info/1
Location transparent version of the BIF
process_info/2
.
- call/4
- call/5
- block_call/4
- block_call/5
- async_call/4
- yield/1
- nb_yield/1
- nb_yield/2
- multicall/3
- multicall/4
- multicall/4-1
- multicall/5
- cast/4
- eval_everywhere/3
- eval_everywhere/4
- abcast/2
- abcast/3
- sbcast/2
- sbcast/3
- server_call/4
- multi_server_call/2
- multi_server_call/3
- safe_multi_server_call/2
- safe_multi_server_call/3
- parallel_eval/1
- pmap/4
- pinfo/1
- pinfo/2