erpc(3erl) Erlang Module Definition erpc(3erl)
NAME
erpc - Enhanced Remote Procedure Call
DESCRIPTION
This module provide services similar to Remote Procedure Calls. A re-
mote 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.
This is an enhanced subset of the operations provided by the rpc mod-
ule. Enhanced in the sense that it makes it possible to distinguish be-
tween returned value, raised exceptions, and other errors. erpc also
has better performance and scalability than the original rpc implemen-
tation. However, current rpc module will utilize erpc in order to also
provide these properties when possible.
In order for an erpc operation to succeed, the remote node also needs
to support erpc. Typically only ordinary Erlang nodes as of OTP 23 have
erpc support.
Note that it is up to the user to ensure that correct code to execute
via erpc is available on the involved nodes.
DATA TYPES
request_id()
An opaque type of call request identifiers. For more information
see send_request/4.
EXPORTS
call(Node, Fun) -> Result
call(Node, Fun, Timeout) -> Result
Types:
Node = node()
Fun = function()
Timeout = 0..4294967295 | infinity
Result = term()
The same as calling erpc:call(Node,erlang,apply,[Fun,[]],Time-
out). May raise all the same exceptions as erpc:call/5 plus an
{erpc, badarg} error exception if Fun is not a fun of zero ar-
ity.
The call erpc:call(Node,Fun) is the same as the call
erpc:call(Node,Fun,infinity).
call(Node, Module, Function, Args) -> Result
call(Node, Module, Function, Args, Timeout) -> Result
Types:
Node = node()
Module = Function = atom()
Args = [term()]
Timeout = 0..4294967295 | infinity
Result = term()
Evaluates apply(Module, Function, Args) on node Node and returns
the corresponding value Result. Timeout is an integer represent-
ing the timeout in milliseconds or the atom infinity which pre-
vents the operation from ever timing out.
The call erpc:call(Node, Module, Function, Args) is equivalent
to the call erpc:call(Node, Module, Function, Args, infinity)
The call() function only returns if the applied function suc-
cessfully returned without raising any uncaught exceptions, the
operation did not time out, and no failures occurred. In all
other cases an exception is raised. The following exceptions,
listed by exception class, can currently be raised by
erpc:call():
throw:
The applied function called throw(Value) and did not catch
this exception. The exception reason Value equals the argu-
ment passed to throw/1.
exit:
Exception reason:
{exception, ExitReason}:
The applied function called exit(ExitReason) and did not
catch this exception. The exit reason ExitReason equals
the argument passed to exit/1.
{signal, ExitReason}:
The process that applied the function received an exit
signal and terminated due to this signal. The process ter-
minated with exit reason ExitReason.
error:
Exception reason:
{exception, ErrorReason, StackTrace}:
A runtime error occurred which raised and error exception
while applying the function, and the applied function did
not catch the exception. The error reason ErrorReason in-
dicates the type of error that occurred. StackTrace is
formatted as when caught in a try/catch construct. The
StackTrace is limited to the applied function and func-
tions called by it.
{erpc, ERpcErrorReason}:
The erpc operation failed. The following ERpcErrorReasons
are the most common ones:
badarg:
If any one of these are true:
* Node is not an atom.
* Module is not an atom.
* Function is not an atom.
* Args is not a list. Note that the list is not verified
to be a proper list at the client side.
* Timeout is not the atom infinity or an integer in
valid range.
noconnection:
The connection to Node was lost or could not be estab-
lished. The function may or may not be applied.
system_limit:
The erpc operation failed due to some system limit being
reached. This typically due to failure to create a
process on the remote node Node, but can be other things
as well.
timeout:
The erpc operation timed out. The function may or may
not be applied.
notsup:
The remote node Node does not support this erpc opera-
tion.
If the erpc operation fails, but it is unknown if the function
is/will be applied (that is, a timeout or a connection loss),
the caller will not receive any further information about the
result if/when the applied function completes. If the applied
function explicitly communicates with the calling process, such
communication may, of course, reach the calling process.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be the calling process itself, a
server, or a freshly spawned process.
cast(Node, Fun) -> ok
Types:
Node = node()
Fun = function()
The same as calling erpc:cast(Node,erlang,apply,[Fun,[]]).
erpc:cast/2 fails with an {erpc, badarg} error exception if:
* Node is not an atom.
* Fun is not a a fun of zero arity.
cast(Node, Module, Function, Args) -> ok
Types:
Node = node()
Module = Function = atom()
Args = [term()]
Evaluates apply(Module, Function, Args) on node Node. No re-
sponse is delivered to the calling process. erpc:cast() returns
immediately after the cast request has been sent. Any failures
beside bad arguments are silently ignored.
erpc:cast/4 fails with an {erpc, badarg} error exception if:
* Node is not an atom.
* Module is not an atom.
* Function is not an atom.
* Args is not a list. Note that the list is not verified to be
a proper list at the client side.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be a server, or a freshly spawned
process.
check_response(Message, RequestId) ->
{response, Result} | no_response
Types:
Message = term()
RequestId = request_id()
Result = term()
Check if a message is a response to a call request previously
made by the calling process using erpc:send_request/4. RequestId
should be the value returned from the previously made
erpc:send_request() call, and the corresponding response should
not already have been received and handled to completion by
erpc:check_response(), erpc:receive_response(), or erpc:wait_re-
sponse(). Message is the message to check.
If Message does not correspond to the response, the atom no_re-
sponse is returned. If Message corresponds to the response, the
call operation is completed and either the result is returned as
{response, Result} where Result corresponds to the value re-
turned from the applied function or an exception is raised. The
exceptions that can be raised corresponds to the same exceptions
as can be raised by erpc:call/4. That is, no {erpc, timeout} er-
ror exception can be raised. erpc:check_response() will fail
with an {erpc, badarg} exception if/when an invalid RequestId is
detected.
If the erpc operation fails, but it is unknown if the function
is/will be applied (that is, a connection loss), the caller will
not receive any further information about the result if/when the
applied function completes. If the applied function explicitly
communicates with the calling process, such communication may,
of course, reach the calling process.
multicall(Nodes, Fun) -> Result
multicall(Nodes, Fun, Timeout) -> Result
Types:
Nodes = [atom()]
Fun = function()
Timeout = 0..4294967295 | infinity
Result = term()
The same as calling erpc:multicall(Nodes,erlang,ap-
ply,[Fun,[]],Timeout). May raise all the same exceptions as
erpc:multicall/5 plus an {erpc, badarg} error exception if Fun
is not a fun of zero arity.
The call erpc:multicall(Nodes,Fun) is the same as the call
erpc:multicall(Nodes,Fun, infinity).
multicall(Nodes, Module, Function, Args) -> Result
multicall(Nodes, Module, Function, Args, Timeout) -> Result
Types:
Nodes = [atom()]
Module = Function = atom()
Args = [term()]
Timeout = 0..4294967295 | infinity
Result =
[{ok, ReturnValue :: term()} | caught_call_exception()]
caught_call_exception() =
{throw, Throw :: term()} |
{exit, {exception, Reason :: term()}} |
{error,
{exception, Reason :: term(), StackTrace :: [stack_item()]}} |
{exit, {signal, Reason :: term()}} |
{error, {erpc, Reason :: term()}}
stack_item() =
{Module :: atom(),
Function :: atom(),
Arity :: arity() | (Args :: [term()]),
Location ::
[{file, Filename :: string()} |
{line, Line :: integer() >= 1}]}
Performs multiple call operations in parallel on multiple nodes.
That is, evaluates apply(Module, Function, Args) on the nodes
Nodes in parallel. Timeout is an integer representing the time-
out in milliseconds or the atom infinity which prevents the op-
eration from ever timing out. The result is returned as a list
where the result from each node is placed at the same position
as the node name is placed in Nodes. Each item in the resulting
list is formatted as either:
{ok, Result}:
The call operation for this specific node returned Result.
{Class, ExceptionReason}:
The call operation for this specific node raised an excep-
tion of class Class with exception reason ExceptionReason.
These corresponds the the exceptions that erpc:call/5 can
raise.
erpc:multicall/5 fails with an {erpc, badarg} error exception
if:
* Nodes is not a proper list of atoms. Note that some requests
may already have been sent when the failure occurs. That is,
the function may or may not be applied on some nodes.
* Module is not an atom.
* Function is not an atom.
* Args is not a list. Note that the list is not verified to be
a proper list at the client side.
The call erpc:multicall(Nodes, Module, Function, Args) is equiv-
alent to the call erpc:multicall(Nodes, Module, Function, Args,
infinity). These calls are also equivalent to calling my_multi-
call(Nodes, Module, Function, Args) if one disregard performance
and failure behavior:
my_multicall(Nodes, Module, Function, Args) ->
ReqIds = lists:map(fun (Node) ->
erpc:send_request(Node, Module, Function, Args)
end,
Nodes),
lists:map(fun (ReqId) ->
try
{ok, erpc:receive_response(ReqId, infinity)}
catch
Class:Reason ->
{Class, Reason}
end
end,
ReqIds).
The Timeout value in milliseconds sets an upper time limit for
all call operations to complete.
If an erpc operation fails, but it is unknown if the function
is/will be applied (that is, a timeout, connection loss, or an
improper Nodes list), the caller will not receive any further
information about the result if/when the applied function com-
pletes. If the applied function communicates with the calling
process, such communication may, of course, reach the calling
process.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be the calling process itself, a
server, or a freshly spawned process.
multicast(Nodes, Fun) -> ok
Types:
Nodes = [node()]
Fun = function()
The same as calling erpc:multicast(Nodes,erlang,apply,[Fun,[]]).
erpc:multicast/2 fails with an {erpc, badarg} error exception
if:
* Nodes is not a proper list of atoms.
* Fun is not a a fun of zero arity.
multicast(Nodes, Module, Function, Args) -> ok
Types:
Nodes = [node()]
Module = Function = atom()
Args = [term()]
Evaluates apply(Module, Function, Args) on the nodes Nodes. No
response is delivered to the calling process. erpc:multicast()
returns immediately after the cast requests have been sent. Any
failures beside bad arguments are silently ignored.
erpc:multicast/4 fails with an {erpc, badarg} error exception
if:
* Nodes is not a proper list of atoms. Note that some requests
may already have been sent when the failure occurs. That is,
the function may or may not be applied on some nodes.
* Module is not an atom.
* Function is not an atom.
* Args is not a list. Note that the list is not verified to be
a proper list at the client side.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be a server, or a freshly spawned
process.
receive_response(RequestId) -> Result
receive_response(RequestId, Timeout) -> Result
Types:
RequestId = request_id()
Timeout = 0..4294967295 | infinity
Result = term()
Receive a response to a call request previously made by the
calling process using erpc:send_request/4. RequestId should be
the value returned from the previously made erpc:send_request()
call, and the corresponding response should not already have
been received and handled to completion by erpc:check_re-
sponse(), erpc:receive_response(), or erpc:wait_response().
Timeout is an integer representing the timeout in milliseconds
or the atom infinity which prevents the operation from ever tim-
ing out. The call operation is completed once the erpc:re-
ceive_response() call returns or raise an exception.
The call erpc:receive_response(RequestId) is equivalent to the
call erpc:receive_response(RequestId, infinity).
A call to the function my_call(Node, Module, Function, Args,
Timeout) below is equivalent to the call erpc:call(Node, Module,
Function, Args, Timeout) if one disregards performance.
erpc:call() can utilize a message queue optimization which re-
moves the need to scan the whole message queue which the combi-
nation erpc:send_request()/erpc:receive_response() cannot.
my_call(Node, Module, Function, Args, Timeout) ->
RequestId = erpc:send_request(Node, Module, Function, Args),
erpc:receive_response(RequestId, Timeout).
If the erpc operation fails, but it is unknown if the function
is/will be applied (that is, a timeout, or a connection loss),
the caller will not receive any further information about the
result if/when the applied function completes. If the applied
function explicitly communicates with the calling process, such
communication may, of course, reach the calling process.
erpc:receive_response() will return or raise exceptions the same
way as erpc:call/5 does with the exception of {erpc, badarg}. An
{erpc, badarg} exception will be raised if/when an invalid Re-
questId is detected or if an invalid Timeout is passed.
send_request(Node, Fun) -> RequestId
Types:
Node = node()
Fun = function()
RequestId = request_id()
The same as calling erpc:send_request(Node,erlang,ap-
ply,[Fun,[]]).
erpc:send_request/2 fails with an {erpc, badarg} error exception
if:
* Node is not an atom.
* Fun is not a fun of zero arity.
Note:
You cannot make any assumptions about the process that will per-
form the apply(). It may be a server, or a freshly spawned
process.
send_request(Node, Module, Function, Args) -> RequestId
Types:
Node = node()
Module = Function = atom()
Args = [term()]
RequestId = request_id()
Send an asynchronous call request to the node Node.
erpc:send_request() returns a request identifier that later is
to be passed as argument to either erpc:receive_response(),
erpc:wait_response(), or, erpc:check_response() in order to get
the response of the call request.
erpc:send_request() fails with an {erpc, badarg} error exception
if:
* Node is not an atom.
* Module is not an atom.
* Function is not an atom.
* Args is not a list. Note that the list is not verified to be
a proper list at the client side.
wait_response(RequestId) -> {response, Result} | no_response
wait_response(RequestId, WaitTime) ->
{response, Result} | no_response
Types:
RequestId = request_id()
WaitTime = 0..4294967295 | infinity
Result = term()
Wait or poll for a response message to a call request previously
made by the calling process using erpc:send_request/4. RequestId
should be the value returned from the previously made
erpc:send_request() call, and the corresponding response should
not already have been received and handled to completion by
erpc:check_response(), erpc:receive_response(), or erpc:wait_re-
sponse(). WaitTime equals the time to wait in milliseconds (or
the atom infinity) during the wait. WaitTime is an integer rep-
resenting time to wait in milliseconds or the atom infinity
which will cause wait_response/2 to wait for a response until it
appears regardless of how long time that is.
The call erpc:wait_response(RequestId) is equivalent to the call
erpc:wait_response(RequestId, 0). That is, poll for a response
message to a call request previously made by the calling
process.
If no response is received before WaitTime milliseconds, the
atom no_response is returned. It is valid to continue waiting
for a response as many times as needed up until a response has
been received and completed by erpc:check_response(), erpc:re-
ceive_response(), or erpc:wait_response(). If a response is re-
ceived, the call operation is completed and either the result is
returned as {response, Result} where Result corresponds to the
value returned from the applied function or an exception is
raised. The exceptions that can be raised corresponds to the
same exceptions as can be raised by erpc:call/4. That is, no
{erpc, timeout} error exception can be raised. erpc:wait_re-
sponse() will fail with an {erpc, badarg} exception if/when an
invalid RequestId is detected or if an invalid WaitTime is
passed.
If the erpc operation fails, but it is unknown if the function
is/will be applied (that is, a too large wait time value, or a
connection loss), the caller will not receive any further infor-
mation about the result if/when the applied function completes.
If the applied function explicitly communicates with the calling
process, such communication may, of course, reach the calling
process.
Ericsson AB kernel 7.0 erpc(3erl)