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 re‐
10 mote procedure call is a method to call a function on a remote node and
11 collect the answer. It is used for collecting information on a remote
12 node, or for running a function with some specific side effects on the
13 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 be‐
17 tween 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 ar‐
50 ity.
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 in‐
107 dicates 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 re‐
186 sponse is delivered to the calling process. erpc:cast() returns
187 immediately after the cast request has been sent. Any failures
188 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 erpc:wait_re‐
222 sponse(). Message is the message to check.
223 If Message does not correspond to the response, the atom no_re‐
225 sponse is returned. If Message corresponds to the response, the
226 call operation is completed and either the result is returned as
227 {response, Result} where Result corresponds to the value re‐
228 turned from the applied function or an exception is raised. The
229 exceptions that can be raised corresponds to the same exceptions
230 as can be raised by erpc:call/4. That is, no {erpc, timeout} er‐
231 ror exception can be raised. erpc:check_response() will fail
232 with an {erpc, badarg} exception if/when an invalid RequestId is
233 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:multicall(Nodes,erlang,ap‐
254 ply,[Fun,[]],Timeout). May raise all the same exceptions as
255 erpc:multicall/5 plus an {erpc, badarg} error exception if Fun
256 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 op‐
292 eration 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 erpc:check_re‐
423 sponse(), erpc:receive_response(), or erpc:wait_response().
424 Timeout is an integer representing the timeout in milliseconds
425 or the atom infinity which prevents the operation from ever tim‐
426 ing out. The call operation is completed once the erpc:re‐
427 ceive_response() call returns or raise an exception.
428 The call erpc:receive_response(RequestId) is equivalent to the
430 call erpc:receive_response(RequestId, infinity).
431 A call to the function my_call(Node, Module, Function, Args,
433 Timeout) below is equivalent to the call erpc:call(Node, Module,
434 Function, Args, Timeout) if one disregards performance.
435 erpc:call() can utilize a message queue optimization which re‐
436 moves the need to scan the whole message queue which the combi‐
437 nation erpc:send_request()/erpc:receive_response() cannot.
438 my_call(Node, Module, Function, Args, Timeout) ->
440 RequestId = erpc:send_request(Node, Module, Function, Args),
441 erpc:receive_response(RequestId, Timeout).
442 If the erpc operation fails, but it is unknown if the function
445 is/will be applied (that is, a timeout, or a connection loss),
446 the caller will not receive any further information about the
447 result if/when the applied function completes. If the applied
448 function explicitly communicates with the calling process, such
449 communication may, of course, reach the calling process.
450 erpc:receive_response() will return or raise exceptions the same
452 way as erpc:call/5 does with the exception of {erpc, badarg}. An
453 {erpc, badarg} exception will be raised if/when an invalid Re‐
454 questId is detected or if an invalid Timeout is passed.
455 send_request(Node, Fun) -> RequestId
457 Types:
459 Node = node()
461 Fun = function()
462 RequestId = request_id()
463 The same as calling erpc:send_request(Node,erlang,ap‐
465 ply,[Fun,[]]).
466 erpc:send_request/2 fails with an {erpc, badarg} error exception
468 if:
469 * Node is not an atom.
471 * Fun is not a fun of zero arity.
473 Note:
475 You cannot make any assumptions about the process that will per‐
476 form the apply(). It may be a server, or a freshly spawned
477 process.
478 send_request(Node, Module, Function, Args) -> RequestId
481 Types:
483 Node = node()
485 Module = Function = atom()
486 Args = [term()]
487 RequestId = request_id()
488 Send an asynchronous call request to the node Node.
490 erpc:send_request() returns a request identifier that later is
491 to be passed as argument to either erpc:receive_response(),
492 erpc:wait_response(), or, erpc:check_response() in order to get
493 the response of the call request.
494 erpc:send_request() fails with an {erpc, badarg} error exception
496 if:
497 * Node is not an atom.
499 * Module is not an atom.
501 * Function is not an atom.
503 * Args is not a list. Note that the list is not verified to be
505 a proper list at the client side.
506 wait_response(RequestId) -> {response, Result} | no_response
508 wait_response(RequestId, WaitTime) ->
510 {response, Result} | no_response
511 Types:
513 RequestId = request_id()
515 WaitTime = 0..4294967295 | infinity
516 Result = term()
517 Wait or poll for a response message to a call request previously
519 made by the calling process using erpc:send_request/4. RequestId
520 should be the value returned from the previously made
521 erpc:send_request() call, and the corresponding response should
522 not already have been received and handled to completion by
523 erpc:check_response(), erpc:receive_response(), or erpc:wait_re‐
524 sponse(). WaitTime equals the time to wait in milliseconds (or
525 the atom infinity) during the wait. WaitTime is an integer rep‐
526 resenting time to wait in milliseconds or the atom infinity
527 which will cause wait_response/2 to wait for a response until it
528 appears regardless of how long time that is.
529 The call erpc:wait_response(RequestId) is equivalent to the call
531 erpc:wait_response(RequestId, 0). That is, poll for a response
532 message to a call request previously made by the calling
533 process.
534 If no response is received before WaitTime milliseconds, the
536 atom no_response is returned. It is valid to continue waiting
537 for a response as many times as needed up until a response has
538 been received and completed by erpc:check_response(), erpc:re‐
539 ceive_response(), or erpc:wait_response(). If a response is re‐
540 ceived, the call operation is completed and either the result is
541 returned as {response, Result} where Result corresponds to the
542 value returned from the applied function or an exception is
543 raised. The exceptions that can be raised corresponds to the
544 same exceptions as can be raised by erpc:call/4. That is, no
545 {erpc, timeout} error exception can be raised. erpc:wait_re‐
546 sponse() will fail with an {erpc, badarg} exception if/when an
547 invalid RequestId is detected or if an invalid WaitTime is
548 passed.
549 If the erpc operation fails, but it is unknown if the function
551 is/will be applied (that is, a too large wait time value, or a
552 connection loss), the caller will not receive any further infor‐
553 mation about the result if/when the applied function completes.
554 If the applied function explicitly communicates with the calling
555 process, such communication may, of course, reach the calling
556 process.
557Ericsson AB kernel 8.3.2 erpc(3)