rpc(3erl)
NAME
rpc - Remote Procedure Call services.
DESCRIPTION
This module contains services 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.
DATA TYPES
key()
As returned by async_call/4.
EXPORTS
abcast(Name, Msg) -> abcast
Types:
Name = atom()
Msg = term()
Equivalent to abcast([node()|nodes()], Name, Msg).
abcast(Nodes, Name, Msg) -> abcast
Types:
Nodes = [node()]
Name = atom()
Msg = term()
Broadcasts the message Msg asynchronously to the registered
process Name on the specified nodes.
async_call(Node, Module, Function, Args) -> Key
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Key = key()
Implements call streams with promises, a type of RPC that does
not suspend the caller until the result is finished. Instead, a
key is returned, which can be used later to collect the value.
The key can be viewed as a promise to deliver the answer.
In this case, the key Key is returned, which can be used in a
subsequent call to yield/1 or nb_yield/1,2 to retrieve the value
of evaluating apply(Module, Function, Args) on node Node.
block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Same as call/4, but the RPC server at Node 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.
block_call(Node, Module, Function, Args, Timeout) ->
Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = timeout()
Same as block_call/4, but with a time-out value in the same
manner as call/5.
call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Evaluates apply(Module, Function, Args) on node Node and returns
the corresponding value Res, or {badrpc, Reason} if the call
fails.
call(Node, Module, Function, Args, Timeout) ->
Res | {badrpc, Reason}
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = timeout()
Evaluates apply(Module, Function, Args) on node Node and returns
the corresponding value Res, or {badrpc, Reason} if the call
fails. Timeout is a time-out value in milliseconds. If the call
times out, Reason is timeout.
If the reply arrives after the call times out, no message
contaminates the caller's message queue, as 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) -> true
Types:
Node = node()
Module = module()
Function = atom()
Args = [term()]
Evaluates apply(Module, Function, Args) on node Node. No
response is delivered and the calling process is not suspended
until the evaluation is complete, as is the case with call/4,5.
eval_everywhere(Module, Function, Args) -> abcast
Types:
Module = module()
Function = atom()
Args = [term()]
Equivalent to eval_everywhere([node()|nodes()], Module,
Function, Args).
eval_everywhere(Nodes, Module, Function, Args) -> abcast
Types:
Nodes = [node()]
Module = module()
Function = atom()
Args = [term()]
Evaluates apply(Module, Function, Args) on the specified nodes.
No answers are collected.
multi_server_call(Name, Msg) -> {Replies, BadNodes}
Types:
Name = atom()
Msg = term()
Replies = [Reply :: term()]
BadNodes = [node()]
Equivalent to multi_server_call([node()|nodes()], Name, Msg).
multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
Types:
Nodes = [node()]
Name = atom()
Msg = term()
Replies = [Reply :: term()]
BadNodes = [node()]
Can be used when interacting with servers called Name on the
specified nodes. It is assumed that the servers receive messages
in the format {From, Msg} and reply using From ! {Name, Node,
Reply}, where Node is the name of the node where the server is
located. The function returns {Replies, BadNodes}, where Replies
is a list of all Reply values, and BadNodes is one of the
following:
* A list of the nodes that do not exist
* A list of the nodes where the server does not exist
* A list of the nodes where the server terminatd before
sending any reply.
multicall(Module, Function, Args) -> {ResL, BadNodes}
Types:
Module = module()
Function = atom()
Args = ResL = [term()]
BadNodes = [node()]
Equivalent to multicall([node()|nodes()], Module, Function,
Args, infinity).
multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
Types:
Nodes = [node()]
Module = module()
Function = atom()
Args = ResL = [term()]
BadNodes = [node()]
Equivalent to multicall(Nodes, Module, Function, Args,
infinity).
multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
Types:
Module = module()
Function = atom()
Args = [term()]
Timeout = timeout()
ResL = [term()]
BadNodes = [node()]
Equivalent to multicall([node()|nodes()], Module, Function,
Args, Timeout).
multicall(Nodes, Module, Function, Args, Timeout) ->
{ResL, BadNodes}
Types:
Nodes = [node()]
Module = module()
Function = atom()
Args = [term()]
Timeout = timeout()
ResL = [term()]
BadNodes = [node()]
In contrast to an RPC, a multicall is an RPC that is sent
concurrently from one client to multiple servers. This is useful
for collecting 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 evaluates apply(Module, Function, Args) on the
specified nodes and collects the answers. It returns {ResL,
BadNodes}, where BadNodes is a list of the nodes that terminated
or timed out during computation, and ResL 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 indicates some side
effects that RPCs can produce:
%% 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.
nb_yield(Key) -> {value, Val} | timeout
Types:
Key = key()
Val = (Res :: term()) | {badrpc, Reason :: term()}
Equivalent to nb_yield(Key, 0).
nb_yield(Key, Timeout) -> {value, Val} | timeout
Types:
Key = key()
Timeout = timeout()
Val = (Res :: term()) | {badrpc, Reason :: term()}
Non-blocking version of yield/1. It returns the tuple {value,
Val} when the computation is finished, or timeout when Timeout
milliseconds has elapsed.
parallel_eval(FuncCalls) -> ResL
Types:
FuncCalls = [{Module, Function, Args}]
Module = module()
Function = atom()
Args = ResL = [term()]
Evaluates, for every tuple in FuncCalls, apply(Module, Function,
Args) on some node in the network. Returns the list of return
values, in the same order as in FuncCalls.
pinfo(Pid) -> [{Item, Info}] | undefined
Types:
Pid = pid()
Item = atom()
Info = term()
Location transparent version of the BIF erlang:process_info/1 in
ERTS.
pinfo(Pid, Item) -> {Item, Info} | undefined | []
pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
Types:
Pid = pid()
Item = atom()
ItemList = [Item]
Info = term()
Location transparent version of the BIF erlang:process_info/2 in
ERTS.
pmap(FuncSpec, ExtraArgs, List1) -> List2
Types:
FuncSpec = {Module, Function}
Module = module()
Function = atom()
ExtraArgs = [term()]
List1 = [Elem :: term()]
List2 = [term()]
Evaluates apply(Module, Function, [Elem|ExtraArgs]) for every
element Elem in List1, in parallel. Returns the list of return
values, in the same order as in List1.
sbcast(Name, Msg) -> {GoodNodes, BadNodes}
Types:
Name = atom()
Msg = term()
GoodNodes = BadNodes = [node()]
Equivalent to sbcast([node()|nodes()], Name, Msg).
sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
Types:
Name = atom()
Msg = term()
Nodes = GoodNodes = BadNodes = [node()]
Broadcasts the message Msg synchronously to the registered
process Name on the specified nodes.
Returns {GoodNodes, BadNodes}, where GoodNodes is the list of
nodes that have Name as a registered process.
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 processed the
message.
Any further messages sent to the servers, after this function
has returned, are received by all servers after this message.
server_call(Node, Name, ReplyWrapper, Msg) ->
Reply | {error, Reason}
Types:
Node = node()
Name = atom()
ReplyWrapper = Msg = Reply = term()
Reason = nodedown
Can be used when interacting with a server called Name on node
Node. It is assumed that the server receives messages in the
format {From, Msg} and replies using 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 the answer Reply as produced by the server
Name, or {error, Reason}.
yield(Key) -> Res | {badrpc, Reason}
Types:
Key = key()
Res = Reason = term()
Returns the promised answer from a previous async_call/4. If the
answer is available, it is returned immediately. Otherwise, the
calling process is suspended until the answer arrives from Node.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
