1rpc(3)                     Erlang Module Definition                     rpc(3)
2
3
4

NAME

6       rpc - Remote Procedure Call services.
7

DESCRIPTION

9       This  module  contains  services  similar to Remote Procedure Calls. It
10       also contains broadcast facilities and parallel  evaluators.  A  remote
11       procedure call is a method to call a function on a remote node and col‐
12       lect the answer. It is used for  collecting  information  on  a  remote
13       node,  or for running a function with some specific side effects on the
14       remote node.
15
16   Note:
17       rpc:call() and friends makes it quite hard to distinguish between  suc‐
18       cessful  results,  raised  exceptions, and other errors. This cannot be
19       changed due to compatibility reasons. As of OTP 23, a new  module  erpc
20       was  introduced  in  order  to provide an API that makes it possible to
21       distinguish between the different results. The erpc module  provides  a
22       subset  (however, the central subset) of the functionality available in
23       the rpc module. The erpc implementation also provides a  more  scalable
24       implementation  with better performance than the original rpc implemen‐
25       tation. However, since the introduction of erpc, the rpc module  imple‐
26       ments  large  parts of its central functionality using erpc, so the rpc
27       module won't not suffer scalability wise and performance wise  compared
28       to erpc.
29
30

DATA TYPES

32       key()
33
34              Opaque value returned by async_call/4.
35

EXPORTS

37       abcast(Name, Msg) -> abcast
38
39              Types:
40
41                 Name = atom()
42                 Msg = term()
43
44              Equivalent to abcast([node()|nodes()], Name, Msg).
45
46       abcast(Nodes, Name, Msg) -> abcast
47
48              Types:
49
50                 Nodes = [node()]
51                 Name = atom()
52                 Msg = term()
53
54              Broadcasts  the  message  Msg  asynchronously  to the registered
55              process Name on the specified nodes.
56
57       async_call(Node, Module, Function, Args) -> Key
58
59              Types:
60
61                 Node = node()
62                 Module = module()
63                 Function = atom()
64                 Args = [term()]
65                 Key = key()
66
67              Implements call streams with promises, a type of RPC  that  does
68              not  suspend the caller until the result is finished. Instead, a
69              key is returned, which can be used later to collect  the  value.
70              The key can be viewed as a promise to deliver the answer.
71
72              In  this  case,  the key Key is returned, which can be used in a
73              subsequent call to yield/1 or nb_yield/1,2 to retrieve the value
74              of evaluating apply(Module, Function, Args) on node Node.
75
76          Note:
77              If  you want the ability to distinguish between results, you may
78              want to consider using the erpc:send_request() function from the
79              erpc  module  instead.  This also gives you the ability retrieve
80              the results in other useful ways.
81
82
83          Note:
84              yield/1 and nb_yield/1,2 must be called by the same process from
85              which  this  function  was  made otherwise they will never yield
86              correctly.
87
88
89          Note:
90              You cannot make any assumptions about the process that will per‐
91              form  the apply(). It may be an rpc server, another server, or a
92              freshly spawned process.
93
94
95       block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
96
97              Types:
98
99                 Node = node()
100                 Module = module()
101                 Function = atom()
102                 Args = [term()]
103                 Res = Reason = term()
104
105              The same as calling rpc:block_call(Node, Module, Function, Args,
106              infinity).
107
108       block_call(Node, Module, Function, Args, Timeout) ->
109                     Res | {badrpc, Reason}
110
111              Types:
112
113                 Node = node()
114                 Module = module()
115                 Function = atom()
116                 Args = [term()]
117                 Res = Reason = term()
118                 Timeout = 0..4294967295 | infinity
119
120              The same as calling rpc:call(Node, Module, Function, Args, Time‐
121              out)  with   the   exception   that   it   also   blocks   other
122              rpc:block_call()  operations  from executing concurrently on the
123              node Node.
124
125          Warning:
126              Note  that  it  also   blocks   other   operations   than   just
127              rpc:block_call() operations, so use it with care.
128
129
130       call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
131
132              Types:
133
134                 Node = node()
135                 Module = module()
136                 Function = atom()
137                 Args = [term()]
138                 Res = Reason = term()
139
140              Evaluates apply(Module, Function, Args) on node Node and returns
141              the corresponding value Res, or {badrpc,  Reason}  if  the  call
142              fails.  The  same  as  calling  rpc:call(Node, Module, Function,
143              Args, infinity).
144
145       call(Node, Module, Function, Args, Timeout) ->
146               Res | {badrpc, Reason}
147
148              Types:
149
150                 Node = node()
151                 Module = module()
152                 Function = atom()
153                 Args = [term()]
154                 Res = Reason = term()
155                 Timeout = 0..4294967295 | infinity
156
157              Evaluates apply(Module, Function, Args) on node Node and returns
158              the  corresponding  value  Res,  or {badrpc, Reason} if the call
159              fails. Timeout is a time-out value in milliseconds. If the  call
160              times out, Reason is timeout.
161
162              If  the  reply arrives after the call times out, no message con‐
163              taminates the caller's message queue.
164
165          Note:
166              If you want the ability to distinguish between results, you  may
167              want  to  consider  using the erpc:call() function from the erpc
168              module instead.
169
170
171          Note:
172              Here follows the details of what exactly is returned.
173
174              {badrpc, Reason} will  be  returned  in  the  following  circum‐
175              stances:
176
177                * The called function fails with an exit exception.
178
179                * The called function fails with an error exception.
180
181                * The called function returns a term that matches {'EXIT', _}.
182
183                * The called function throws a term that matches {'EXIT', _}.
184
185              Res is returned in the following circumstances:
186
187                * The  called  function returns normally with a term that does
188                  not  match {'EXIT',_}.
189
190                * The called function throws  a  term  that  does  not   match
191                  {'EXIT',_}.
192
193          Note:
194              You cannot make any assumptions about the process that will per‐
195              form the apply(). It may be the calling process itself,  an  rpc
196              server, another server, or a freshly spawned process.
197
198
199       cast(Node, Module, Function, Args) -> true
200
201              Types:
202
203                 Node = node()
204                 Module = module()
205                 Function = atom()
206                 Args = [term()]
207
208              Evaluates  apply(Module,  Function,  Args)  on node Node. No re‐
209              sponse is delivered and the calling process is not suspended un‐
210              til the evaluation is complete, as is the case with call/4,5.
211
212          Note:
213              You cannot make any assumptions about the process that will per‐
214              form the apply(). It may be an rpc server, another server, or  a
215              freshly spawned process.
216
217
218       eval_everywhere(Module, Function, Args) -> abcast
219
220              Types:
221
222                 Module = module()
223                 Function = atom()
224                 Args = [term()]
225
226              Equivalent  to  eval_everywhere([node()|nodes()],  Module, Func‐
227              tion, Args).
228
229       eval_everywhere(Nodes, Module, Function, Args) -> abcast
230
231              Types:
232
233                 Nodes = [node()]
234                 Module = module()
235                 Function = atom()
236                 Args = [term()]
237
238              Evaluates apply(Module, Function, Args) on the specified  nodes.
239              No answers are collected.
240
241       multi_server_call(Name, Msg) -> {Replies, BadNodes}
242
243              Types:
244
245                 Name = atom()
246                 Msg = term()
247                 Replies = [Reply :: term()]
248                 BadNodes = [node()]
249
250              Equivalent to multi_server_call([node()|nodes()], Name, Msg).
251
252       multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
253
254              Types:
255
256                 Nodes = [node()]
257                 Name = atom()
258                 Msg = term()
259                 Replies = [Reply :: term()]
260                 BadNodes = [node()]
261
262              Can  be  used  when  interacting with servers called Name on the
263              specified nodes. It is assumed that the servers receive messages
264              in  the  format  {From, Msg} and reply using From ! {Name, Node,
265              Reply}, where Node is the name of the node where the  server  is
266              located. The function returns {Replies, BadNodes}, where Replies
267              is a list of all Reply values, and BadNodes is one of  the  fol‐
268              lowing:
269
270                * A list of the nodes that do not exist
271
272                * A list of the nodes where the server does not exist
273
274                * A list of the nodes where the server terminated before send‐
275                  ing any reply.
276
277       multicall(Module, Function, Args) -> {ResL, BadNodes}
278
279              Types:
280
281                 Module = module()
282                 Function = atom()
283                 Args = [term()]
284                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
285                 BadNodes = [node()]
286
287              Equivalent  to  multicall([node()|nodes()],  Module,   Function,
288              Args, infinity).
289
290       multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
291
292              Types:
293
294                 Nodes = [node()]
295                 Module = module()
296                 Function = atom()
297                 Args = [term()]
298                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
299                 BadNodes = [node()]
300
301              Equivalent  to  multicall(Nodes,  Module, Function, Args, infin‐
302              ity).
303
304       multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
305
306              Types:
307
308                 Module = module()
309                 Function = atom()
310                 Args = [term()]
311                 Timeout = 0..4294967295 | infinity
312                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
313                 BadNodes = [node()]
314
315              Equivalent  to  multicall([node()|nodes()],  Module,   Function,
316              Args, Timeout).
317
318       multicall(Nodes, Module, Function, Args, Timeout) ->
319                    {ResL, BadNodes}
320
321              Types:
322
323                 Nodes = [node()]
324                 Module = module()
325                 Function = atom()
326                 Args = [term()]
327                 Timeout = 0..4294967295 | infinity
328                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
329                 BadNodes = [node()]
330
331              In  contrast  to an RPC, a multicall is an RPC that is sent con‐
332              currently from one client to multiple servers.  This  is  useful
333              for collecting information from a set of nodes, or for calling a
334              function on a set of nodes to achieve some side effects.  It  is
335              semantically  the same as iteratively making a series of RPCs on
336              all the nodes, but the multicall is faster, as all the  requests
337              are  sent  at the same time and are collected one by one as they
338              come back.
339
340              The function evaluates  apply(Module,  Function,  Args)  on  the
341              specified  nodes  and  collects  the  answers. It returns {ResL,
342              BadNodes}, where BadNodes is a list of the nodes that do not ex‐
343              ist,  and  ResL is a list of the return values, or {badrpc, Rea‐
344              son} for failing calls. Timeout is a time (integer) in millisec‐
345              onds, or infinity.
346
347              The  following  example  is useful when new object code is to be
348              loaded on all nodes in the network, and indicates some side  ef‐
349              fects that RPCs can produce:
350
351              %% Find object code for module Mod
352              {Mod, Bin, File} = code:get_object_code(Mod),
353
354              %% and load it on all nodes including this one
355              {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
356
357              %% and then maybe check the ResL list.
358
359          Note:
360              If  you want the ability to distinguish between results, you may
361              want to consider using the erpc:multicall()  function  from  the
362              erpc module instead.
363
364
365          Note:
366              You cannot make any assumptions about the process that will per‐
367              form the apply(). It may be the calling process itself,  an  rpc
368              server, another server, or a freshly spawned process.
369
370
371       nb_yield(Key) -> {value, Val} | timeout
372
373              Types:
374
375                 Key = key()
376                 Val = (Res :: term()) | {badrpc, Reason :: term()}
377
378              Equivalent to nb_yield(Key, 0).
379
380       nb_yield(Key, Timeout) -> {value, Val} | timeout
381
382              Types:
383
384                 Key = key()
385                 Timeout = 0..4294967295 | infinity
386                 Val = (Res :: term()) | {badrpc, Reason :: term()}
387
388              Non-blocking  version  of  yield/1. It returns the tuple {value,
389              Val} when the computation is finished, or timeout  when  Timeout
390              milliseconds has elapsed.
391
392              See the note in call/4 for more details of Val.
393
394          Note:
395              This  function  must  be  called  by the same process from which
396              async_call/4 was made otherwise it will only return timeout.
397
398
399       parallel_eval(FuncCalls) -> ResL
400
401              Types:
402
403                 FuncCalls = [{Module, Function, Args}]
404                 Module = module()
405                 Function = atom()
406                 Args = ResL = [term()]
407
408              Evaluates, for every tuple in FuncCalls, apply(Module, Function,
409              Args)  on  some  node in the network. Returns the list of return
410              values, in the same order as in FuncCalls.
411
412       pinfo(Pid) -> [{Item, Info}] | undefined
413
414              Types:
415
416                 Pid = pid()
417                 Item = atom()
418                 Info = term()
419
420              Location transparent version of the BIF erlang:process_info/1 in
421              ERTS.
422
423       pinfo(Pid, Item) -> {Item, Info} | undefined | []
424
425       pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
426
427              Types:
428
429                 Pid = pid()
430                 Item = atom()
431                 ItemList = [Item]
432                 Info = term()
433
434              Location transparent version of the BIF erlang:process_info/2 in
435              ERTS.
436
437       pmap(FuncSpec, ExtraArgs, List1) -> List2
438
439              Types:
440
441                 FuncSpec = {Module, Function}
442                 Module = module()
443                 Function = atom()
444                 ExtraArgs = [term()]
445                 List1 = [Elem :: term()]
446                 List2 = [term()]
447
448              Evaluates apply(Module, Function,  [Elem|ExtraArgs])  for  every
449              element  Elem  in List1, in parallel. Returns the list of return
450              values, in the same order as in List1.
451
452       sbcast(Name, Msg) -> {GoodNodes, BadNodes}
453
454              Types:
455
456                 Name = atom()
457                 Msg = term()
458                 GoodNodes = BadNodes = [node()]
459
460              Equivalent to sbcast([node()|nodes()], Name, Msg).
461
462       sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
463
464              Types:
465
466                 Name = atom()
467                 Msg = term()
468                 Nodes = GoodNodes = BadNodes = [node()]
469
470              Broadcasts the  message  Msg  synchronously  to  the  registered
471              process Name on the specified nodes.
472
473              Returns  {GoodNodes,  BadNodes},  where GoodNodes is the list of
474              nodes that have Name as a registered process.
475
476              The function is synchronous in the sense that it is  known  that
477              all  servers have received the message when the call returns. It
478              is not possible to know that the servers have processed the mes‐
479              sage.
480
481              Any  further  messages  sent to the servers, after this function
482              has returned, are received by all servers after this message.
483
484       server_call(Node, Name, ReplyWrapper, Msg) ->
485                      Reply | {error, Reason}
486
487              Types:
488
489                 Node = node()
490                 Name = atom()
491                 ReplyWrapper = Msg = Reply = term()
492                 Reason = nodedown
493
494              Can be used when interacting with a server called Name  on  node
495              Node.  It  is  assumed  that the server receives messages in the
496              format {From, Msg} and replies using From ! {ReplyWrapper, Node,
497              Reply}.  This function makes such a server call and ensures that
498              the entire call is packed into an atomic transaction, which  ei‐
499              ther succeeds or fails. It never hangs, unless the server itself
500              hangs.
501
502              The function returns the answer Reply as produced by the  server
503              Name, or {error, Reason}.
504
505       yield(Key) -> Res | {badrpc, Reason}
506
507              Types:
508
509                 Key = key()
510                 Res = Reason = term()
511
512              Returns the promised answer from a previous async_call/4. If the
513              answer is available, it is returned immediately. Otherwise,  the
514              calling process is suspended until the answer arrives from Node.
515
516          Note:
517              This  function  must  be  called  by the same process from which
518              async_call/4 was made otherwise it will never return.
519
520
521              See the note in call/4 for more details of the return value.
522
523
524
525Ericsson AB                     kernel 8.5.4.2                          rpc(3)
Impressum