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

DATA TYPES

17       key()
18
19              As returned by async_call/4.
20

EXPORTS

22       abcast(Name, Msg) -> abcast
23
24              Types:
25
26                 Name = atom()
27                 Msg = term()
28
29              Equivalent to abcast([node()|nodes()], Name, Msg).
30
31       abcast(Nodes, Name, Msg) -> abcast
32
33              Types:
34
35                 Nodes = [node()]
36                 Name = atom()
37                 Msg = term()
38
39              Broadcasts the message  Msg  asynchronously  to  the  registered
40              process Name on the specified nodes.
41
42       async_call(Node, Module, Function, Args) -> Key
43
44              Types:
45
46                 Node = node()
47                 Module = module()
48                 Function = atom()
49                 Args = [term()]
50                 Key = key()
51
52              Implements  call  streams with promises, a type of RPC that does
53              not suspend the caller until the result is finished. Instead,  a
54              key  is  returned, which can be used later to collect the value.
55              The key can be viewed as a promise to deliver the answer.
56
57              In this case, the key Key is returned, which can be  used  in  a
58              subsequent call to yield/1 or nb_yield/1,2 to retrieve the value
59              of evaluating apply(Module, Function, Args) on node Node.
60
61          Note:
62              yield/1 and nb_yield/1,2 must be called by the same process from
63              which  this  function  was  made otherwise they will never yield
64              correctly.
65
66
67       block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
68
69              Types:
70
71                 Node = node()
72                 Module = module()
73                 Function = atom()
74                 Args = [term()]
75                 Res = Reason = term()
76
77              Same as call/4, but the RPC server at Node  does  not  create  a
78              separate  process to handle the call. Thus, this function can be
79              used if the intention of the call is to  block  the  RPC  server
80              from any other incoming requests until the request has been han‐
81              dled. The function can also be used for efficiency reasons  when
82              very  small fast functions are evaluated, for example, BIFs that
83              are guaranteed not to suspend.
84
85       block_call(Node, Module, Function, Args, Timeout) ->
86                     Res | {badrpc, Reason}
87
88              Types:
89
90                 Node = node()
91                 Module = module()
92                 Function = atom()
93                 Args = [term()]
94                 Res = Reason = term()
95                 Timeout = timeout()
96
97              Same as block_call/4, but with a time-out value in the same man‐
98              ner as call/5.
99
100       call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
101
102              Types:
103
104                 Node = node()
105                 Module = module()
106                 Function = atom()
107                 Args = [term()]
108                 Res = Reason = term()
109
110              Evaluates apply(Module, Function, Args) on node Node and returns
111              the corresponding value Res, or {badrpc,  Reason}  if  the  call
112              fails.
113
114       call(Node, Module, Function, Args, Timeout) ->
115               Res | {badrpc, Reason}
116
117              Types:
118
119                 Node = node()
120                 Module = module()
121                 Function = atom()
122                 Args = [term()]
123                 Res = Reason = term()
124                 Timeout = timeout()
125
126              Evaluates apply(Module, Function, Args) on node Node and returns
127              the corresponding value Res, or {badrpc,  Reason}  if  the  call
128              fails.  Timeout is a time-out value in milliseconds. If the call
129              times out, Reason is timeout.
130
131              If the reply arrives after the call times out, no  message  con‐
132              taminates  the  caller's  message queue, as this function spawns
133              off a middleman process to act as (a void) destination for  such
134              an  orphan  reply.  This  feature  also makes this function more
135              expensive than call/4 at the caller's end.
136
137       cast(Node, Module, Function, Args) -> true
138
139              Types:
140
141                 Node = node()
142                 Module = module()
143                 Function = atom()
144                 Args = [term()]
145
146              Evaluates  apply(Module,  Function,  Args)  on  node  Node.   No
147              response  is  delivered and the calling process is not suspended
148              until the evaluation is complete, as is the case with call/4,5.
149
150       eval_everywhere(Module, Function, Args) -> abcast
151
152              Types:
153
154                 Module = module()
155                 Function = atom()
156                 Args = [term()]
157
158              Equivalent to  eval_everywhere([node()|nodes()],  Module,  Func‐
159              tion, Args).
160
161       eval_everywhere(Nodes, Module, Function, Args) -> abcast
162
163              Types:
164
165                 Nodes = [node()]
166                 Module = module()
167                 Function = atom()
168                 Args = [term()]
169
170              Evaluates  apply(Module, Function, Args) on the specified nodes.
171              No answers are collected.
172
173       multi_server_call(Name, Msg) -> {Replies, BadNodes}
174
175              Types:
176
177                 Name = atom()
178                 Msg = term()
179                 Replies = [Reply :: term()]
180                 BadNodes = [node()]
181
182              Equivalent to multi_server_call([node()|nodes()], Name, Msg).
183
184       multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
185
186              Types:
187
188                 Nodes = [node()]
189                 Name = atom()
190                 Msg = term()
191                 Replies = [Reply :: term()]
192                 BadNodes = [node()]
193
194              Can be used when interacting with servers  called  Name  on  the
195              specified nodes. It is assumed that the servers receive messages
196              in the format {From, Msg} and reply using From  !  {Name,  Node,
197              Reply},  where  Node is the name of the node where the server is
198              located. The function returns {Replies, BadNodes}, where Replies
199              is  a  list of all Reply values, and BadNodes is one of the fol‐
200              lowing:
201
202                * A list of the nodes that do not exist
203
204                * A list of the nodes where the server does not exist
205
206                * A list of the nodes where the server terminated before send‐
207                  ing any reply.
208
209       multicall(Module, Function, Args) -> {ResL, BadNodes}
210
211              Types:
212
213                 Module = module()
214                 Function = atom()
215                 Args = [term()]
216                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
217                 BadNodes = [node()]
218
219              Equivalent   to  multicall([node()|nodes()],  Module,  Function,
220              Args, infinity).
221
222       multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
223
224              Types:
225
226                 Nodes = [node()]
227                 Module = module()
228                 Function = atom()
229                 Args = [term()]
230                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
231                 BadNodes = [node()]
232
233              Equivalent to multicall(Nodes, Module,  Function,  Args,  infin‐
234              ity).
235
236       multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
237
238              Types:
239
240                 Module = module()
241                 Function = atom()
242                 Args = [term()]
243                 Timeout = timeout()
244                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
245                 BadNodes = [node()]
246
247              Equivalent   to  multicall([node()|nodes()],  Module,  Function,
248              Args, Timeout).
249
250       multicall(Nodes, Module, Function, Args, Timeout) ->
251                    {ResL, BadNodes}
252
253              Types:
254
255                 Nodes = [node()]
256                 Module = module()
257                 Function = atom()
258                 Args = [term()]
259                 Timeout = timeout()
260                 ResL = [Res :: term() | {badrpc, Reason :: term()}]
261                 BadNodes = [node()]
262
263              In contrast to an RPC, a multicall is an RPC that is  sent  con‐
264              currently  from  one  client to multiple servers. This is useful
265              for collecting information from a set of nodes, or for calling a
266              function  on  a set of nodes to achieve some side effects. It is
267              semantically the same as iteratively making a series of RPCs  on
268              all  the nodes, but the multicall is faster, as all the requests
269              are sent at the same time and are collected one by one  as  they
270              come back.
271
272              The  function  evaluates  apply(Module,  Function,  Args) on the
273              specified nodes and collects  the  answers.  It  returns  {ResL,
274              BadNodes},  where  BadNodes  is  a list of the nodes that do not
275              exist, and ResL is a list of the return values, or {badrpc, Rea‐
276              son} for failing calls. Timeout is a time (integer) in millisec‐
277              onds, or infinity.
278
279              The following example is useful when new object code  is  to  be
280              loaded  on  all  nodes  in  the network, and indicates some side
281              effects that RPCs can produce:
282
283              %% Find object code for module Mod
284              {Mod, Bin, File} = code:get_object_code(Mod),
285
286              %% and load it on all nodes including this one
287              {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
288
289              %% and then maybe check the ResL list.
290
291       nb_yield(Key) -> {value, Val} | timeout
292
293              Types:
294
295                 Key = key()
296                 Val = (Res :: term()) | {badrpc, Reason :: term()}
297
298              Equivalent to nb_yield(Key, 0).
299
300       nb_yield(Key, Timeout) -> {value, Val} | timeout
301
302              Types:
303
304                 Key = key()
305                 Timeout = timeout()
306                 Val = (Res :: term()) | {badrpc, Reason :: term()}
307
308              Non-blocking version of yield/1. It returns  the  tuple  {value,
309              Val}  when  the computation is finished, or timeout when Timeout
310              milliseconds has elapsed.
311
312          Note:
313              This function must be called by  the  same  process  from  which
314              async_call/4 was made otherwise it will only return timeout.
315
316
317       parallel_eval(FuncCalls) -> ResL
318
319              Types:
320
321                 FuncCalls = [{Module, Function, Args}]
322                 Module = module()
323                 Function = atom()
324                 Args = ResL = [term()]
325
326              Evaluates, for every tuple in FuncCalls, apply(Module, Function,
327              Args) on some node in the network. Returns the  list  of  return
328              values, in the same order as in FuncCalls.
329
330       pinfo(Pid) -> [{Item, Info}] | undefined
331
332              Types:
333
334                 Pid = pid()
335                 Item = atom()
336                 Info = term()
337
338              Location transparent version of the BIF erlang:process_info/1 in
339              ERTS.
340
341       pinfo(Pid, Item) -> {Item, Info} | undefined | []
342
343       pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
344
345              Types:
346
347                 Pid = pid()
348                 Item = atom()
349                 ItemList = [Item]
350                 Info = term()
351
352              Location transparent version of the BIF erlang:process_info/2 in
353              ERTS.
354
355       pmap(FuncSpec, ExtraArgs, List1) -> List2
356
357              Types:
358
359                 FuncSpec = {Module, Function}
360                 Module = module()
361                 Function = atom()
362                 ExtraArgs = [term()]
363                 List1 = [Elem :: term()]
364                 List2 = [term()]
365
366              Evaluates  apply(Module,  Function,  [Elem|ExtraArgs]) for every
367              element Elem in List1, in parallel. Returns the list  of  return
368              values, in the same order as in List1.
369
370       sbcast(Name, Msg) -> {GoodNodes, BadNodes}
371
372              Types:
373
374                 Name = atom()
375                 Msg = term()
376                 GoodNodes = BadNodes = [node()]
377
378              Equivalent to sbcast([node()|nodes()], Name, Msg).
379
380       sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
381
382              Types:
383
384                 Name = atom()
385                 Msg = term()
386                 Nodes = GoodNodes = BadNodes = [node()]
387
388              Broadcasts  the  message  Msg  synchronously  to  the registered
389              process Name on the specified nodes.
390
391              Returns {GoodNodes, BadNodes}, where GoodNodes is  the  list  of
392              nodes that have Name as a registered process.
393
394              The  function  is synchronous in the sense that it is known that
395              all servers have received the message when the call returns.  It
396              is not possible to know that the servers have processed the mes‐
397              sage.
398
399              Any further messages sent to the servers,  after  this  function
400              has returned, are received by all servers after this message.
401
402       server_call(Node, Name, ReplyWrapper, Msg) ->
403                      Reply | {error, Reason}
404
405              Types:
406
407                 Node = node()
408                 Name = atom()
409                 ReplyWrapper = Msg = Reply = term()
410                 Reason = nodedown
411
412              Can  be  used when interacting with a server called Name on node
413              Node. It is assumed that the server  receives  messages  in  the
414              format {From, Msg} and replies using From ! {ReplyWrapper, Node,
415              Reply}. This function makes such a server call and ensures  that
416              the  entire  call  is  packed  into an atomic transaction, which
417              either succeeds or fails. It  never  hangs,  unless  the  server
418              itself hangs.
419
420              The  function returns the answer Reply as produced by the server
421              Name, or {error, Reason}.
422
423       yield(Key) -> Res | {badrpc, Reason}
424
425              Types:
426
427                 Key = key()
428                 Res = Reason = term()
429
430              Returns the promised answer from a previous async_call/4. If the
431              answer  is available, it is returned immediately. Otherwise, the
432              calling process is suspended until the answer arrives from Node.
433
434          Note:
435              This function must be called by  the  same  process  from  which
436              async_call/4 was made otherwise it will never return.
437
438
439
440
441Ericsson AB                     kernel 6.3.1.1                          rpc(3)
Impressum