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.

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, for example, is used by the call/4 function to interact with the rpc server at a remote node. 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.

multicall(M, F, A)

    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.

multicall(Nodes, M, F, A)

    Executes the multicall only on the nodes Nodes.

multi_server_call(Name, Msg)

    This function is used by the multicall/3 function when it interacts with the rpc server. The function can, of course, also be used for interacting with other servers.

    The function sends Msg to Name on all nodes, and collects the answers. It returns .br {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 .br From ! {Name, node(), Reply}.

    The function also hangs if any one of the servers involved crash, or do not exist, during the call. This function, then, assumes that the servers are stable. If any of the nodes involved crash, the function still works and the crashed node appears in the Badnodes list of the return value.

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

    This is a non-blocking version of yield. It returns either the atom timeout, or the tuple {value, V}, if the computation is finished.

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 -  klacke@erix.ericsson.se