1erpc(3) Erlang Module Definition erpc(3)
2
6 erpc - Enhanced Remote Procedure Call
7
9 This module provide services similar to Remote Procedure Calls. A
10 remote procedure call is a method to call a function on a remote node
11 and collect the answer. It is used for collecting information on a
12 remote node, or for running a function with some specific side effects
13 on the remote node.
14 This is an enhanced subset of the operations provided by the rpc mod‐
16 ule. Enhanced in the sense that it makes it possible to distinguish
17 between returned value, raised exceptions, and other errors. erpc also
18 has better performance and scalability than the original rpc implemen‐
19 tation. However, current rpc module will utilize erpc in order to also
20 provide these properties when possible.
21 In order for an erpc operation to succeed, the remote node also needs
23 to support erpc. Typically only ordinary Erlang nodes as of OTP 23 have
24 erpc support.
25 Note that it is up to the user to ensure that correct code to execute
27 via erpc is available on the involved nodes.
28
30 request_id()
31 An opaque type of call request identifiers. For more information
33 see send_request/4.
34
36 call(Node, Fun) -> Result
37 call(Node, Fun, Timeout) -> Result
39 Types:
41 Node = node()
43 Fun = function()
44 Timeout = 0..4294967295 | infinity
45 Result = term()
46 The same as calling erpc:call(Node,erlang,apply,[Fun,[]],Time‐
48 out). May raise all the same exceptions as erpc:call/5 plus an
49 {erpc, badarg} error exception if Fun is not a fun of zero
50 arity.
51 The call erpc:call(Node,Fun) is the same as the call
53 erpc:call(Node,Fun,infinity).
54 call(Node, Module, Function, Args) -> Result
56 call(Node, Module, Function, Args, Timeout) -> Result
58 Types:
60 Node = node()
62 Module = Function = atom()
63 Args = [term()]
64 Timeout = 0..4294967295 | infinity
65 Result = term()
66 Evaluates apply(Module, Function, Args) on node Node and returns
68 the corresponding value Result. Timeout is an integer represent‐
69 ing the timeout in milliseconds or the atom infinity which pre‐
70 vents the operation from ever timing out.
71 The call erpc:call(Node, Module, Function, Args) is equivalent
73 to the call erpc:call(Node, Module, Function, Args, infinity)
74 The call() function only returns if the applied function suc‐
76 cessfully returned without raising any uncaught exceptions, the
77 operation did not time out, and no failures occurred. In all
78 other cases an exception is raised. The following exceptions,
79 listed by exception class, can currently be raised by
80 erpc:call():
81 throw:
83 The applied function called throw(Value) and did not catch
84 this exception. The exception reason Value equals the argu‐
85 ment passed to throw/1.
86 exit:
88 Exception reason:
89 {exception, ExitReason}:
91 The applied function called exit(ExitReason) and did not
92 catch this exception. The exit reason ExitReason equals
93 the argument passed to exit/1.
94 {signal, ExitReason}:
96 The process that applied the function received an exit
97 signal and terminated due to this signal. The process ter‐
98 minated with exit reason ExitReason.
99 error:
101 Exception reason:
102 {exception, ErrorReason, StackTrace}:
104 A runtime error occurred which raised and error exception
105 while applying the function, and the applied function did
106 not catch the exception. The error reason ErrorReason
107 indicates the type of error that occurred. StackTrace is
108 formatted as when caught in a try/catch construct. The
109 StackTrace is limited to the applied function and func‐
110 tions called by it.
111 {erpc, ERpcErrorReason}:
113 The erpc operation failed. The following ERpcErrorReasons
114 are the most common ones:
115 badarg:
117 If any one of these are true:
118 * Node is not an atom.
120 * Module is not an atom.
122 * Function is not an atom.
124 * Args is not a list. Note that the list is not verified
126 to be a proper list at the client side.
127 * Timeout is not the atom infinity or an integer in
129 valid range.
130 noconnection:
132 The connection to Node was lost or could not be estab‐
133 lished. The function may or may not be applied.
134 system_limit:
136 The erpc operation failed due to some system limit being
137 reached. This typically due to failure to create a
138 process on the remote node Node, but can be other things
139 as well.
140 timeout:
142 The erpc operation timed out. The function may or may
143 not be applied.
144 notsup:
146 The remote node Node does not support this erpc opera‐
147 tion.
148 If the erpc operation fails, but it is unknown if the function
150 is/will be applied (that is, a timeout or a connection loss),
151 the caller will not receive any further information about the
152 result if/when the applied function completes. If the applied
153 function explicitly communicates with the calling process, such
154 communication may, of course, reach the calling process.
155 Note:
157 You cannot make any assumptions about the process that will per‐
158 form the apply(). It may be the calling process itself, a
159 server, or a freshly spawned process.
160 cast(Node, Fun) -> ok
163 Types:
165 Node = node()
167 Fun = function()
168 The same as calling erpc:cast(Node,erlang,apply,[Fun,[]]).
170 erpc:cast/2 fails with an {erpc, badarg} error exception if:
172 * Node is not an atom.
174 * Fun is not a a fun of zero arity.
176 cast(Node, Module, Function, Args) -> ok
178 Types:
180 Node = node()
182 Module = Function = atom()
183 Args = [term()]
184 Evaluates apply(Module, Function, Args) on node Node. No
186 response is delivered to the calling process. erpc:cast()
187 returns immediately after the cast request has been sent. Any
188 failures beside bad arguments are silently ignored.
189 erpc:cast/4 fails with an {erpc, badarg} error exception if:
191 * Node is not an atom.
193 * Module is not an atom.
195 * Function is not an atom.
197 * Args is not a list. Note that the list is not verified to be
199 a proper list at the client side.
200 Note:
202 You cannot make any assumptions about the process that will per‐
203 form the apply(). It may be a server, or a freshly spawned
204 process.
205 check_response(Message, RequestId) ->
208 {response, Result} | no_response
209 Types:
211 Message = term()
213 RequestId = request_id()
214 Result = term()
215 Check if a message is a response to a call request previously
217 made by the calling process using erpc:send_request/4. RequestId
218 should be the value returned from the previously made
219 erpc:send_request() call, and the corresponding response should
220 not already have been received and handled to completion by
221 erpc:check_response(), erpc:receive_response(), or
222 erpc:wait_response(). Message is the message to check.
223 If Message does not correspond to the response, the atom
225 no_response is returned. If Message corresponds to the response,
226 the call operation is completed and either the result is
227 returned as {response, Result} where Result corresponds to the
228 value returned from the applied function or an exception is
229 raised. The exceptions that can be raised corresponds to the
230 same exceptions as can be raised by erpc:call/4. That is, no
231 {erpc, timeout} error exception can be raised.
232 erpc:check_response() will fail with an {erpc, badarg} exception
233 if/when an invalid RequestId is detected.
234 If the erpc operation fails, but it is unknown if the function
236 is/will be applied (that is, a connection loss), the caller will
237 not receive any further information about the result if/when the
238 applied function completes. If the applied function explicitly
239 communicates with the calling process, such communication may,
240 of course, reach the calling process.
241 multicall(Nodes, Fun) -> Result
243 multicall(Nodes, Fun, Timeout) -> Result
245 Types:
247 Nodes = [atom()]
249 Fun = function()
250 Timeout = 0..4294967295 | infinity
251 Result = term()
252 The same as calling erpc:multi‐
254 call(Nodes,erlang,apply,[Fun,[]],Timeout). May raise all the
255 same exceptions as erpc:multicall/5 plus an {erpc, badarg} error
256 exception if Fun is not a fun of zero arity.
257 The call erpc:multicall(Nodes,Fun) is the same as the call
259 erpc:multicall(Nodes,Fun, infinity).
260 multicall(Nodes, Module, Function, Args) -> Result
262 multicall(Nodes, Module, Function, Args, Timeout) -> Result
264 Types:
266 Nodes = [atom()]
268 Module = Function = atom()
269 Args = [term()]
270 Timeout = 0..4294967295 | infinity
271 Result =
272 [{ok, ReturnValue :: term()} | caught_call_exception()]
273 caught_call_exception() =
274 {throw, Throw :: term()} |
275 {exit, {exception, Reason :: term()}} |
276 {error,
277 {exception, Reason :: term(), StackTrace :: [stack_item()]}} |
278 {exit, {signal, Reason :: term()}} |
279 {error, {erpc, Reason :: term()}}
280 stack_item() =
281 {Module :: atom(),
282 Function :: atom(),
283 Arity :: arity() | (Args :: [term()]),
284 Location ::
285 [{file, Filename :: string()} |
286 {line, Line :: integer() >= 1}]}
287 Performs multiple call operations in parallel on multiple nodes.
289 That is, evaluates apply(Module, Function, Args) on the nodes
290 Nodes in parallel. Timeout is an integer representing the time‐
291 out in milliseconds or the atom infinity which prevents the
292 operation from ever timing out. The result is returned as a list
293 where the result from each node is placed at the same position
294 as the node name is placed in Nodes. Each item in the resulting
295 list is formatted as either:
296 {ok, Result}:
298 The call operation for this specific node returned Result.
299 {Class, ExceptionReason}:
301 The call operation for this specific node raised an excep‐
302 tion of class Class with exception reason ExceptionReason.
303 These corresponds the the exceptions that erpc:call/5 can
304 raise.
305 erpc:multicall/5 fails with an {erpc, badarg} error exception
307 if:
308 * Nodes is not a proper list of atoms. Note that some requests
310 may already have been sent when the failure occurs. That is,
311 the function may or may not be applied on some nodes.
312 * Module is not an atom.
314 * Function is not an atom.
316 * Args is not a list. Note that the list is not verified to be
318 a proper list at the client side.
319 The call erpc:multicall(Nodes, Module, Function, Args) is equiv‐
321 alent to the call erpc:multicall(Nodes, Module, Function, Args,
322 infinity). These calls are also equivalent to calling my_multi‐
323 call(Nodes, Module, Function, Args) if one disregard performance
324 and failure behavior:
325 my_multicall(Nodes, Module, Function, Args) ->
327 ReqIds = lists:map(fun (Node) ->
328 erpc:send_request(Node, Module, Function, Args)
329 end,
330 Nodes),
331 lists:map(fun (ReqId) ->
332 try
333 {ok, erpc:receive_response(ReqId, infinity)}
334 catch
335 Class:Reason ->
336 {Class, Reason}
337 end
338 end,
339 ReqIds).
340 The Timeout value in milliseconds sets an upper time limit for
343 all call operations to complete.
344 If an erpc operation fails, but it is unknown if the function
346 is/will be applied (that is, a timeout, connection loss, or an
347 improper Nodes list), the caller will not receive any further
348 information about the result if/when the applied function com‐
349 pletes. If the applied function communicates with the calling
350 process, such communication may, of course, reach the calling
351 process.
352 Note:
354 You cannot make any assumptions about the process that will per‐
355 form the apply(). It may be the calling process itself, a
356 server, or a freshly spawned process.
357 multicast(Nodes, Fun) -> ok
360 Types:
362 Nodes = [node()]
364 Fun = function()
365 The same as calling erpc:multicast(Nodes,erlang,apply,[Fun,[]]).
367 erpc:multicast/2 fails with an {erpc, badarg} error exception
369 if:
370 * Nodes is not a proper list of atoms.
372 * Fun is not a a fun of zero arity.
374 multicast(Nodes, Module, Function, Args) -> ok
376 Types:
378 Nodes = [node()]
380 Module = Function = atom()
381 Args = [term()]
382 Evaluates apply(Module, Function, Args) on the nodes Nodes. No
384 response is delivered to the calling process. erpc:multicast()
385 returns immediately after the cast requests have been sent. Any
386 failures beside bad arguments are silently ignored.
387 erpc:multicast/4 fails with an {erpc, badarg} error exception
389 if:
390 * Nodes is not a proper list of atoms. Note that some requests
392 may already have been sent when the failure occurs. That is,
393 the function may or may not be applied on some nodes.
394 * Module is not an atom.
396 * Function is not an atom.
398 * Args is not a list. Note that the list is not verified to be
400 a proper list at the client side.
401 Note:
403 You cannot make any assumptions about the process that will per‐
404 form the apply(). It may be a server, or a freshly spawned
405 process.
406 receive_response(RequestId) -> Result
409 receive_response(RequestId, Timeout) -> Result
411 Types:
413 RequestId = request_id()
415 Timeout = 0..4294967295 | infinity
416 Result = term()
417 Receive a response to a call request previously made by the
419 calling process using erpc:send_request/4. RequestId should be
420 the value returned from the previously made erpc:send_request()
421 call, and the corresponding response should not already have
422 been received and handled to completion by
423 erpc:check_response(), erpc:receive_response(), or
424 erpc:wait_response(). Timeout is an integer representing the
425 timeout in milliseconds or the atom infinity which prevents the
426 operation from ever timing out. The call operation is completed
427 once the erpc:receive_response() call returns or raise an excep‐
428 tion.
429 The call erpc:receive_response(RequestId) is equivalent to the
431 call erpc:receive_response(RequestId, infinity).
432 A call to the function my_call(Node, Module, Function, Args,
434 Timeout) below is equivalent to the call erpc:call(Node, Module,
435 Function, Args, Timeout) if one disregards performance.
436 erpc:call() can utilize a message queue optimization which
437 removes the need to scan the whole message queue which the com‐
438 bination erpc:send_request()/erpc:receive_response() cannot.
439 my_call(Node, Module, Function, Args, Timeout) ->
441 RequestId = erpc:send_request(Node, Module, Function, Args),
442 erpc:receive_response(RequestId, Timeout).
443 If the erpc operation fails, but it is unknown if the function
446 is/will be applied (that is, a timeout, or a connection loss),
447 the caller will not receive any further information about the
448 result if/when the applied function completes. If the applied
449 function explicitly communicates with the calling process, such
450 communication may, of course, reach the calling process.
451 erpc:receive_response() will return or raise exceptions the same
453 way as erpc:call/5 does with the exception of {erpc, badarg}. An
454 {erpc, badarg} exception will be raised if/when an invalid
455 RequestId is detected or if an invalid Timeout is passed.
456 send_request(Node, Fun) -> RequestId
458 Types:
460 Node = node()
462 Fun = function()
463 RequestId = request_id()
464 The same as calling
466 erpc:send_request(Node,erlang,apply,[Fun,[]]).
467 erpc:send_request/2 fails with an {erpc, badarg} error exception
469 if:
470 * Node is not an atom.
472 * Fun is not a fun of zero arity.
474 Note:
476 You cannot make any assumptions about the process that will per‐
477 form the apply(). It may be a server, or a freshly spawned
478 process.
479 send_request(Node, Module, Function, Args) -> RequestId
482 Types:
484 Node = node()
486 Module = Function = atom()
487 Args = [term()]
488 RequestId = request_id()
489 Send an asynchronous call request to the node Node.
491 erpc:send_request() returns a request identifier that later is
492 to be passed as argument to either erpc:receive_response(),
493 erpc:wait_response(), or, erpc:check_response() in order to get
494 the response of the call request.
495 erpc:send_request() fails with an {erpc, badarg} error exception
497 if:
498 * Node is not an atom.
500 * Module is not an atom.
502 * Function is not an atom.
504 * Args is not a list. Note that the list is not verified to be
506 a proper list at the client side.
507 wait_response(RequestId) -> {response, Result} | no_response
509 wait_response(RequestId, WaitTime) ->
511 {response, Result} | no_response
512 Types:
514 RequestId = request_id()
516 WaitTime = 0..4294967295 | infinity
517 Result = term()
518 Wait or poll for a response message to a call request previously
520 made by the calling process using erpc:send_request/4. RequestId
521 should be the value returned from the previously made
522 erpc:send_request() call, and the corresponding response should
523 not already have been received and handled to completion by
524 erpc:check_response(), erpc:receive_response(), or
525 erpc:wait_response(). WaitTime equals the time to wait in mil‐
526 liseconds (or the atom infinity) during the wait. WaitTime is an
527 integer representing time to wait in milliseconds or the atom
528 infinity which will cause wait_response/2 to wait for a response
529 until it appears regardless of how long time that is.
530 The call erpc:wait_response(RequestId) is equivalent to the call
532 erpc:wait_response(RequestId, 0). That is, poll for a response
533 message to a call request previously made by the calling
534 process.
535 If no response is received before WaitTime milliseconds, the
537 atom no_response is returned. It is valid to continue waiting
538 for a response as many times as needed up until a response has
539 been received and completed by erpc:check_response(),
540 erpc:receive_response(), or erpc:wait_response(). If a response
541 is received, the call operation is completed and either the
542 result is returned as {response, Result} where Result corre‐
543 sponds to the value returned from the applied function or an
544 exception is raised. The exceptions that can be raised corre‐
545 sponds to the same exceptions as can be raised by erpc:call/4.
546 That is, no {erpc, timeout} error exception can be raised.
547 erpc:wait_response() will fail with an {erpc, badarg} exception
548 if/when an invalid RequestId is detected or if an invalid Wait‐
549 Time is passed.
550 If the erpc operation fails, but it is unknown if the function
552 is/will be applied (that is, a too large wait time value, or a
553 connection loss), the caller will not receive any further infor‐
554 mation about the result if/when the applied function completes.
555 If the applied function explicitly communicates with the calling
556 process, such communication may, of course, reach the calling
557 process.
558Ericsson AB kernel 7.3 erpc(3)