rpc(3)

MODULE
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.

EXPORTS

start()

    Starts the rpc server. Normally, this is not necessary because the rpc server is started automatically.

stop()

    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.

call(Node, Module, Function, Args, Timeout)

    Evaluates apply(Mod, Fun, Args) on the node Node and returns a value, or {badrpc, Reason} if the call fails. 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.

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.

block_call(Node, Module, Function, Args, Timeout)

    See call/4 and block_call/4. This is a combination of both. Returns a value, or {badrpc, Reason} if the call fails. If the call times out, Reason is timeout.

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.

abcast(Name, Mess)

    Broadcasts the message Mess asynchronously to the registered process Name on all nodes, including the current node.

abcast(Nodes, Name, Mess)

    The same as abcast/2, but only to the nodes Nodes.

sbcast(Name, Msg)

    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 .

sbcast(Nodes, Name, Msg)

    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. No answers are collected.

multicall(M, F, A)

    The same as multicall(M, F, A, infinity)

multicall(Nodes, M, F, A)

    The same as multicall(Nodes, M, F, A, infinity), where Nodes is a list of nodes.

multicall(M, F, A, Timeout)

    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 or timed out during computation, and Replies 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
    {Replies, _} = rpc:multicall(code, load_binary, [Mod, Bin, File,]),
    %% and then maybe check the Replies list.

multicall(Nodes, M, F, A, Timeout)

    Executes the multicall with timeout, but only on the nodes Nodes.

multi_server_call(Name, Msg)

    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.

  Warning:

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).

yield(Key)

    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.

nb_yield(Key, Timeout)

    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.

nb_yield(Key)

    Same as nb_yield(Key, 0).

parallel_eval(ListOfTuples)

    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.

pmap({M, F}, Extraargs, List)

    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.

pinfo(Pid)

    Location transparent version of process_info/1.

pinfo(Pid, Item)

    Location transparent version of process_info/2.

AUTHOR
 Claes Wikstrom - support@erlang.ericsson.se