.TH rpc 3erl "kernel 3.0.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
rpc \- Remote Procedure Call Services
.SH DESCRIPTION
.LP
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\&.
.SH DATA TYPES
.nf

\fBkey()\fR\&
.br
.fi
.RS
.LP
As returned by \fB\fIasync_call/4\fR\&\&.\fR\&
.RE

.SH EXPORTS
.LP
.nf

.B
call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Res = Reason = term()
.br
.RE
.RE
.RS
.LP
Evaluates \fIapply(Module, Function, Args)\fR\& on the node \fINode\fR\& and returns the corresponding value \fIRes\fR\&, or \fI{badrpc, Reason}\fR\& if the call fails\&.
.RE

.LP
.nf

.B
call(Node, Module, Function, Args, Timeout) ->
.B
        Res | {badrpc, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Res = Reason = term()
.br
Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Evaluates \fIapply(Module, Function, Args)\fR\& on the node \fINode\fR\& and returns the corresponding value \fIRes\fR\&, or \fI{badrpc, Reason}\fR\& if the call fails\&. \fITimeout\fR\& is a timeout value in milliseconds\&. If the call times out, \fIReason\fR\& is \fItimeout\fR\&\&.
.LP
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 \fIcall/4\fR\& at the caller\&'s end\&.
.RE

.LP
.nf

.B
block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Res = Reason = term()
.br
.RE
.RE
.RS
.LP
Like \fIcall/4\fR\&, but the RPC server at \fINode\fR\& 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\&.
.RE

.LP
.nf

.B
block_call(Node, Module, Function, Args, Timeout) ->
.B
              Res | {badrpc, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Res = Reason = term()
.br
Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Like \fIblock_call/4\fR\&, but with a timeout value in the same manner as \fIcall/5\fR\&\&.
.RE

.LP
.nf

.B
async_call(Node, Module, Function, Args) -> Key
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Key = \fBkey()\fR\&
.br
.RE
.RE
.RS
.LP
Implements \fIcall streams with promises\fR\&, a type of RPC which does not suspend the caller until the result is finished\&. Instead, a key is returned which can be used at a later stage to collect the value\&. The key can be viewed as a promise to deliver the answer\&.
.LP
In this case, the key \fIKey\fR\& is returned, which can be used in a subsequent call to \fIyield/1\fR\& or \fInb_yield/1,2\fR\& to retrieve the value of evaluating \fIapply(Module, Function, Args)\fR\& on the node \fINode\fR\&\&.
.RE

.LP
.nf

.B
yield(Key) -> Res | {badrpc, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Key = \fBkey()\fR\&
.br
Res = Reason = term()
.br
.RE
.RE
.RS
.LP
Returns the promised answer from a previous \fIasync_call/4\fR\&\&. If the answer is available, it is returned immediately\&. Otherwise, the calling process is suspended until the answer arrives from \fINode\fR\&\&.
.RE

.LP
.nf

.B
nb_yield(Key) -> {value, Val} | timeout
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Key = \fBkey()\fR\&
.br
Val = (Res :: term()) | {badrpc, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Equivalent to \fInb_yield(Key, 0)\fR\&\&.
.RE

.LP
.nf

.B
nb_yield(Key, Timeout) -> {value, Val} | timeout
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Key = \fBkey()\fR\&
.br
Timeout = timeout()
.br
Val = (Res :: term()) | {badrpc, Reason :: term()}
.br
.RE
.RE
.RS
.LP
This is a non-blocking version of \fIyield/1\fR\&\&. It returns the tuple \fI{value, Val}\fR\& when the computation has finished, or \fItimeout\fR\& when \fITimeout\fR\& milliseconds has elapsed\&.
.RE

.LP
.nf

.B
multicall(Module, Function, Args) -> {ResL, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Module = module()
.br
Function = atom()
.br
Args = ResL = [term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
Equivalent to \fImulticall([node()|nodes()], Module, Function, Args, infinity)\fR\&\&.
.RE

.LP
.nf

.B
multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
Module = module()
.br
Function = atom()
.br
Args = ResL = [term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
Equivalent to \fImulticall(Nodes, Module, Function, Args, infinity)\fR\&\&.
.RE

.LP
.nf

.B
multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Timeout = timeout()
.br
ResL = [term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
Equivalent to \fImulticall([node()|nodes()], Module, Function, Args, Timeout)\fR\&\&.
.RE

.LP
.nf

.B
multicall(Nodes, Module, Function, Args, Timeout) ->
.B
             {ResL, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Timeout = timeout()
.br
ResL = [term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
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\&.
.LP
The function evaluates \fIapply(Module, Function, Args)\fR\& on the specified nodes and collects the answers\&. It returns \fI{ResL, BadNodes}\fR\&, where \fIBadNodes\fR\& is a list of the nodes that terminated or timed out during computation, and \fIResL\fR\& is a list of the return values\&. \fITimeout\fR\& is a time (integer) in milliseconds, or \fIinfinity\fR\&\&.
.LP
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:
.LP
.nf

%% 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.
.fi
.RE

.LP
.nf

.B
cast(Node, Module, Function, Args) -> true
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
.RE
.RE
.RS
.LP
Evaluates \fIapply(Module, Function, Args)\fR\& on the node \fINode\fR\&\&. No response is delivered and the calling process is not suspended until the evaluation is complete, as is the case with \fIcall/4,5\fR\&\&.
.RE

.LP
.nf

.B
eval_everywhere(Module, Function, Args) -> abcast
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
.RE
.RE
.RS
.LP
Equivalent to \fIeval_everywhere([node()|nodes()], Module, Function, Args)\fR\&\&.
.RE

.LP
.nf

.B
eval_everywhere(Nodes, Module, Function, Args) -> abcast
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
.RE
.RE
.RS
.LP
Evaluates \fIapply(Module, Function, Args)\fR\& on the specified nodes\&. No answers are collected\&.
.RE

.LP
.nf

.B
abcast(Name, Msg) -> abcast
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Msg = term()
.br
.RE
.RE
.RS
.LP
Equivalent to \fIabcast([node()|nodes()], Name, Msg)\fR\&\&.
.RE

.LP
.nf

.B
abcast(Nodes, Name, Msg) -> abcast
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
Name = atom()
.br
Msg = term()
.br
.RE
.RE
.RS
.LP
Broadcasts the message \fIMsg\fR\& asynchronously to the registered process \fIName\fR\& on the specified nodes\&.
.RE

.LP
.nf

.B
sbcast(Name, Msg) -> {GoodNodes, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Msg = term()
.br
GoodNodes = BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
Equivalent to \fIsbcast([node()|nodes()], Name, Msg)\fR\&\&.
.RE

.LP
.nf

.B
sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Msg = term()
.br
Nodes = GoodNodes = BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
Broadcasts the message \fIMsg\fR\& synchronously to the registered process \fIName\fR\& on the specified nodes\&.
.LP
Returns \fI{GoodNodes, BadNodes}\fR\&, where \fIGoodNodes\fR\& is the list of nodes which have \fIName\fR\& as a registered process\&.
.LP
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 actually processed the message\&.
.LP
Any further messages sent to the servers, after this function has returned, will be received by all servers after this message\&.
.RE

.LP
.nf

.B
server_call(Node, Name, ReplyWrapper, Msg) ->
.B
               Reply | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
Name = atom()
.br
ReplyWrapper = Msg = Reply = term()
.br
Reason = nodedown
.br
.RE
.RE
.RS
.LP
This function can be used when interacting with a server called \fIName\fR\& at node \fINode\fR\&\&. It is assumed that the server receives messages in the format \fI{From, Msg}\fR\& and replies using \fIFrom ! {ReplyWrapper, Node, Reply}\fR\&\&. 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\&.
.LP
The function returns the answer \fIReply\fR\& as produced by the server \fIName\fR\&, or \fI{error, Reason}\fR\&\&.
.RE

.LP
.nf

.B
multi_server_call(Name, Msg) -> {Replies, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Msg = term()
.br
Replies = [Reply :: term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
Equivalent to \fImulti_server_call([node()|nodes()], Name, Msg)\fR\&\&.
.RE

.LP
.nf

.B
multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
Name = atom()
.br
Msg = term()
.br
Replies = [Reply :: term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP
This function can be used when interacting with servers called \fIName\fR\& on the specified nodes\&. It is assumed that the servers receive messages in the format \fI{From, Msg}\fR\& and reply using \fIFrom ! {Name, Node, Reply}\fR\&, where \fINode\fR\& is the name of the node where the server is located\&. The function returns \fI{Replies, BadNodes}\fR\&, where \fIReplies\fR\& is a list of all \fIReply\fR\& values and \fIBadNodes\fR\& is a list of the nodes which did not exist, or where the server did not exist, or where the server terminated before sending any reply\&.
.RE

.LP
.nf

.B
safe_multi_server_call(Name, Msg) -> {Replies, BadNodes}
.br
.fi
.br
.nf

.B
safe_multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
Name = atom()
.br
Msg = term()
.br
Replies = [Reply :: term()]
.br
BadNodes = [node()]
.br
.RE
.RE
.RS
.LP

.RS -4
.B
Warning:
.RE
This function is deprecated\&. Use \fImulti_server_call/2,3\fR\& instead\&.

.LP
In Erlang/OTP R6B and earlier releases, \fImulti_server_call/2,3\fR\& could not handle the case where the remote node exists, but there is no server called \fIName\fR\&\&. Instead this function had to be used\&. In Erlang/OTP R7B and later releases, however, the functions are equivalent, except for this function being slightly slower\&.
.RE

.LP
.nf

.B
parallel_eval(FuncCalls) -> ResL
.br
.fi
.br
.RS
.LP
Types:

.RS 3
FuncCalls = [{Module, Function, Args}]
.br
Module = module()
.br
Function = atom()
.br
Args = ResL = [term()]
.br
.RE
.RE
.RS
.LP
For every tuple in \fIFuncCalls\fR\&, evaluates \fIapply(Module, Function, Args)\fR\& on some node in the network\&. Returns the list of return values, in the same order as in \fIFuncCalls\fR\&\&.
.RE

.LP
.nf

.B
pmap(FuncSpec, ExtraArgs, List1) -> List2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
FuncSpec = {Module, Function}
.br
Module = module()
.br
Function = atom()
.br
ExtraArgs = [term()]
.br
List1 = [Elem :: term()]
.br
List2 = [term()]
.br
.RE
.RE
.RS
.LP
Evaluates \fIapply(Module, Function, [Elem|ExtraArgs])\fR\&, for every element \fIElem\fR\& in \fIList1\fR\&, in parallel\&. Returns the list of return values, in the same order as in \fIList1\fR\&\&.
.RE

.LP
.nf

.B
pinfo(Pid) -> [{Item, Info}] | undefined
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Pid = pid()
.br
Item = atom()
.br
Info = term()
.br
.RE
.RE
.RS
.LP
Location transparent version of the BIF \fB\fIprocess_info/1\fR\&\fR\&\&.
.RE

.LP
.nf

.B
pinfo(Pid, Item) -> {Item, Info} | undefined | []
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Pid = pid()
.br
Item = atom()
.br
Info = term()
.br
.RE
.RE
.RS
.LP
Location transparent version of the BIF \fB\fIprocess_info/2\fR\&\fR\&\&.
.RE