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 Note:
30 For some important information about distributed signals, see the
31 Blocking Signaling Over Distribution section in the Processes chapter
32 of the Erlang Reference Manual . Blocking signaling can, for example,
33 cause timeouts in erpc to be significantly delayed.
34
37 request_id()
38 An opaque request identifier. For more information see send_re‐
40 quest/4.
41 request_id_collection()
43 An opaque collection of request identifiers (request_id()) where
45 each request identifier can be associated with a label chosen by
46 the user. For more information see reqids_new/0.
47 timeout_time() = 0..4294967295 | infinity | {abs, integer()}
49 0..4294967295:
51 Timeout relative to current time in milliseconds.
52 infinity:
54 Infinite timeout. That is, the operation will never time
55 out.
56 {abs, Timeout}:
58 An absolute Erlang monotonic time timeout in milliseconds.
59 That is, the operation will time out when erlang:mono‐
60 tonic_time(millisecond) returns a value larger than or equal
61 to Timeout. Timeout is not allowed to identify a time fur‐
62 ther into the future than 4294967295 milliseconds. Identify‐
63 ing the timeout using an absolute timeout value is espe‐
64 cially handy when you have a deadline for responses corre‐
65 sponding to a complete collection of requests (re‐
66 quest_id_collection()) , since you do not have to recalcu‐
67 late the relative time until the deadline over and over
68 again.
69
71 call(Node, Fun) -> Result
72 call(Node, Fun, Timeout) -> Result
74 Types:
76 Node = node()
78 Fun = function()
79 Timeout = timeout_time()
80 Result = term()
81 The same as calling erpc:call(Node, erlang, apply, [Fun,[]],
83 Timeout). May raise all the same exceptions as call/5 plus an
84 {erpc, badarg} error exception if Fun is not a fun of zero ar‐
85 ity.
86 The call erpc:call(Node,Fun) is the same as the call
88 erpc:call(Node,Fun,infinity).
89 call(Node, Module, Function, Args) -> Result
91 call(Node, Module, Function, Args, Timeout) -> Result
93 Types:
95 Node = node()
97 Module = Function = atom()
98 Args = [term()]
99 Timeout = timeout_time()
100 Result = term()
101 Evaluates apply(Module, Function, Args) on node Node and returns
103 the corresponding value Result. Timeout sets an upper time limit
104 for the call operation to complete.
105 The call erpc:call(Node, Module, Function, Args) is equivalent
107 to the call erpc:call(Node, Module, Function, Args, infinity)
108 The call() function only returns if the applied function suc‐
110 cessfully returned without raising any uncaught exceptions, the
111 operation did not time out, and no failures occurred. In all
112 other cases an exception is raised. The following exceptions,
113 listed by exception class, can currently be raised by call():
114 throw:
116 The applied function called throw(Value) and did not catch
117 this exception. The exception reason Value equals the argu‐
118 ment passed to throw/1.
119 exit:
121 Exception reason:
122 {exception, ExitReason}:
124 The applied function called exit(ExitReason) and did not
125 catch this exception. The exit reason ExitReason equals
126 the argument passed to exit/1.
127 {signal, ExitReason}:
129 The process that applied the function received an exit
130 signal and terminated due to this signal. The process ter‐
131 minated with exit reason ExitReason.
132 error:
134 Exception reason:
135 {exception, ErrorReason, StackTrace}:
137 A runtime error occurred which raised an error exception
138 while applying the function, and the applied function did
139 not catch the exception. The error reason ErrorReason in‐
140 dicates the type of error that occurred. StackTrace is
141 formatted as when caught in a try/catch construct. The
142 StackTrace is limited to the applied function and func‐
143 tions called by it.
144 {erpc, ERpcErrorReason}:
146 The erpc operation failed. The following ERpcErrorReasons
147 are the most common ones:
148 badarg:
150 If any one of these are true:
151 * Node is not an atom.
153 * Module is not an atom.
155 * Function is not an atom.
157 * Args is not a list. Note that the list is not verified
159 to be a proper list at the client side.
160 * Timeout is invalid.
162 noconnection:
164 The connection to Node was lost or could not be estab‐
165 lished. The function may or may not be applied.
166 system_limit:
168 The erpc operation failed due to some system limit being
169 reached. This typically due to failure to create a
170 process on the remote node Node, but can be other things
171 as well.
172 timeout:
174 The erpc operation timed out. The function may or may
175 not be applied.
176 notsup:
178 The remote node Node does not support this erpc opera‐
179 tion.
180 If the erpc operation fails, but it is unknown if the function
182 is/will be applied (that is, a timeout or a connection loss),
183 the caller will not receive any further information about the
184 result if/when the applied function completes. If the applied
185 function explicitly communicates with the calling process, such
186 communication may, of course, reach the calling process.
187 Note:
189 You cannot make any assumptions about the process that will per‐
190 form the apply(). It may be the calling process itself, a
191 server, or a freshly spawned process.
192 cast(Node, Fun) -> ok
195 Types:
197 Node = node()
199 Fun = function()
200 The same as calling erpc:cast(Node,erlang,apply,[Fun,[]]).
202 cast/2 fails with an {erpc, badarg} error exception if:
204 * Node is not an atom.
206 * Fun is not a a fun of zero arity.
208 cast(Node, Module, Function, Args) -> ok
210 Types:
212 Node = node()
214 Module = Function = atom()
215 Args = [term()]
216 Evaluates apply(Module, Function, Args) on node Node. No re‐
218 sponse is delivered to the calling process. cast() returns imme‐
219 diately after the cast request has been sent. Any failures be‐
220 side bad arguments are silently ignored.
221 cast/4 fails with an {erpc, badarg} error exception if:
223 * Node is not an atom.
225 * Module is not an atom.
227 * Function is not an atom.
229 * Args is not a list. Note that the list is not verified to be
231 a proper list at the client side.
232 Note:
234 You cannot make any assumptions about the process that will per‐
235 form the apply(). It may be a server, or a freshly spawned
236 process.
237 check_response(Message, RequestId) ->
240 {response, Result} | no_response
241 Types:
243 Message = term()
245 RequestId = request_id()
246 Result = term()
247 Check if a message is a response to a call request previously
249 made by the calling process using send_request/4. RequestId
250 should be the value returned from the previously made send_re‐
251 quest/4 call, and the corresponding response should not already
252 have been received and handled to completion by check_re‐
253 sponse/2, receive_response/2, or wait_response/2. Message is the
254 message to check.
255 If Message does not correspond to the response, the atom no_re‐
257 sponse is returned. If Message corresponds to the response, the
258 call operation is completed and either the result is returned as
259 {response, Result} where Result corresponds to the value re‐
260 turned from the applied function or an exception is raised. The
261 exceptions that can be raised corresponds to the same exceptions
262 as can be raised by call/4. That is, no {erpc, timeout} error
263 exception can be raised. check_response() will fail with an
264 {erpc, badarg} exception if/when an invalid RequestId is de‐
265 tected.
266 If the erpc operation fails, but it is unknown if the function
268 is/will be applied (that is, a connection loss), the caller will
269 not receive any further information about the result if/when the
270 applied function completes. If the applied function explicitly
271 communicates with the calling process, such communication may,
272 of course, reach the calling process.
273 check_response(Message, RequestIdCollection, Delete) ->
275 {{response, Result},
276 Label, NewRequestIdCollection} |
277 no_response | no_request
278 Types:
280 Message = term()
282 RequestIdCollection = request_id_collection()
283 Delete = boolean()
284 Result = Label = term()
285 NewRequestIdCollection = request_id_collection()
286 Check if a message is a response to a call request corresponding
288 to a request identifier saved in RequestIdCollection. All re‐
289 quest identifiers of RequestIdCollection must correspond to re‐
290 quests that have been made using send_request/4 or send_re‐
291 quest/6, and all requests must have been made by the process
292 calling this function.
293 Label is the label associated with the request identifier of the
295 request that the response corresponds to. A request identifier
296 is associated with a label when adding a request identifier in a
297 request identifier collection, or when sending the request using
298 send_request/6.
299 Compared to check_response/2, the returned result associated
301 with a specific request identifier or an exception associated
302 with a specific request identifier will be wrapped in a 3-tuple.
303 The first element of this tuple equals the value that would have
304 been produced by check_response/2, the second element equals the
305 Label associated with the specific request identifier, and the
306 third element NewRequestIdCollection is a possibly modified re‐
307 quest identifier collection. The error exception {erpc, badarg}
308 is not associated with any specific request identifier, and will
309 hence not be wrapped.
310 If RequestIdCollection is empty, the atom no_request will be re‐
312 turned. If Message does not correspond to any of the request
313 identifiers in RequestIdCollection, the atom no_response is re‐
314 turned.
315 If Delete equals true, the association with Label will have been
317 deleted from RequestIdCollection in the resulting NewRequestId‐
318 Collection. If Delete equals false, NewRequestIdCollection will
319 equal RequestIdCollection. Note that deleting an association is
320 not for free and that a collection containing already handled
321 requests can still be used by subsequent calls to check_re‐
322 sponse/3, receive_response/3, and wait_response/3. However,
323 without deleting handled associations, the above calls will not
324 be able to detect when there are no more outstanding requests to
325 handle, so you will have to keep track of this some other way
326 than relying on a no_request return. Note that if you pass a
327 collection only containing associations of already handled or
328 abandoned requests to check_response/3, it will always return
329 no_response.
330 Note that a response might have been consumed uppon an {erpc,
332 badarg} exception and if so, will be lost for ever.
333 multicall(Nodes, Fun) -> Result
335 multicall(Nodes, Fun, Timeout) -> Result
337 Types:
339 Nodes = [atom()]
341 Fun = function()
342 Timeout = timeout_time()
343 Result = term()
344 The same as calling erpc:multicall(Nodes, erlang, apply,
346 [Fun,[]], Timeout). May raise all the same exceptions as multi‐
347 call/5 plus an {erpc, badarg} error exception if Fun is not a
348 fun of zero arity.
349 The call erpc:multicall(Nodes,Fun) is the same as the call
351 erpc:multicall(Nodes,Fun, infinity).
352 multicall(Nodes, Module, Function, Args) -> Result
354 multicall(Nodes, Module, Function, Args, Timeout) -> Result
356 Types:
358 Nodes = [atom()]
360 Module = Function = atom()
361 Args = [term()]
362 Timeout = timeout_time()
363 Result =
364 [{ok, ReturnValue :: term()} | caught_call_exception()]
365 caught_call_exception() =
366 {throw, Throw :: term()} |
367 {exit, {exception, Reason :: term()}} |
368 {error,
369 {exception, Reason :: term(), StackTrace :: [stack_item()]}} |
370 {exit, {signal, Reason :: term()}} |
371 {error, {erpc, Reason :: term()}}
372 stack_item() =
373 {Module :: atom(),
374 Function :: atom(),
375 Arity :: arity() | (Args :: [term()]),
376 Location ::
377 [{file, Filename :: string()} |
378 {line, Line :: integer() >= 1}]}
379 Performs multiple call operations in parallel on multiple nodes.
381 That is, evaluates apply(Module, Function, Args) on the nodes
382 Nodes in parallel. Timeout sets an upper time limit for all call
383 operations to complete. The result is returned as a list where
384 the result from each node is placed at the same position as the
385 node name is placed in Nodes. Each item in the resulting list is
386 formatted as either:
387 {ok, Result}:
389 The call operation for this specific node returned Result.
390 {Class, ExceptionReason}:
392 The call operation for this specific node raised an excep‐
393 tion of class Class with exception reason ExceptionReason.
394 These correspond to the exceptions that call/5 can raise.
395 multicall/5 fails with an {erpc, badarg} error exception if:
397 * Nodes is not a proper list of atoms. Note that some requests
399 may already have been sent when the failure occurs. That is,
400 the function may or may not be applied on some nodes.
401 * Module is not an atom.
403 * Function is not an atom.
405 * Args is not a list. Note that the list is not verified to be
407 a proper list at the client side.
408 The call erpc:multicall(Nodes, Module, Function, Args) is equiv‐
410 alent to the call erpc:multicall(Nodes, Module, Function, Args,
411 infinity). These calls are also equivalent to calling my_multi‐
412 call(Nodes, Module, Function, Args) below if one disregard per‐
413 formance and failure behavior. multicall() can utilize a selec‐
414 tive receive optimization which removes the need to scan the
415 message queue from the beginning in order to find a matching
416 message. The send_request()/receive_response() combination can,
417 however, not utilize this optimization.
418 my_multicall(Nodes, Module, Function, Args) ->
420 ReqIds = lists:map(fun (Node) ->
421 erpc:send_request(Node, Module, Function, Args)
422 end,
423 Nodes),
424 lists:map(fun (ReqId) ->
425 try
426 {ok, erpc:receive_response(ReqId, infinity)}
427 catch
428 Class:Reason ->
429 {Class, Reason}
430 end
431 end,
432 ReqIds).
433 If an erpc operation fails, but it is unknown if the function
436 is/will be applied (that is, a timeout, connection loss, or an
437 improper Nodes list), the caller will not receive any further
438 information about the result if/when the applied function com‐
439 pletes. If the applied function communicates with the calling
440 process, such communication may, of course, reach the calling
441 process.
442 Note:
444 You cannot make any assumptions about the process that will per‐
445 form the apply(). It may be the calling process itself, a
446 server, or a freshly spawned process.
447 multicast(Nodes, Fun) -> ok
450 Types:
452 Nodes = [node()]
454 Fun = function()
455 The same as calling erpc:multicast(Nodes,erlang,apply,[Fun,[]]).
457 multicast/2 fails with an {erpc, badarg} error exception if:
459 * Nodes is not a proper list of atoms.
461 * Fun is not a a fun of zero arity.
463 multicast(Nodes, Module, Function, Args) -> ok
465 Types:
467 Nodes = [node()]
469 Module = Function = atom()
470 Args = [term()]
471 Evaluates apply(Module, Function, Args) on the nodes Nodes. No
473 response is delivered to the calling process. multicast() re‐
474 turns immediately after the cast requests have been sent. Any
475 failures beside bad arguments are silently ignored.
476 multicast/4 fails with an {erpc, badarg} error exception if:
478 * Nodes is not a proper list of atoms. Note that some requests
480 may already have been sent when the failure occurs. That is,
481 the function may or may not be applied on some nodes.
482 * Module is not an atom.
484 * Function is not an atom.
486 * Args is not a list. Note that the list is not verified to be
488 a proper list at the client side.
489 Note:
491 You cannot make any assumptions about the process that will per‐
492 form the apply(). It may be a server, or a freshly spawned
493 process.
494 receive_response(RequestId) -> Result
497 Types:
499 RequestId = request_id()
501 Result = term()
502 The same as calling erpc:receive_response(RequestId, infinity).
504 receive_response(RequestId, Timeout) -> Result
506 Types:
508 RequestId = request_id()
510 Timeout = timeout_time()
511 Result = term()
512 Receive a response to a call request previously made by the
514 calling process using send_request/4. RequestId should be the
515 value returned from the previously made send_request/4 call, and
516 the corresponding response should not already have been received
517 and handled to completion by receive_response(), check_re‐
518 sponse/4, or wait_response/4.
519 Timeout sets an upper time limit on how long to wait for a re‐
521 sponse. If the operation times out, the request identified by
522 RequestId will be abandoned, then an {erpc, timeout} error ex‐
523 ception will be raised. That is, no response corresponding to
524 the request will ever be received after a timeout. If a response
525 is received, the call operation is completed and either the re‐
526 sult is returned or an exception is raised. The exceptions that
527 can be raised corresponds to the same exceptions as can be
528 raised by call/5. receive_response/2 will fail with an {erpc,
529 badarg} exception if/when an invalid RequestId is detected or if
530 an invalid Timeout is passed.
531 A call to the function my_call(Node, Module, Function, Args,
533 Timeout) below is equivalent to the call erpc:call(Node, Module,
534 Function, Args, Timeout) if one disregards performance. call()
535 can utilize a selective receive optimization which removes the
536 need to scan the message queue from the beginning in order to
537 find a matching message. The send_request()/receive_response()
538 combination can, however, not utilize this optimization.
539 my_call(Node, Module, Function, Args, Timeout) ->
541 RequestId = erpc:send_request(Node, Module, Function, Args),
542 erpc:receive_response(RequestId, Timeout).
543 If the erpc operation fails, but it is unknown if the function
546 is/will be applied (that is, a timeout, or a connection loss),
547 the caller will not receive any further information about the
548 result if/when the applied function completes. If the applied
549 function explicitly communicates with the calling process, such
550 communication may, of course, reach the calling process.
551 receive_response(RequestIdCollection, Timeout, Delete) ->
553 {Result, Label, NewRequestIdCollection} |
554 no_request
555 Types:
557 RequestIdCollection = request_id_collection()
559 Timeout = timeout_time()
560 Delete = boolean()
561 Result = Label = term()
562 NewRequestIdCollection = request_id_collection()
563 Receive a response to a call request corresponding to a request
565 identifier saved in RequestIdCollection. All request identifiers
566 of RequestIdCollection must correspond to requests that have
567 been made using send_request/4 or send_request/6, and all re‐
568 quests must have been made by the process calling this function.
569 Label is the label associated with the request identifier of the
571 request that the response corresponds to. A request identifier
572 is associated with a label when adding a request identifier in a
573 request identifier collection, or when sending the request using
574 send_request/6.
575 Compared to receive_response/2, the returned result associated
577 with a specific request identifier or an exception associated
578 with a specific request identifier will be wrapped in a 3-tuple.
579 The first element of this tuple equals the value that would have
580 been produced by receive_response/2, the second element equals
581 the Label associated with the specific request identifier, and
582 the third element NewRequestIdCollection is a possibly modified
583 request identifier collection. The error exceptions {erpc,
584 badarg} and {erpc, timeout} are not associated with any specific
585 request identifiers, and will hence not be wrapped.
586 If RequestIdCollection is empty, the atom no_request will be re‐
588 turned.
589 If the operation times out, all requests identified by Re‐
591 questIdCollection will be abandoned, then an {erpc, timeout} er‐
592 ror exception will be raised. That is, no responses correspond‐
593 ing to any of the request identifiers in RequestIdCollection
594 will ever be received after a timeout. The difference between
595 receive_response/3 and wait_response/3 is that receive_re‐
596 sponse/3 abandons the requests at timeout so that any potential
597 future responses are ignored, while wait_response/3 does not.
598 If Delete equals true, the association with Label will have been
600 deleted from RequestIdCollection in the resulting NewRequestId‐
601 Collection. If Delete equals false, NewRequestIdCollection will
602 equal RequestIdCollection. Note that deleting an association is
603 not for free and that a collection containing already handled
604 requests can still be used by subsequent calls to receive_re‐
605 sponse/3, check_response/3, and wait_response/3. However, with‐
606 out deleting handled associations, the above calls will not be
607 able to detect when there are no more outstanding requests to
608 handle, so you will have to keep track of this some other way
609 than relying on a no_request return. Note that if you pass a
610 collection only containing associations of already handled or
611 abandoned requests to receive_response/3, it will always block
612 until a timeout determined by Timeout is triggered.
613 Note that a response might have been consumed uppon an {erpc,
615 badarg} exception and if so, will be lost for ever.
616 reqids_add(RequestId :: request_id(),
618 Label :: term(),
619 RequestIdCollection :: request_id_collection()) ->
620 NewRequestIdCollection :: request_id_collection()
621 Saves RequestId and associates a Label with the request identi‐
623 fier by adding this information to RequestIdCollection and re‐
624 turning the resulting request identifier collection.
625 reqids_new() -> NewRequestIdCollection :: request_id_collection()
627 Returns a new empty request identifier collection. A request
629 identifier collection can be utilized in order the handle multi‐
630 ple outstanding requests.
631 Request identifiers of requests made by send_request/4 can be
633 saved in a request identifier collection using reqids_add/3.
634 Such a collection of request identifiers can later be used in
635 order to get one response corresponding to a request in the col‐
636 lection by passing the collection as argument to check_re‐
637 sponse/3, receive_response/3, and wait_response/3.
638 reqids_size/1 can be used to determine the amount of request
640 identifiers in a request identifier collection.
641 reqids_size(RequestIdCollection :: request_id_collection()) ->
643 integer() >= 0
644 Returns the amount of request identifiers saved in RequestIdCol‐
646 lection.
647 reqids_to_list(RequestIdCollection :: request_id_collection()) ->
649 [{RequestId :: request_id(), Label :: term()}]
650 Returns a list of {RequestId, Label} tuples which corresponds to
652 all request identifiers with their associated labels present in
653 the RequestIdCollection collection.
654 send_request(Node, Fun) -> RequestId
656 Types:
658 Node = node()
660 Fun = function()
661 RequestId = request_id()
662 The same as calling erpc:send_request(Node, erlang, apply, [Fun,
664 []]).
665 Fails with an {erpc, badarg} error exception if:
667 * Node is not an atom.
669 * Fun is not a fun of zero arity.
671 Note:
673 You cannot make any assumptions about the process that will per‐
674 form the apply(). It may be a server, or a freshly spawned
675 process.
676 send_request(Node, Module, Function, Args) -> RequestId
679 Types:
681 Node = node()
683 Module = Function = atom()
684 Args = [term()]
685 RequestId = request_id()
686 Send an asynchronous call request to the node Node. send_re‐
688 quest/4 returns a request identifier that later is to be passed
689 to either receive_response/2, wait_response/2, or, check_re‐
690 sponse/2 in order to get the response of the call request. Be‐
691 sides passing the request identifier directly to these func‐
692 tions, it can also be added in a request identifier collection
693 using reqids_add/3. Such a collection of request identifiers can
694 later be used in order to get one response corresponding to a
695 request in the collection by passing the collection as argument
696 to receive_response/3, wait_response/3, or, check_response/3. If
697 you are about to save the request identifier in a request iden‐
698 tifier collection, you may want to consider using send_request/6
699 instead.
700 A call to the function my_call(Node, Module, Function, Args,
702 Timeout) below is equivalent to the call erpc:call(Node, Module,
703 Function, Args, Timeout) if one disregards performance. call()
704 can utilize a selective receive optimization which removes the
705 need to scan the message queue from the beginning in order to
706 find a matching message. The send_request()/receive_response()
707 combination can, however, not utilize this optimization.
708 my_call(Node, Module, Function, Args, Timeout) ->
710 RequestId = erpc:send_request(Node, Module, Function, Args),
711 erpc:receive_response(RequestId, Timeout).
712 Fails with an {erpc, badarg} error exception if:
715 * Node is not an atom.
717 * Module is not an atom.
719 * Function is not an atom.
721 * Args is not a list. Note that the list is not verified to be
723 a proper list at the client side.
724 Note:
726 You cannot make any assumptions about the process that will per‐
727 form the apply(). It may be a server, or a freshly spawned
728 process.
729 send_request(Node, Fun, Label, RequestIdCollection) ->
732 NewRequestIdCollection
733 Types:
735 Node = node()
737 Fun = function()
738 Label = term()
739 RequestIdCollection = NewRequestIdCollection = re‐
740 quest_id_collection()
741 The same as calling erpc:send_request(Node, erlang, apply,
743 [Fun,[]]), Label, RequestIdCollection).
744 Fails with an {erpc, badarg} error exception if:
746 * Node is not an atom.
748 * Fun is not a fun of zero arity.
750 * RequestIdCollection is detected not to be request identifier
752 collection.
753 Note:
755 You cannot make any assumptions about the process that will per‐
756 form the apply(). It may be a server, or a freshly spawned
757 process.
758 send_request(Node, Module, Function, Args, Label,
761 RequestIdCollection) ->
762 NewRequestIdCollection
763 Types:
765 Node = node()
767 Module = Function = atom()
768 Args = [term()]
769 Label = term()
770 RequestIdCollection = NewRequestIdCollection = re‐
771 quest_id_collection()
772 Send an asynchronous call request to the node Node. The Label
774 will be associated with the request identifier of the operation
775 and added to the returned request identifier collection NewRe‐
776 questIdCollection. The collection can later be used in order to
777 get one response corresponding to a request in the collection by
778 passing the collection as argument to receive_response/3,
779 wait_response/3, or, check_response/3.
780 The same as calling erpc:reqids_add(erpc:send_request(Node, Mod‐
782 ule, Function, Args), Label, RequestIdCollection), but calling
783 send_request/6 is slightly more efficient.
784 Fails with an {erpc, badarg} error exception if:
786 * Node is not an atom.
788 * Module is not an atom.
790 * Function is not an atom.
792 * Args is not a list. Note that the list is not verified to be
794 a proper list at the client side.
795 * RequestIdCollection is detected not to be request identifier
797 collection.
798 Note:
800 You cannot make any assumptions about the process that will per‐
801 form the apply(). It may be a server, or a freshly spawned
802 process.
803 wait_response(RequestId) -> {response, Result} | no_response
806 Types:
808 RequestId = request_id()
810 Result = term()
811 The same as calling erpc:wait_response(RequestId, 0). That is,
813 poll for a response message to a call request previously made by
814 the calling process.
815 wait_response(RequestId, WaitTime) ->
817 {response, Result} | no_response
818 Types:
820 RequestId = request_id()
822 WaitTime = timeout_time()
823 Result = term()
824 Wait or poll for a response message to a call request previously
826 made by the calling process using send_request/4. RequestId
827 should be the value returned from the previously made send_re‐
828 quest() call, and the corresponding response should not already
829 have been received and handled to completion by check_re‐
830 sponse/2, receive_response/2, or wait_response().
831 WaitTime sets an upper time limit on how long to wait for a re‐
833 sponse. If no response is received before the WaitTime timeout
834 has triggered, the atom no_response is returned. It is valid to
835 continue waiting for a response as many times as needed up until
836 a response has been received and completed by check_response(),
837 receive_response(), or wait_response(). If a response is re‐
838 ceived, the call operation is completed and either the result is
839 returned as {response, Result} where Result corresponds to the
840 value returned from the applied function or an exception is
841 raised. The exceptions that can be raised corresponds to the
842 same exceptions as can be raised by call/4. That is, no {erpc,
843 timeout} error exception can be raised. wait_response/2 will
844 fail with an {erpc, badarg} exception if/when an invalid Re‐
845 questId is detected or if an invalid WaitTime is passed.
846 If the erpc operation fails, but it is unknown if the function
848 is/will be applied (that is, a too large wait time value, or a
849 connection loss), the caller will not receive any further infor‐
850 mation about the result if/when the applied function completes.
851 If the applied function explicitly communicates with the calling
852 process, such communication may, of course, reach the calling
853 process.
854 wait_response(RequestIdCollection, WaitTime, Delete) ->
856 {{response, Result},
857 Label, NewRequestIdCollection} |
858 no_response | no_request
859 Types:
861 RequestIdCollection = request_id_collection()
863 WaitTime = timeout_time()
864 Delete = boolean()
865 Label = term()
866 NewRequestIdCollection = request_id_collection()
867 Result = term()
868 Wait or poll for a response to a call request corresponding to a
870 request identifier saved in RequestIdCollection. All request
871 identifiers of RequestIdCollection must correspond to requests
872 that have been made using send_request/4 or send_request/6, and
873 all requests must have been made by the process calling this
874 function.
875 Label is the label associated with the request identifier of the
877 request that the response corresponds to. A request identifier
878 is associated with a label when adding a request identifier in a
879 request identifier collection, or when sending the request using
880 send_request/6.
881 Compared to wait_response/2, the returned result associated with
883 a specific request identifier or an exception associated with a
884 specific request identifier will be wrapped in a 3-tuple. The
885 first element of this tuple equals the value that would have
886 been produced by wait_response/2, the second element equals the
887 Label associated with the specific request identifier, and the
888 third element NewRequestIdCollection is a possibly modified re‐
889 quest identifier collection. The error exception {erpc, badarg}
890 is not associated with any specific request identifier, and will
891 hence not be wrapped.
892 If RequestIdCollection is empty, no_request will be returned. If
894 no response is received before the WaitTime timeout has trig‐
895 gered, the atom no_response is returned. It is valid to continue
896 waiting for a response as many times as needed up until a re‐
897 sponse has been received and completed by check_response(), re‐
898 ceive_response(), or wait_response(). The difference between re‐
899 ceive_response/3 and wait_response/3 is that receive_response/3
900 abandons requests at timeout so that any potential future re‐
901 sponses are ignored, while wait_response/3 does not.
902 If Delete equals true, the association with Label will have been
904 deleted from RequestIdCollection in the resulting NewRequestId‐
905 Collection. If Delete equals false, NewRequestIdCollection will
906 equal RequestIdCollection. Note that deleting an association is
907 not for free and that a collection containing already handled
908 requests can still be used by subsequent calls to wait_re‐
909 sponse/3, check_response/3, and receive_response/3. However,
910 without deleting handled associations, the above calls will not
911 be able to detect when there are no more outstanding requests to
912 handle, so you will have to keep track of this some other way
913 than relying on a no_request return. Note that if you pass a
914 collection only containing associations of already handled or
915 abandoned requests to wait_response/3, it will always block un‐
916 til a timeout determined by WaitTime is triggered and then re‐
917 turn no_response.
918 Note that a response might have been consumed uppon an {erpc,
920 badarg} exception and if so, will be lost for ever.
921Ericsson AB kernel 9.1 erpc(3)