![[Erlang Systems]](min_head.gif)
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.
Starts the rpc server. Normally, this is not necessary
because the rpc server is started automatically.
Stops the rpc server.
call(Node, Module, Function, Args)
Evaluates apply(Mod, Fun, Args) on the node Node
and returns a value, or {badrpc, Reason} if the call fails.
cast(Node, Module, Function, Args)
Causes the expression apply(Mod, Fun, Args) to be evaluated on
Node. No response is delivered and the process which makes
the call is not suspended until the evaluation is complete, as is the
case with call/4. The function immediately returns true.
Example:
> rpc:cast(Node, erlang, halt, [])
This function shuts down the node Node.
The following function also shuts down the node, but the call returns the tuple
{badrpc, noconnection}
> rpc:call(Node, erlang, halt, [])
block_call(Node, Mod, Fun, Args)
The call/4 function causes the server at Node to create a
new process for each request. This means that several RPCs can be active
concurrently. The rpc server is not affected if a request does not return a value. 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.
> rpc:block_call(Node, erlang, whereis, [file_server]),
Returns the Pid of the file server at Node.
server_call(Node, Name, ReplyWrapper, Msg)
This function is used when interacting
with a server called Name at node Node.
It is assumed that the server receives messages in the
format {From, Request} and replies in the format
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
{error, Reason}, or the answer as produced by the server
Name.
Broadcasts the message Mess asynchronously to the registered
process Name on all nodes, including the current node.
The same as abcast/2, but only to the nodes Nodes.
Broadcasts to all nodes synchronously and
returns a list of the nodes which have Name
as a registered server. Returns {Goodnodes, Badnodes}.
It is synchronous in the sense that it is known that all servers have received the message when we return from the call. 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 .
As sbcast/2 but only to the nodes in Nodes.
eval_everywhere(Mod, Fun, Args)
Evaluates the expression apply(Mod, Fun, Args)
on all nodes. No answers are collected.
eval_everywhere(Nodes, Mod, Fun, Args)
Evaluates the expression apply(Mod, Fun, Args)
on the nodes Nodes.
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 multicall/3 evaluates the expression
apply(M, F, A)
on all nodes and collects the answers. It returns
{Replies, Badnodes},
where Badnodes is a list of the nodes that terminated
during computation
and Replies is a list of the return values. This is useful
when new object code is to be loaded on all nodes in the network.
%% Find object code for module Mod
{Mod, File, Bin} = code:get_object_code(Mod),
%% and load it on all nodes including this one
{Replies, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
%% and then maybe check the Replies list.
This is an example of the side effects the RPCs may produce.
Executes the multicall only on the nodes Nodes.
The function sends Msg to Name on all nodes,
and collects the answers. It returns
{Replies, Badnodes},
where Badnodes is a list of the nodes which failed during
the call. This function assumes that if a request
sent to a server
called Name, the server replies in the form
{Name, node(), Reply}. Otherwise, the function will hang.
It also assumes that the server receives messages in the form
{From, Msg}, and then replies as
From ! {Name, node(), Reply}.
If any of the nodes or servers does not exist or
crashes during the call, they appear in the
Badnodes list.
 |
If any of the nodes are of an older release of Erlang, the server cannot be monitored, and this function hangs if the server does not exist. |
If all nodes are of the current release of Erlang,
safe_multi_server_call/2,3 is now obsolete and
much more inefficient than multi_server_call/2,3.
The replies are not ordered in any particular way.
multi_server_call(Nodes, Name, Msg)
The same as above, but Msg is only sent to Nodes.
safe_multi_server_call(Name, Msg)
The same as the multi_server_call/2, except that this
function handles the case where the remote node exists,
but no server called Name exists there,
and the remote node is of an older release of Erlang.
This call is also slightly slower than multi_server_call/2
since all request go via the rpc server at the
remote sites.
safe_multi_server_call(Nodes, Name, Msg)
The same as above, but only on the nodes Nodes.
async_call(Node, Mod, Fun, Args)
Call streams with promises is a type of rpc which does
not suspend the caller until the result is finished. They return
a Key which can be used at a later stage to collect the
value. The key can be viewed as a promise to deliver the
answer. The expression apply(Mod, Fun, Args) is
evaluated for this function on Node. Returns Key
which can be used in a subsequent yield/1 (see below).
Delivers the promised answer from a previous async_call
operation. If the answer is available, it is returned immediately.
Otherwise, the caller of yield/1 is suspended until
the answer arrives from Node.
This is a non-blocking version of yield.
It returns the tuple {value, V} when the computation has
finished, or the atom timeout when Timeout
elapses.
Timeout is either a non-negative integer or the
atom infinity.
Same as nb_yield(Key, 0).
Evaluates the list of size 3 tuples ListOfTuples.
Each tuple must
be of the type {Mod, Fun, Args}. Each tuple is sent
for evaluation
to neighboring nodes, and the replies are collected and returned as
a list of individual values. The return values are presented in the
same order as the original list ListOfTuples.
Takes exactly the same arguments and has the same return value
as the lists:map/3 function, except that everything
is evaluated
in parallel on different nodes.
Location transparent version of process_info/1.
Location transparent version of process_info/2.