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 request identifier. For more information see send_re‐
33 quest/4.
34 request_id_collection()
36 An opaque collection of request identifiers (request_id()) where
38 each request identifier can be associated with a label chosen by
39 the user. For more information see reqids_new/0.
40 timeout_time() = 0..4294967295 | infinity | {abs, integer()}
42 0..4294967295:
44 Timeout relative to current time in milliseconds.
45 infinity:
47 Infinite timeout. That is, the operation will never time
48 out.
49 {abs, Timeout}:
51 An absolute Erlang monotonic time timeout in milliseconds.
52 That is, the operation will time out when erlang:mono‐
53 tonic_time(millisecond) returns a value larger than or equal
54 to Timeout. Timeout is not allowed to identify a time fur‐
55 ther into the future than 4294967295 milliseconds. Identify‐
56 ing the timeout using an absolute timeout value is espe‐
57 cially handy when you have a deadline for responses corre‐
58 sponding to a complete collection of requests (re‐
59 quest_id_collection()) , since you do not have to recalcu‐
60 late the relative time until the deadline over and over
61 again.
62
64 call(Node, Fun) -> Result
65 call(Node, Fun, Timeout) -> Result
67 Types:
69 Node = node()
71 Fun = function()
72 Timeout = timeout_time()
73 Result = term()
74 The same as calling erpc:call(Node, erlang, apply, [Fun,[]],
76 Timeout). May raise all the same exceptions as call/5 plus an
77 {erpc, badarg} error exception if Fun is not a fun of zero ar‐
78 ity.
79 The call erpc:call(Node,Fun) is the same as the call
81 erpc:call(Node,Fun,infinity).
82 call(Node, Module, Function, Args) -> Result
84 call(Node, Module, Function, Args, Timeout) -> Result
86 Types:
88 Node = node()
90 Module = Function = atom()
91 Args = [term()]
92 Timeout = timeout_time()
93 Result = term()
94 Evaluates apply(Module, Function, Args) on node Node and returns
96 the corresponding value Result. Timeout sets an upper time limit
97 for the call operation to complete.
98 The call erpc:call(Node, Module, Function, Args) is equivalent
100 to the call erpc:call(Node, Module, Function, Args, infinity)
101 The call() function only returns if the applied function suc‐
103 cessfully returned without raising any uncaught exceptions, the
104 operation did not time out, and no failures occurred. In all
105 other cases an exception is raised. The following exceptions,
106 listed by exception class, can currently be raised by call():
107 throw:
109 The applied function called throw(Value) and did not catch
110 this exception. The exception reason Value equals the argu‐
111 ment passed to throw/1.
112 exit:
114 Exception reason:
115 {exception, ExitReason}:
117 The applied function called exit(ExitReason) and did not
118 catch this exception. The exit reason ExitReason equals
119 the argument passed to exit/1.
120 {signal, ExitReason}:
122 The process that applied the function received an exit
123 signal and terminated due to this signal. The process ter‐
124 minated with exit reason ExitReason.
125 error:
127 Exception reason:
128 {exception, ErrorReason, StackTrace}:
130 A runtime error occurred which raised an error exception
131 while applying the function, and the applied function did
132 not catch the exception. The error reason ErrorReason in‐
133 dicates the type of error that occurred. StackTrace is
134 formatted as when caught in a try/catch construct. The
135 StackTrace is limited to the applied function and func‐
136 tions called by it.
137 {erpc, ERpcErrorReason}:
139 The erpc operation failed. The following ERpcErrorReasons
140 are the most common ones:
141 badarg:
143 If any one of these are true:
144 * Node is not an atom.
146 * Module is not an atom.
148 * Function is not an atom.
150 * Args is not a list. Note that the list is not verified
152 to be a proper list at the client side.
153 * Timeout is invalid.
155 noconnection:
157 The connection to Node was lost or could not be estab‐
158 lished. The function may or may not be applied.
159 system_limit:
161 The erpc operation failed due to some system limit being
162 reached. This typically due to failure to create a
163 process on the remote node Node, but can be other things
164 as well.
165 timeout:
167 The erpc operation timed out. The function may or may
168 not be applied.
169 notsup:
171 The remote node Node does not support this erpc opera‐
172 tion.
173 If the erpc operation fails, but it is unknown if the function
175 is/will be applied (that is, a timeout or a connection loss),
176 the caller will not receive any further information about the
177 result if/when the applied function completes. If the applied
178 function explicitly communicates with the calling process, such
179 communication may, of course, reach the calling process.
180 Note:
182 You cannot make any assumptions about the process that will per‐
183 form the apply(). It may be the calling process itself, a
184 server, or a freshly spawned process.
185 cast(Node, Fun) -> ok
188 Types:
190 Node = node()
192 Fun = function()
193 The same as calling erpc:cast(Node,erlang,apply,[Fun,[]]).
195 cast/2 fails with an {erpc, badarg} error exception if:
197 * Node is not an atom.
199 * Fun is not a a fun of zero arity.
201 cast(Node, Module, Function, Args) -> ok
203 Types:
205 Node = node()
207 Module = Function = atom()
208 Args = [term()]
209 Evaluates apply(Module, Function, Args) on node Node. No re‐
211 sponse is delivered to the calling process. cast() returns imme‐
212 diately after the cast request has been sent. Any failures be‐
213 side bad arguments are silently ignored.
214 cast/4 fails with an {erpc, badarg} error exception if:
216 * Node is not an atom.
218 * Module is not an atom.
220 * Function is not an atom.
222 * Args is not a list. Note that the list is not verified to be
224 a proper list at the client side.
225 Note:
227 You cannot make any assumptions about the process that will per‐
228 form the apply(). It may be a server, or a freshly spawned
229 process.
230 check_response(Message, RequestId) ->
233 {response, Result} | no_response
234 Types:
236 Message = term()
238 RequestId = request_id()
239 Result = term()
240 Check if a message is a response to a call request previously
242 made by the calling process using send_request/4. RequestId
243 should be the value returned from the previously made send_re‐
244 quest/4 call, and the corresponding response should not already
245 have been received and handled to completion by check_re‐
246 sponse/2, receive_response/2, or wait_response/2. Message is the
247 message to check.
248 If Message does not correspond to the response, the atom no_re‐
250 sponse is returned. If Message corresponds to the response, the
251 call operation is completed and either the result is returned as
252 {response, Result} where Result corresponds to the value re‐
253 turned from the applied function or an exception is raised. The
254 exceptions that can be raised corresponds to the same exceptions
255 as can be raised by call/4. That is, no {erpc, timeout} error
256 exception can be raised. check_response() will fail with an
257 {erpc, badarg} exception if/when an invalid RequestId is de‐
258 tected.
259 If the erpc operation fails, but it is unknown if the function
261 is/will be applied (that is, a connection loss), the caller will
262 not receive any further information about the result if/when the
263 applied function completes. If the applied function explicitly
264 communicates with the calling process, such communication may,
265 of course, reach the calling process.
266 check_response(Message, RequestIdCollection, Delete) ->
268 {{response, Result},
269 Label, NewRequestIdCollection} |
270 no_response | no_request
271 Types:
273 Message = term()
275 RequestIdCollection = request_id_collection()
276 Delete = boolean()
277 Result = Label = term()
278 NewRequestIdCollection = request_id_collection()
279 Check if a message is a response to a call request corresponding
281 to a request identifier saved in RequestIdCollection. All re‐
282 quest identifiers of RequestIdCollection must correspond to re‐
283 quests that have been made using send_request/4 or send_re‐
284 quest/6, and all requests must have been made by the process
285 calling this function.
286 Label is the label associated with the request identifier of the
288 request that the response corresponds to. A request identifier
289 is associated with a label when adding a request identifier in a
290 request identifier collection, or when sending the request using
291 send_request/6.
292 Compared to check_response/2, the returned result associated
294 with a specific request identifier or an exception associated
295 with a specific request identifier will be wrapped in a 3-tuple.
296 The first element of this tuple equals the value that would have
297 been produced by check_response/2, the second element equals the
298 Label associated with the specific request identifier, and the
299 third element NewRequestIdCollection is a possibly modified re‐
300 quest identifier collection. The error exception {erpc, badarg}
301 is not associated with any specific request identifier, and will
302 hence not be wrapped.
303 If RequestIdCollection is empty, the atom no_request will be re‐
305 turned. If Message does not correspond to any of the request
306 identifiers in RequestIdCollection, the atom no_response is re‐
307 turned.
308 If Delete equals true, the association with Label will have been
310 deleted from RequestIdCollection in the resulting NewRequestId‐
311 Collection. If Delete equals false, NewRequestIdCollection will
312 equal RequestIdCollection. Note that deleting an association is
313 not for free and that a collection containing already handled
314 requests can still be used by subsequent calls to check_re‐
315 sponse/3, receive_response/3, and wait_response/3. However,
316 without deleting handled associations, the above calls will not
317 be able to detect when there are no more outstanding requests to
318 handle, so you will have to keep track of this some other way
319 than relying on a no_request return. Note that if you pass a
320 collection only containing associations of already handled or
321 abandoned requests to check_response/3, it will always return
322 no_response.
323 Note that a response might have been consumed uppon an {erpc,
325 badarg} exception and if so, will be lost for ever.
326 multicall(Nodes, Fun) -> Result
328 multicall(Nodes, Fun, Timeout) -> Result
330 Types:
332 Nodes = [atom()]
334 Fun = function()
335 Timeout = timeout_time()
336 Result = term()
337 The same as calling erpc:multicall(Nodes, erlang, apply,
339 [Fun,[]], Timeout). May raise all the same exceptions as multi‐
340 call/5 plus an {erpc, badarg} error exception if Fun is not a
341 fun of zero arity.
342 The call erpc:multicall(Nodes,Fun) is the same as the call
344 erpc:multicall(Nodes,Fun, infinity).
345 multicall(Nodes, Module, Function, Args) -> Result
347 multicall(Nodes, Module, Function, Args, Timeout) -> Result
349 Types:
351 Nodes = [atom()]
353 Module = Function = atom()
354 Args = [term()]
355 Timeout = timeout_time()
356 Result =
357 [{ok, ReturnValue :: term()} | caught_call_exception()]
358 caught_call_exception() =
359 {throw, Throw :: term()} |
360 {exit, {exception, Reason :: term()}} |
361 {error,
362 {exception, Reason :: term(), StackTrace :: [stack_item()]}} |
363 {exit, {signal, Reason :: term()}} |
364 {error, {erpc, Reason :: term()}}
365 stack_item() =
366 {Module :: atom(),
367 Function :: atom(),
368 Arity :: arity() | (Args :: [term()]),
369 Location ::
370 [{file, Filename :: string()} |
371 {line, Line :: integer() >= 1}]}
372 Performs multiple call operations in parallel on multiple nodes.
374 That is, evaluates apply(Module, Function, Args) on the nodes
375 Nodes in parallel. Timeout sets an upper time limit for all call
376 operations to complete. The result is returned as a list where
377 the result from each node is placed at the same position as the
378 node name is placed in Nodes. Each item in the resulting list is
379 formatted as either:
380 {ok, Result}:
382 The call operation for this specific node returned Result.
383 {Class, ExceptionReason}:
385 The call operation for this specific node raised an excep‐
386 tion of class Class with exception reason ExceptionReason.
387 These correspond to the exceptions that call/5 can raise.
388 multicall/5 fails with an {erpc, badarg} error exception 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 The call erpc:multicall(Nodes, Module, Function, Args) is equiv‐
403 alent to the call erpc:multicall(Nodes, Module, Function, Args,
404 infinity). These calls are also equivalent to calling my_multi‐
405 call(Nodes, Module, Function, Args) below if one disregard per‐
406 formance and failure behavior. multicall() can utilize a selec‐
407 tive receive optimization which removes the need to scan the
408 message queue from the beginning in order to find a matching
409 message. The send_request()/receive_response() combination can,
410 however, not utilize this optimization.
411 my_multicall(Nodes, Module, Function, Args) ->
413 ReqIds = lists:map(fun (Node) ->
414 erpc:send_request(Node, Module, Function, Args)
415 end,
416 Nodes),
417 lists:map(fun (ReqId) ->
418 try
419 {ok, erpc:receive_response(ReqId, infinity)}
420 catch
421 Class:Reason ->
422 {Class, Reason}
423 end
424 end,
425 ReqIds).
426 If an erpc operation fails, but it is unknown if the function
429 is/will be applied (that is, a timeout, connection loss, or an
430 improper Nodes list), the caller will not receive any further
431 information about the result if/when the applied function com‐
432 pletes. If the applied function communicates with the calling
433 process, such communication may, of course, reach the calling
434 process.
435 Note:
437 You cannot make any assumptions about the process that will per‐
438 form the apply(). It may be the calling process itself, a
439 server, or a freshly spawned process.
440 multicast(Nodes, Fun) -> ok
443 Types:
445 Nodes = [node()]
447 Fun = function()
448 The same as calling erpc:multicast(Nodes,erlang,apply,[Fun,[]]).
450 multicast/2 fails with an {erpc, badarg} error exception if:
452 * Nodes is not a proper list of atoms.
454 * Fun is not a a fun of zero arity.
456 multicast(Nodes, Module, Function, Args) -> ok
458 Types:
460 Nodes = [node()]
462 Module = Function = atom()
463 Args = [term()]
464 Evaluates apply(Module, Function, Args) on the nodes Nodes. No
466 response is delivered to the calling process. multicast() re‐
467 turns immediately after the cast requests have been sent. Any
468 failures beside bad arguments are silently ignored.
469 multicast/4 fails with an {erpc, badarg} error exception if:
471 * Nodes is not a proper list of atoms. Note that some requests
473 may already have been sent when the failure occurs. That is,
474 the function may or may not be applied on some nodes.
475 * Module is not an atom.
477 * Function is not an atom.
479 * Args is not a list. Note that the list is not verified to be
481 a proper list at the client side.
482 Note:
484 You cannot make any assumptions about the process that will per‐
485 form the apply(). It may be a server, or a freshly spawned
486 process.
487 receive_response(RequestId) -> Result
490 Types:
492 RequestId = request_id()
494 Result = term()
495 The same as calling erpc:receive_response(RequestId, infinity).
497 receive_response(RequestId, Timeout) -> Result
499 Types:
501 RequestId = request_id()
503 Timeout = timeout_time()
504 Result = term()
505 Receive a response to a call request previously made by the
507 calling process using send_request/4. RequestId should be the
508 value returned from the previously made send_request/4 call, and
509 the corresponding response should not already have been received
510 and handled to completion by receive_response(), check_re‐
511 sponse/4, or wait_response/4.
512 Timeout sets an upper time limit on how long to wait for a re‐
514 sponse. If the operation times out, the request identified by
515 RequestId will be abandoned, then an {erpc, timeout} error ex‐
516 ception will be raised. That is, no response corresponding to
517 the request will ever be received after a timeout. If a response
518 is received, the call operation is completed and either the re‐
519 sult is returned or an exception is raised. The exceptions that
520 can be raised corresponds to the same exceptions as can be
521 raised by call/5. receive_response/2 will fail with an {erpc,
522 badarg} exception if/when an invalid RequestId is detected or if
523 an invalid Timeout is passed.
524 A call to the function my_call(Node, Module, Function, Args,
526 Timeout) below is equivalent to the call erpc:call(Node, Module,
527 Function, Args, Timeout) if one disregards performance. call()
528 can utilize a selective receive optimization which removes the
529 need to scan the message queue from the beginning in order to
530 find a matching message. The send_request()/receive_response()
531 combination can, however, not utilize this optimization.
532 my_call(Node, Module, Function, Args, Timeout) ->
534 RequestId = erpc:send_request(Node, Module, Function, Args),
535 erpc:receive_response(RequestId, Timeout).
536 If the erpc operation fails, but it is unknown if the function
539 is/will be applied (that is, a timeout, or a connection loss),
540 the caller will not receive any further information about the
541 result if/when the applied function completes. If the applied
542 function explicitly communicates with the calling process, such
543 communication may, of course, reach the calling process.
544 receive_response(RequestIdCollection, Timeout, Delete) ->
546 {Result, Label, NewRequestIdCollection} |
547 no_request
548 Types:
550 RequestIdCollection = request_id_collection()
552 Timeout = timeout_time()
553 Delete = boolean()
554 Result = Label = term()
555 NewRequestIdCollection = request_id_collection()
556 Receive a response to a call request corresponding to a request
558 identifier saved in RequestIdCollection. All request identifiers
559 of RequestIdCollection must correspond to requests that have
560 been made using send_request/4 or send_request/6, and all re‐
561 quests must have been made by the process calling this function.
562 Label is the label associated with the request identifier of the
564 request that the response corresponds to. A request identifier
565 is associated with a label when adding a request identifier in a
566 request identifier collection, or when sending the request using
567 send_request/6.
568 Compared to receive_response/2, the returned result associated
570 with a specific request identifier or an exception associated
571 with a specific request identifier will be wrapped in a 3-tuple.
572 The first element of this tuple equals the value that would have
573 been produced by receive_response/2, the second element equals
574 the Label associated with the specific request identifier, and
575 the third element NewRequestIdCollection is a possibly modified
576 request identifier collection. The error exceptions {erpc,
577 badarg} and {erpc, timeout} are not associated with any specific
578 request identifiers, and will hence not be wrapped.
579 If RequestIdCollection is empty, the atom no_request will be re‐
581 turned.
582 If the operation times out, all requests identified by Re‐
584 questIdCollection will be abandoned, then an {erpc, timeout} er‐
585 ror exception will be raised. That is, no responses correspond‐
586 ing to any of the request identifiers in RequestIdCollection
587 will ever be received after a timeout. The difference between
588 receive_response/3 and wait_response/3 is that receive_re‐
589 sponse/3 abandons the requests at timeout so that any potential
590 future responses are ignored, while wait_response/3 does not.
591 If Delete equals true, the association with Label will have been
593 deleted from RequestIdCollection in the resulting NewRequestId‐
594 Collection. If Delete equals false, NewRequestIdCollection will
595 equal RequestIdCollection. Note that deleting an association is
596 not for free and that a collection containing already handled
597 requests can still be used by subsequent calls to receive_re‐
598 sponse/3, check_response/3, and wait_response/3. However, with‐
599 out deleting handled associations, the above calls will not be
600 able to detect when there are no more outstanding requests to
601 handle, so you will have to keep track of this some other way
602 than relying on a no_request return. Note that if you pass a
603 collection only containing associations of already handled or
604 abandoned requests to receive_response/3, it will always block
605 until a timeout determined by Timeout is triggered.
606 Note that a response might have been consumed uppon an {erpc,
608 badarg} exception and if so, will be lost for ever.
609 reqids_add(RequestId :: request_id(),
611 Label :: term(),
612 RequestIdCollection :: request_id_collection()) ->
613 NewRequestIdCollection :: request_id_collection()
614 Saves RequestId and associates a Label with the request identi‐
616 fier by adding this information to RequestIdCollection and re‐
617 turning the resulting request identifier collection.
618 reqids_new() -> NewRequestIdCollection :: request_id_collection()
620 Returns a new empty request identifier collection. A request
622 identifier collection can be utilized in order the handle multi‐
623 ple outstanding requests.
624 Request identifiers of requests made by send_request/4 can be
626 saved in a request identifier collection using reqids_add/3.
627 Such a collection of request identifiers can later be used in
628 order to get one response corresponding to a request in the col‐
629 lection by passing the collection as argument to check_re‐
630 sponse/3, receive_response/3, and wait_response/3.
631 reqids_size/1 can be used to determine the amount of request
633 identifiers in a request identifier collection.
634 reqids_size(RequestIdCollection :: request_id_collection()) ->
636 integer() >= 0
637 Returns the amount of request identifiers saved in RequestIdCol‐
639 lection.
640 reqids_to_list(RequestIdCollection :: request_id_collection()) ->
642 [{RequestId :: request_id(), Label :: term()}]
643 Returns a list of {RequestId, Label} tuples which corresponds to
645 all request identifiers with their associated labels present in
646 the RequestIdCollection collection.
647 send_request(Node, Fun) -> RequestId
649 Types:
651 Node = node()
653 Fun = function()
654 RequestId = request_id()
655 The same as calling erpc:send_request(Node, erlang, apply, [Fun,
657 []]).
658 Fails with an {erpc, badarg} error exception if:
660 * Node is not an atom.
662 * Fun is not a fun of zero arity.
664 Note:
666 You cannot make any assumptions about the process that will per‐
667 form the apply(). It may be a server, or a freshly spawned
668 process.
669 send_request(Node, Module, Function, Args) -> RequestId
672 Types:
674 Node = node()
676 Module = Function = atom()
677 Args = [term()]
678 RequestId = request_id()
679 Send an asynchronous call request to the node Node. send_re‐
681 quest/4 returns a request identifier that later is to be passed
682 to either receive_response/2, wait_response/2, or, check_re‐
683 sponse/2 in order to get the response of the call request. Be‐
684 sides passing the request identifier directly to these func‐
685 tions, it can also be added in a request identifier collection
686 using reqids_add/3. Such a collection of request identifiers can
687 later be used in order to get one response corresponding to a
688 request in the collection by passing the collection as argument
689 to receive_response/3, wait_response/3, or, check_response/3. If
690 you are about to save the request identifier in a request iden‐
691 tifier collection, you may want to consider using send_request/6
692 instead.
693 A call to the function my_call(Node, Module, Function, Args,
695 Timeout) below is equivalent to the call erpc:call(Node, Module,
696 Function, Args, Timeout) if one disregards performance. call()
697 can utilize a selective receive optimization which removes the
698 need to scan the message queue from the beginning in order to
699 find a matching message. The send_request()/receive_response()
700 combination can, however, not utilize this optimization.
701 my_call(Node, Module, Function, Args, Timeout) ->
703 RequestId = erpc:send_request(Node, Module, Function, Args),
704 erpc:receive_response(RequestId, Timeout).
705 Fails with an {erpc, badarg} error exception if:
708 * Node is not an atom.
710 * Module is not an atom.
712 * Function is not an atom.
714 * Args is not a list. Note that the list is not verified to be
716 a proper list at the client side.
717 Note:
719 You cannot make any assumptions about the process that will per‐
720 form the apply(). It may be a server, or a freshly spawned
721 process.
722 send_request(Node, Fun, Label, RequestIdCollection) ->
725 NewRequestIdCollection
726 Types:
728 Node = node()
730 Fun = function()
731 Label = term()
732 RequestIdCollection = NewRequestIdCollection = re‐
733 quest_id_collection()
734 The same as calling erpc:send_request(Node, erlang, apply,
736 [Fun,[]]), Label, RequestIdCollection).
737 Fails with an {erpc, badarg} error exception if:
739 * Node is not an atom.
741 * Fun is not a fun of zero arity.
743 * RequestIdCollection is detected not to be request identifier
745 collection.
746 Note:
748 You cannot make any assumptions about the process that will per‐
749 form the apply(). It may be a server, or a freshly spawned
750 process.
751 send_request(Node, Module, Function, Args, Label,
754 RequestIdCollection) ->
755 NewRequestIdCollection
756 Types:
758 Node = node()
760 Module = Function = atom()
761 Args = [term()]
762 Label = term()
763 RequestIdCollection = NewRequestIdCollection = re‐
764 quest_id_collection()
765 Send an asynchronous call request to the node Node. The Label
767 will be associated with the request identifier of the operation
768 and added to the returned request identifier collection NewRe‐
769 questIdCollection. The collection can later be used in order to
770 get one response corresponding to a request in the collection by
771 passing the collection as argument to receive_response/3,
772 wait_response/3, or, check_response/3.
773 The same as calling erpc:reqids_add(erpc:send_request(Node, Mod‐
775 ule, Function, Args), Label, RequestIdCollection), but calling
776 send_request/6 is slightly more efficient.
777 Fails with an {erpc, badarg} error exception if:
779 * Node is not an atom.
781 * Module is not an atom.
783 * Function is not an atom.
785 * Args is not a list. Note that the list is not verified to be
787 a proper list at the client side.
788 * RequestIdCollection is detected not to be request identifier
790 collection.
791 Note:
793 You cannot make any assumptions about the process that will per‐
794 form the apply(). It may be a server, or a freshly spawned
795 process.
796 wait_response(RequestId) -> {response, Result} | no_response
799 Types:
801 RequestId = request_id()
803 Result = term()
804 The same as calling erpc:wait_response(RequestId, 0). That is,
806 poll for a response message to a call request previously made by
807 the calling process.
808 wait_response(RequestId, WaitTime) ->
810 {response, Result} | no_response
811 Types:
813 RequestId = request_id()
815 WaitTime = timeout_time()
816 Result = term()
817 Wait or poll for a response message to a call request previously
819 made by the calling process using send_request/4. RequestId
820 should be the value returned from the previously made send_re‐
821 quest() call, and the corresponding response should not already
822 have been received and handled to completion by check_re‐
823 sponse/2, receive_response/2, or wait_response().
824 WaitTime sets an upper time limit on how long to wait for a re‐
826 sponse. If no response is received before the WaitTime timeout
827 has triggered, the atom no_response is returned. It is valid to
828 continue waiting for a response as many times as needed up until
829 a response has been received and completed by check_response(),
830 receive_response(), or wait_response(). If a response is re‐
831 ceived, the call operation is completed and either the result is
832 returned as {response, Result} where Result corresponds to the
833 value returned from the applied function or an exception is
834 raised. The exceptions that can be raised corresponds to the
835 same exceptions as can be raised by call/4. That is, no {erpc,
836 timeout} error exception can be raised. wait_response/2 will
837 fail with an {erpc, badarg} exception if/when an invalid Re‐
838 questId is detected or if an invalid WaitTime is passed.
839 If the erpc operation fails, but it is unknown if the function
841 is/will be applied (that is, a too large wait time value, or a
842 connection loss), the caller will not receive any further infor‐
843 mation about the result if/when the applied function completes.
844 If the applied function explicitly communicates with the calling
845 process, such communication may, of course, reach the calling
846 process.
847 wait_response(RequestIdCollection, WaitTime, Delete) ->
849 {{response, Result},
850 Label, NewRequestIdCollection} |
851 no_response | no_request
852 Types:
854 RequestIdCollection = request_id_collection()
856 WaitTime = timeout_time()
857 Delete = boolean()
858 Label = term()
859 NewRequestIdCollection = request_id_collection()
860 Result = term()
861 Wait or poll for a response to a call request corresponding to a
863 request identifier saved in RequestIdCollection. All request
864 identifiers of RequestIdCollection must correspond to requests
865 that have been made using send_request/4 or send_request/6, and
866 all requests must have been made by the process calling this
867 function.
868 Label is the label associated with the request identifier of the
870 request that the response corresponds to. A request identifier
871 is associated with a label when adding a request identifier in a
872 request identifier collection, or when sending the request using
873 send_request/6.
874 Compared to wait_response/2, the returned result associated with
876 a specific request identifier or an exception associated with a
877 specific request identifier will be wrapped in a 3-tuple. The
878 first element of this tuple equals the value that would have
879 been produced by wait_response/2, the second element equals the
880 Label associated with the specific request identifier, and the
881 third element NewRequestIdCollection is a possibly modified re‐
882 quest identifier collection. The error exception {erpc, badarg}
883 is not associated with any specific request identifier, and will
884 hence not be wrapped.
885 If RequestIdCollection is empty, no_request will be returned. If
887 no response is received before the WaitTime timeout has trig‐
888 gered, the atom no_response is returned. It is valid to continue
889 waiting for a response as many times as needed up until a re‐
890 sponse has been received and completed by check_response(), re‐
891 ceive_response(), or wait_response(). The difference between re‐
892 ceive_response/3 and wait_response/3 is that receive_response/3
893 abandons requests at timeout so that any potential future re‐
894 sponses are ignored, while wait_response/3 does not.
895 If Delete equals true, the association with Label will have been
897 deleted from RequestIdCollection in the resulting NewRequestId‐
898 Collection. If Delete equals false, NewRequestIdCollection will
899 equal RequestIdCollection. Note that deleting an association is
900 not for free and that a collection containing already handled
901 requests can still be used by subsequent calls to wait_re‐
902 sponse/3, check_response/3, and receive_response/3. However,
903 without deleting handled associations, the above calls will not
904 be able to detect when there are no more outstanding requests to
905 handle, so you will have to keep track of this some other way
906 than relying on a no_request return. Note that if you pass a
907 collection only containing associations of already handled or
908 abandoned requests to wait_response/3, it will always block un‐
909 til a timeout determined by WaitTime is triggered and then re‐
910 turn no_response.
911 Note that a response might have been consumed uppon an {erpc,
913 badarg} exception and if so, will be lost for ever.
914Ericsson AB kernel 8.5.4.2 erpc(3)