1rpc(3) Erlang Module Definition rpc(3)
2
6 rpc - Remote Procedure Call services.
7
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 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 Note:
32 For some important information about distributed signals, see the
33 Blocking Signaling Over Distribution section in the Processes chapter
34 of the Erlang Reference Manual . Blocking signaling can, for example,
35 cause timeouts in rpc to be significantly delayed.
36
39 key()
40 Opaque value returned by async_call/4.
42
44 abcast(Name, Msg) -> abcast
45 Types:
47 Name = atom()
49 Msg = term()
50 Equivalent to abcast([node()|nodes()], Name, Msg).
52 abcast(Nodes, Name, Msg) -> abcast
54 Types:
56 Nodes = [node()]
58 Name = atom()
59 Msg = term()
60 Broadcasts the message Msg asynchronously to the registered
62 process Name on the specified nodes.
63 async_call(Node, Module, Function, Args) -> Key
65 Types:
67 Node = node()
69 Module = module()
70 Function = atom()
71 Args = [term()]
72 Key = key()
73 Implements call streams with promises, a type of RPC that does
75 not suspend the caller until the result is finished. Instead, a
76 key is returned, which can be used later to collect the value.
77 The key can be viewed as a promise to deliver the answer.
78 In this case, the key Key is returned, which can be used in a
80 subsequent call to yield/1 or nb_yield/1,2 to retrieve the value
81 of evaluating apply(Module, Function, Args) on node Node.
82 Note:
84 If you want the ability to distinguish between results, you may
85 want to consider using the erpc:send_request() function from the
86 erpc module instead. This also gives you the ability retrieve
87 the results in other useful ways.
88 Note:
91 yield/1 and nb_yield/1,2 must be called by the same process from
92 which this function was made otherwise they will never yield
93 correctly.
94 Note:
97 You cannot make any assumptions about the process that will per‐
98 form the apply(). It may be an rpc server, another server, or a
99 freshly spawned process.
100 block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
103 Types:
105 Node = node()
107 Module = module()
108 Function = atom()
109 Args = [term()]
110 Res = Reason = term()
111 The same as calling rpc:block_call(Node, Module, Function, Args,
113 infinity).
114 block_call(Node, Module, Function, Args, Timeout) ->
116 Res | {badrpc, Reason}
117 Types:
119 Node = node()
121 Module = module()
122 Function = atom()
123 Args = [term()]
124 Res = Reason = term()
125 Timeout = 0..4294967295 | infinity
126 The same as calling rpc:call(Node, Module, Function, Args, Time‐
128 out) with the exception that it also blocks other
129 rpc:block_call() operations from executing concurrently on the
130 node Node.
131 Warning:
133 Note that it also blocks other operations than just
134 rpc:block_call() operations, so use it with care.
135 call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
138 Types:
140 Node = node()
142 Module = module()
143 Function = atom()
144 Args = [term()]
145 Res = Reason = term()
146 Evaluates apply(Module, Function, Args) on node Node and returns
148 the corresponding value Res, or {badrpc, Reason} if the call
149 fails. The same as calling rpc:call(Node, Module, Function,
150 Args, infinity).
151 call(Node, Module, Function, Args, Timeout) ->
153 Res | {badrpc, Reason}
154 Types:
156 Node = node()
158 Module = module()
159 Function = atom()
160 Args = [term()]
161 Res = Reason = term()
162 Timeout = 0..4294967295 | infinity
163 Evaluates apply(Module, Function, Args) on node Node and returns
165 the corresponding value Res, or {badrpc, Reason} if the call
166 fails. Timeout is a time-out value in milliseconds. If the call
167 times out, Reason is timeout.
168 If the reply arrives after the call times out, no message con‐
170 taminates the caller's message queue.
171 Note:
173 If you want the ability to distinguish between results, you may
174 want to consider using the erpc:call() function from the erpc
175 module instead.
176 Note:
179 Here follows the details of what exactly is returned.
180 {badrpc, Reason} will be returned in the following circum‐
182 stances:
183 * The called function fails with an exit exception.
185 * The called function fails with an error exception.
187 * The called function returns a term that matches {'EXIT', _}.
189 * The called function throws a term that matches {'EXIT', _}.
191 Res is returned in the following circumstances:
193 * The called function returns normally with a term that does
195 not match {'EXIT',_}.
196 * The called function throws a term that does not match
198 {'EXIT',_}.
199 Note:
201 You cannot make any assumptions about the process that will per‐
202 form the apply(). It may be the calling process itself, an rpc
203 server, another server, or a freshly spawned process.
204 cast(Node, Module, Function, Args) -> true
207 Types:
209 Node = node()
211 Module = module()
212 Function = atom()
213 Args = [term()]
214 Evaluates apply(Module, Function, Args) on node Node. No re‐
216 sponse is delivered and the calling process is not suspended un‐
217 til the evaluation is complete, as is the case with call/4,5.
218 Note:
220 You cannot make any assumptions about the process that will per‐
221 form the apply(). It may be an rpc server, another server, or a
222 freshly spawned process.
223 eval_everywhere(Module, Function, Args) -> abcast
226 Types:
228 Module = module()
230 Function = atom()
231 Args = [term()]
232 Equivalent to eval_everywhere([node()|nodes()], Module, Func‐
234 tion, Args).
235 eval_everywhere(Nodes, Module, Function, Args) -> abcast
237 Types:
239 Nodes = [node()]
241 Module = module()
242 Function = atom()
243 Args = [term()]
244 Evaluates apply(Module, Function, Args) on the specified nodes.
246 No answers are collected.
247 multi_server_call(Name, Msg) -> {Replies, BadNodes}
249 Types:
251 Name = atom()
253 Msg = term()
254 Replies = [Reply :: term()]
255 BadNodes = [node()]
256 Equivalent to multi_server_call([node()|nodes()], Name, Msg).
258 multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
260 Types:
262 Nodes = [node()]
264 Name = atom()
265 Msg = term()
266 Replies = [Reply :: term()]
267 BadNodes = [node()]
268 Can be used when interacting with servers called Name on the
270 specified nodes. It is assumed that the servers receive messages
271 in the format {From, Msg} and reply using From ! {Name, Node,
272 Reply}, where Node is the name of the node where the server is
273 located. The function returns {Replies, BadNodes}, where Replies
274 is a list of all Reply values, and BadNodes is one of the fol‐
275 lowing:
276 * A list of the nodes that do not exist
278 * A list of the nodes where the server does not exist
280 * A list of the nodes where the server terminated before send‐
282 ing any reply.
283 multicall(Module, Function, Args) -> {ResL, BadNodes}
285 Types:
287 Module = module()
289 Function = atom()
290 Args = [term()]
291 ResL = [Res :: term() | {badrpc, Reason :: term()}]
292 BadNodes = [node()]
293 Equivalent to multicall([node()|nodes()], Module, Function,
295 Args, infinity).
296 multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
298 Types:
300 Nodes = [node()]
302 Module = module()
303 Function = atom()
304 Args = [term()]
305 ResL = [Res :: term() | {badrpc, Reason :: term()}]
306 BadNodes = [node()]
307 Equivalent to multicall(Nodes, Module, Function, Args, infin‐
309 ity).
310 multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
312 Types:
314 Module = module()
316 Function = atom()
317 Args = [term()]
318 Timeout = 0..4294967295 | infinity
319 ResL = [Res :: term() | {badrpc, Reason :: term()}]
320 BadNodes = [node()]
321 Equivalent to multicall([node()|nodes()], Module, Function,
323 Args, Timeout).
324 multicall(Nodes, Module, Function, Args, Timeout) ->
326 {ResL, BadNodes}
327 Types:
329 Nodes = [node()]
331 Module = module()
332 Function = atom()
333 Args = [term()]
334 Timeout = 0..4294967295 | infinity
335 ResL = [Res :: term() | {badrpc, Reason :: term()}]
336 BadNodes = [node()]
337 In contrast to an RPC, a multicall is an RPC that is sent con‐
339 currently from one client to multiple servers. This is useful
340 for collecting information from a set of nodes, or for calling a
341 function on a set of nodes to achieve some side effects. It is
342 semantically the same as iteratively making a series of RPCs on
343 all the nodes, but the multicall is faster, as all the requests
344 are sent at the same time and are collected one by one as they
345 come back.
346 The function evaluates apply(Module, Function, Args) on the
348 specified nodes and collects the answers. It returns {ResL,
349 BadNodes}, where BadNodes is a list of the nodes that do not ex‐
350 ist, and ResL is a list of the return values, or {badrpc, Rea‐
351 son} for failing calls. Timeout is a time (integer) in millisec‐
352 onds, or infinity.
353 The following example is useful when new object code is to be
355 loaded on all nodes in the network, and indicates some side ef‐
356 fects that RPCs can produce:
357 %% Find object code for module Mod
359 {Mod, Bin, File} = code:get_object_code(Mod),
360 %% and load it on all nodes including this one
362 {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
363 %% and then maybe check the ResL list.
365 Note:
367 If you want the ability to distinguish between results, you may
368 want to consider using the erpc:multicall() function from the
369 erpc module instead.
370 Note:
373 You cannot make any assumptions about the process that will per‐
374 form the apply(). It may be the calling process itself, an rpc
375 server, another server, or a freshly spawned process.
376 nb_yield(Key) -> {value, Val} | timeout
379 Types:
381 Key = key()
383 Val = (Res :: term()) | {badrpc, Reason :: term()}
384 Equivalent to nb_yield(Key, 0).
386 nb_yield(Key, Timeout) -> {value, Val} | timeout
388 Types:
390 Key = key()
392 Timeout = 0..4294967295 | infinity
393 Val = (Res :: term()) | {badrpc, Reason :: term()}
394 Non-blocking version of yield/1. It returns the tuple {value,
396 Val} when the computation is finished, or timeout when Timeout
397 milliseconds has elapsed.
398 See the note in call/4 for more details of Val.
400 Note:
402 This function must be called by the same process from which
403 async_call/4 was made otherwise it will only return timeout.
404 parallel_eval(FuncCalls) -> ResL
407 Types:
409 FuncCalls = [{Module, Function, Args}]
411 Module = module()
412 Function = atom()
413 Args = ResL = [term()]
414 Evaluates, for every tuple in FuncCalls, apply(Module, Function,
416 Args) on some node in the network. Returns the list of return
417 values, in the same order as in FuncCalls.
418 pinfo(Pid) -> [{Item, Info}] | undefined
420 Types:
422 Pid = pid()
424 Item = atom()
425 Info = term()
426 Location transparent version of the BIF erlang:process_info/1 in
428 ERTS.
429 pinfo(Pid, Item) -> {Item, Info} | undefined | []
431 pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
433 Types:
435 Pid = pid()
437 Item = atom()
438 ItemList = [Item]
439 Info = term()
440 Location transparent version of the BIF erlang:process_info/2 in
442 ERTS.
443 pmap(FuncSpec, ExtraArgs, List1) -> List2
445 Types:
447 FuncSpec = {Module, Function}
449 Module = module()
450 Function = atom()
451 ExtraArgs = [term()]
452 List1 = [Elem :: term()]
453 List2 = [term()]
454 Evaluates apply(Module, Function, [Elem|ExtraArgs]) for every
456 element Elem in List1, in parallel. Returns the list of return
457 values, in the same order as in List1.
458 sbcast(Name, Msg) -> {GoodNodes, BadNodes}
460 Types:
462 Name = atom()
464 Msg = term()
465 GoodNodes = BadNodes = [node()]
466 Equivalent to sbcast([node()|nodes()], Name, Msg).
468 sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
470 Types:
472 Name = atom()
474 Msg = term()
475 Nodes = GoodNodes = BadNodes = [node()]
476 Broadcasts the message Msg synchronously to the registered
478 process Name on the specified nodes.
479 Returns {GoodNodes, BadNodes}, where GoodNodes is the list of
481 nodes that have Name as a registered process.
482 The function is synchronous in the sense that it is known that
484 all servers have received the message when the call returns. It
485 is not possible to know that the servers have processed the mes‐
486 sage.
487 Any further messages sent to the servers, after this function
489 has returned, are received by all servers after this message.
490 server_call(Node, Name, ReplyWrapper, Msg) ->
492 Reply | {error, Reason}
493 Types:
495 Node = node()
497 Name = atom()
498 ReplyWrapper = Msg = Reply = term()
499 Reason = nodedown
500 Can be used when interacting with a server called Name on node
502 Node. It is assumed that the server receives messages in the
503 format {From, Msg} and replies using From ! {ReplyWrapper, Node,
504 Reply}. This function makes such a server call and ensures that
505 the entire call is packed into an atomic transaction, which ei‐
506 ther succeeds or fails. It never hangs, unless the server itself
507 hangs.
508 The function returns the answer Reply as produced by the server
510 Name, or {error, Reason}.
511 yield(Key) -> Res | {badrpc, Reason}
513 Types:
515 Key = key()
517 Res = Reason = term()
518 Returns the promised answer from a previous async_call/4. If the
520 answer is available, it is returned immediately. Otherwise, the
521 calling process is suspended until the answer arrives from Node.
522 Note:
524 This function must be called by the same process from which
525 async_call/4 was made otherwise it will never return.
526 See the note in call/4 for more details of the return value.
529Ericsson AB kernel 9.1 rpc(3)