# rpc

### MODULE

rpc

### MODULE SUMMARY

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.

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

### AUTHORS

Claes Wikstrom - support@erlang.ericsson.se

kernel 2.10.4
Copyright © 1991-2005 Ericsson AB