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
32 key()
33 Opaque value returned by async_call/4.
35
37 abcast(Name, Msg) -> abcast
38 Types:
40 Name = atom()
42 Msg = term()
43 Equivalent to abcast([node()|nodes()], Name, Msg).
45 abcast(Nodes, Name, Msg) -> abcast
47 Types:
49 Nodes = [node()]
51 Name = atom()
52 Msg = term()
53 Broadcasts the message Msg asynchronously to the registered
55 process Name on the specified nodes.
56 async_call(Node, Module, Function, Args) -> Key
58 Types:
60 Node = node()
62 Module = module()
63 Function = atom()
64 Args = [term()]
65 Key = key()
66 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 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 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 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 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 block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
96 Types:
98 Node = node()
100 Module = module()
101 Function = atom()
102 Args = [term()]
103 Res = Reason = term()
104 The same as calling rpc:block_call(Node, Module, Function, Args,
106 infinity).
107 block_call(Node, Module, Function, Args, Timeout) ->
109 Res | {badrpc, Reason}
110 Types:
112 Node = node()
114 Module = module()
115 Function = atom()
116 Args = [term()]
117 Res = Reason = term()
118 Timeout = 0..4294967295 | infinity
119 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 Warning:
126 Note that it also blocks other operations than just
127 rpc:block_call() operations, so use it with care.
128 call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
131 Types:
133 Node = node()
135 Module = module()
136 Function = atom()
137 Args = [term()]
138 Res = Reason = term()
139 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 call(Node, Module, Function, Args, Timeout) ->
146 Res | {badrpc, Reason}
147 Types:
149 Node = node()
151 Module = module()
152 Function = atom()
153 Args = [term()]
154 Res = Reason = term()
155 Timeout = 0..4294967295 | infinity
156 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 If the reply arrives after the call times out, no message con‐
163 taminates the caller's message queue.
164 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 Note:
172 Here follows the details of what exactly is returned.
173 {badrpc, Reason} will be returned in the following circum‐
175 stances:
176 * The called function fails with an exit exception.
178 * The called function fails with an error exception.
180 * The called function returns a term that matches {'EXIT', _}.
182 * The called function throws a term that matches {'EXIT', _}.
184 Res is returned in the following circumstances:
186 * The called function returns normally with a term that does
188 not match {'EXIT',_}.
189 * The called function throws a term that does not match
191 {'EXIT',_}.
192 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 cast(Node, Module, Function, Args) -> true
200 Types:
202 Node = node()
204 Module = module()
205 Function = atom()
206 Args = [term()]
207 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 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 eval_everywhere(Module, Function, Args) -> abcast
219 Types:
221 Module = module()
223 Function = atom()
224 Args = [term()]
225 Equivalent to eval_everywhere([node()|nodes()], Module, Func‐
227 tion, Args).
228 eval_everywhere(Nodes, Module, Function, Args) -> abcast
230 Types:
232 Nodes = [node()]
234 Module = module()
235 Function = atom()
236 Args = [term()]
237 Evaluates apply(Module, Function, Args) on the specified nodes.
239 No answers are collected.
240 multi_server_call(Name, Msg) -> {Replies, BadNodes}
242 Types:
244 Name = atom()
246 Msg = term()
247 Replies = [Reply :: term()]
248 BadNodes = [node()]
249 Equivalent to multi_server_call([node()|nodes()], Name, Msg).
251 multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
253 Types:
255 Nodes = [node()]
257 Name = atom()
258 Msg = term()
259 Replies = [Reply :: term()]
260 BadNodes = [node()]
261 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 * A list of the nodes that do not exist
271 * A list of the nodes where the server does not exist
273 * A list of the nodes where the server terminated before send‐
275 ing any reply.
276 multicall(Module, Function, Args) -> {ResL, BadNodes}
278 Types:
280 Module = module()
282 Function = atom()
283 Args = [term()]
284 ResL = [Res :: term() | {badrpc, Reason :: term()}]
285 BadNodes = [node()]
286 Equivalent to multicall([node()|nodes()], Module, Function,
288 Args, infinity).
289 multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
291 Types:
293 Nodes = [node()]
295 Module = module()
296 Function = atom()
297 Args = [term()]
298 ResL = [Res :: term() | {badrpc, Reason :: term()}]
299 BadNodes = [node()]
300 Equivalent to multicall(Nodes, Module, Function, Args, infin‐
302 ity).
303 multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
305 Types:
307 Module = module()
309 Function = atom()
310 Args = [term()]
311 Timeout = 0..4294967295 | infinity
312 ResL = [Res :: term() | {badrpc, Reason :: term()}]
313 BadNodes = [node()]
314 Equivalent to multicall([node()|nodes()], Module, Function,
316 Args, Timeout).
317 multicall(Nodes, Module, Function, Args, Timeout) ->
319 {ResL, BadNodes}
320 Types:
322 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 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 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 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 %% Find object code for module Mod
352 {Mod, Bin, File} = code:get_object_code(Mod),
353 %% and load it on all nodes including this one
355 {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
356 %% and then maybe check the ResL list.
358 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 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 nb_yield(Key) -> {value, Val} | timeout
372 Types:
374 Key = key()
376 Val = (Res :: term()) | {badrpc, Reason :: term()}
377 Equivalent to nb_yield(Key, 0).
379 nb_yield(Key, Timeout) -> {value, Val} | timeout
381 Types:
383 Key = key()
385 Timeout = 0..4294967295 | infinity
386 Val = (Res :: term()) | {badrpc, Reason :: term()}
387 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 See the note in call/4 for more details of Val.
393 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 parallel_eval(FuncCalls) -> ResL
400 Types:
402 FuncCalls = [{Module, Function, Args}]
404 Module = module()
405 Function = atom()
406 Args = ResL = [term()]
407 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 pinfo(Pid) -> [{Item, Info}] | undefined
413 Types:
415 Pid = pid()
417 Item = atom()
418 Info = term()
419 Location transparent version of the BIF erlang:process_info/1 in
421 ERTS.
422 pinfo(Pid, Item) -> {Item, Info} | undefined | []
424 pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
426 Types:
428 Pid = pid()
430 Item = atom()
431 ItemList = [Item]
432 Info = term()
433 Location transparent version of the BIF erlang:process_info/2 in
435 ERTS.
436 pmap(FuncSpec, ExtraArgs, List1) -> List2
438 Types:
440 FuncSpec = {Module, Function}
442 Module = module()
443 Function = atom()
444 ExtraArgs = [term()]
445 List1 = [Elem :: term()]
446 List2 = [term()]
447 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 sbcast(Name, Msg) -> {GoodNodes, BadNodes}
453 Types:
455 Name = atom()
457 Msg = term()
458 GoodNodes = BadNodes = [node()]
459 Equivalent to sbcast([node()|nodes()], Name, Msg).
461 sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
463 Types:
465 Name = atom()
467 Msg = term()
468 Nodes = GoodNodes = BadNodes = [node()]
469 Broadcasts the message Msg synchronously to the registered
471 process Name on the specified nodes.
472 Returns {GoodNodes, BadNodes}, where GoodNodes is the list of
474 nodes that have Name as a registered process.
475 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 Any further messages sent to the servers, after this function
482 has returned, are received by all servers after this message.
483 server_call(Node, Name, ReplyWrapper, Msg) ->
485 Reply | {error, Reason}
486 Types:
488 Node = node()
490 Name = atom()
491 ReplyWrapper = Msg = Reply = term()
492 Reason = nodedown
493 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 The function returns the answer Reply as produced by the server
503 Name, or {error, Reason}.
504 yield(Key) -> Res | {badrpc, Reason}
506 Types:
508 Key = key()
510 Res = Reason = term()
511 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 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 See the note in call/4 for more details of the return value.
522Ericsson AB kernel 8.5.4.2 rpc(3)