rpc
Remote Procedure Call services.
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.
Functions
abcast(Name, Msg) -> abcast
Name = atom()
Msg = term()
Equivalent to abcast([node()|nodes()],
.
abcast(Nodes, Name, Msg) -> abcast
Nodes = [node()]
Name = atom()
Msg = term()
Broadcasts the message
asynchronously to
the registered process
on the specified
nodes.
async_call(Node, Module, Function, Args) -> Key
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
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(
on node
.
block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Same as call/4
,
but the RPC server at
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 = 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}
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Evaluates apply(
on node
and returns
the corresponding value
, or
{badrpc,
if the call fails.
call(Node, Module, Function, Args, Timeout) ->
Res | {badrpc, Reason}
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = timeout()
Evaluates apply(
on node
and returns
the corresponding value
, or
{badrpc,
if the call fails.
is
a time-out value in milliseconds. If the call times out,
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
Node = node()
Module = module()
Function = atom()
Args = [term()]
Evaluates apply(
on 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
Module = module()
Function = atom()
Args = [term()]
Equivalent to eval_everywhere([node()|nodes()],
.
eval_everywhere(Nodes, Module, Function, Args) -> abcast
Nodes = [node()]
Module = module()
Function = atom()
Args = [term()]
Evaluates apply(
on
the specified nodes. No answers are collected.
multi_server_call(Name, Msg) -> {Replies, BadNodes}
Name = atom()
Msg = term()
Replies = [Reply :: term()]
BadNodes = [node()]
Equivalent to multi_server_call([node()|nodes()],
.
multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
Nodes = [node()]
Name = atom()
Msg = term()
Replies = [Reply :: term()]
BadNodes = [node()]
Can be used when interacting with servers called
on the specified nodes. It is assumed that
the servers receive messages in the format
{From,
and reply using
From ! {
, where
Node
is the name of the node where the server is located.
The function returns {
, where
is a
list of all
values, and
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}
Module = module()
Function = atom()
Args = ResL = [term()]
BadNodes = [node()]
Equivalent to multicall([node()|nodes()],
.
multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
Nodes = [node()]
Module = module()
Function = atom()
Args = ResL = [term()]
BadNodes = [node()]
Args = [term()]
Timeout = timeout()
ResL = [term()]
Equivalent to multicall(
.
Equivalent to multicall([node()|nodes()],
.
multicall(Nodes, Module, Function, Args, Timeout) ->
{ResL, BadNodes}
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(
on the specified nodes and collects the answers. It returns
{
, where
is a list
of the nodes that terminated or timed out during computation,
and
is a list of the return values.
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
Key = key()
Val = (Res :: term()) | {badrpc, Reason :: term()}
Equivalent to nb_yield(
.
nb_yield(Key, Timeout) -> {value, Val} | timeout
Key = key()
Timeout = timeout()
Val = (Res :: term()) | {badrpc, Reason :: term()}
Non-blocking version of
yield/1
. It returns
the tuple {value,
when the computation is
finished, or timeout
when
milliseconds has elapsed.
parallel_eval(FuncCalls) -> ResL
FuncCalls = [{Module, Function, Args}]
Module = module()
Function = atom()
Args = ResL = [term()]
Evaluates, for every tuple in
,
apply(
on some node in
the network. Returns the list of return values, in the same
order as in
.
pinfo(Pid) -> [{Item, Info}] | undefined
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 | []
Pid = pid()
Item = atom()
Info = term()
ItemList = [Item]
Location transparent version of the BIF
erlang:process_info/2
in ERTS
.
pmap(FuncSpec, ExtraArgs, List1) -> List2
FuncSpec = {Module, Function}
Module = module()
Function = atom()
ExtraArgs = [term()]
List1 = [Elem :: term()]
List2 = [term()]
Evaluates apply(
for every element
in
, in parallel.
Returns the list of return values, in the same order as in
.
sbcast(Name, Msg) -> {GoodNodes, BadNodes}
Name = atom()
Msg = term()
GoodNodes = BadNodes = [node()]
Equivalent to sbcast([node()|nodes()],
.
sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
Name = atom()
Msg = term()
Nodes = GoodNodes = BadNodes = [node()]
Broadcasts the message
synchronously to
the registered process
on the specified
nodes.
Returns {
,
where
is the list of nodes that have
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}
Node = node()
Name = atom()
ReplyWrapper = Msg = Reply = term()
Reason = nodedown
Can be used when interacting with a server called
on node
. It is
assumed that the server receives messages in the format
{From,
and replies using
From ! {
. 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
as
produced by the server
, or
{error,
.
yield(Key) -> Res | {badrpc, Reason}
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
.