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
17 key()
18 As returned by async_call/4.
20
22 abcast(Name, Msg) -> abcast
23 Types:
25 Name = atom()
27 Msg = term()
28 Equivalent to abcast([node()|nodes()], Name, Msg).
30 abcast(Nodes, Name, Msg) -> abcast
32 Types:
34 Nodes = [node()]
36 Name = atom()
37 Msg = term()
38 Broadcasts the message Msg asynchronously to the registered
40 process Name on the specified nodes.
41 async_call(Node, Module, Function, Args) -> Key
43 Types:
45 Node = node()
47 Module = module()
48 Function = atom()
49 Args = [term()]
50 Key = key()
51 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 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 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 block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
68 Types:
70 Node = node()
72 Module = module()
73 Function = atom()
74 Args = [term()]
75 Res = Reason = term()
76 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 See the note in call/4 for more details of the return value.
86 block_call(Node, Module, Function, Args, Timeout) ->
88 Res | {badrpc, Reason}
89 Types:
91 Node = node()
93 Module = module()
94 Function = atom()
95 Args = [term()]
96 Res = Reason = term()
97 Timeout = timeout()
98 Same as block_call/4, but with a time-out value in the same man‐
100 ner as call/5.
101 See the note in call/4 for more details of the return value.
103 call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
105 Types:
107 Node = node()
109 Module = module()
110 Function = atom()
111 Args = [term()]
112 Res = Reason = term()
113 Evaluates apply(Module, Function, Args) on node Node and returns
115 the corresponding value Res, or {badrpc, Reason} if the call
116 fails.
117 Note:
119 Here follows the details of what exactly is returned.
120 {badrpc, Reason} will be returned in the following circum‐
122 stances:
123 * The called function fails with an exit exception.
125 * The called function fails with an error exception.
127 * The called function returns a term that matches {'EXIT', _}.
129 * The called function throws a term that matches {'EXIT', _}.
131 Res is returned in the following circumstances:
133 * The called function returns normally with a term that does
135 not match {'EXIT',_}.
136 * The called function throws a term that does not match
138 {'EXIT',_}.
139 call(Node, Module, Function, Args, Timeout) ->
141 Res | {badrpc, Reason}
142 Types:
144 Node = node()
146 Module = module()
147 Function = atom()
148 Args = [term()]
149 Res = Reason = term()
150 Timeout = timeout()
151 Evaluates apply(Module, Function, Args) on node Node and returns
153 the corresponding value Res, or {badrpc, Reason} if the call
154 fails. Timeout is a time-out value in milliseconds. If the call
155 times out, Reason is timeout. See the note in call/4 for more
156 details of the return value.
157 If the reply arrives after the call times out, no message con‐
159 taminates the caller's message queue, as this function spawns
160 off a middleman process to act as (a void) destination for such
161 an orphan reply. This feature also makes this function more
162 expensive than call/4 at the caller's end.
163 cast(Node, Module, Function, Args) -> true
165 Types:
167 Node = node()
169 Module = module()
170 Function = atom()
171 Args = [term()]
172 Evaluates apply(Module, Function, Args) on node Node. No
174 response is delivered and the calling process is not suspended
175 until the evaluation is complete, as is the case with call/4,5.
176 eval_everywhere(Module, Function, Args) -> abcast
178 Types:
180 Module = module()
182 Function = atom()
183 Args = [term()]
184 Equivalent to eval_everywhere([node()|nodes()], Module, Func‐
186 tion, Args).
187 eval_everywhere(Nodes, Module, Function, Args) -> abcast
189 Types:
191 Nodes = [node()]
193 Module = module()
194 Function = atom()
195 Args = [term()]
196 Evaluates apply(Module, Function, Args) on the specified nodes.
198 No answers are collected.
199 multi_server_call(Name, Msg) -> {Replies, BadNodes}
201 Types:
203 Name = atom()
205 Msg = term()
206 Replies = [Reply :: term()]
207 BadNodes = [node()]
208 Equivalent to multi_server_call([node()|nodes()], Name, Msg).
210 multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
212 Types:
214 Nodes = [node()]
216 Name = atom()
217 Msg = term()
218 Replies = [Reply :: term()]
219 BadNodes = [node()]
220 Can be used when interacting with servers called Name on the
222 specified nodes. It is assumed that the servers receive messages
223 in the format {From, Msg} and reply using From ! {Name, Node,
224 Reply}, where Node is the name of the node where the server is
225 located. The function returns {Replies, BadNodes}, where Replies
226 is a list of all Reply values, and BadNodes is one of the fol‐
227 lowing:
228 * A list of the nodes that do not exist
230 * A list of the nodes where the server does not exist
232 * A list of the nodes where the server terminated before send‐
234 ing any reply.
235 multicall(Module, Function, Args) -> {ResL, BadNodes}
237 Types:
239 Module = module()
241 Function = atom()
242 Args = [term()]
243 ResL = [Res :: term() | {badrpc, Reason :: term()}]
244 BadNodes = [node()]
245 Equivalent to multicall([node()|nodes()], Module, Function,
247 Args, infinity).
248 multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
250 Types:
252 Nodes = [node()]
254 Module = module()
255 Function = atom()
256 Args = [term()]
257 ResL = [Res :: term() | {badrpc, Reason :: term()}]
258 BadNodes = [node()]
259 Equivalent to multicall(Nodes, Module, Function, Args, infin‐
261 ity).
262 multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
264 Types:
266 Module = module()
268 Function = atom()
269 Args = [term()]
270 Timeout = timeout()
271 ResL = [Res :: term() | {badrpc, Reason :: term()}]
272 BadNodes = [node()]
273 Equivalent to multicall([node()|nodes()], Module, Function,
275 Args, Timeout).
276 multicall(Nodes, Module, Function, Args, Timeout) ->
278 {ResL, BadNodes}
279 Types:
281 Nodes = [node()]
283 Module = module()
284 Function = atom()
285 Args = [term()]
286 Timeout = timeout()
287 ResL = [Res :: term() | {badrpc, Reason :: term()}]
288 BadNodes = [node()]
289 In contrast to an RPC, a multicall is an RPC that is sent con‐
291 currently from one client to multiple servers. This is useful
292 for collecting information from a set of nodes, or for calling a
293 function on a set of nodes to achieve some side effects. It is
294 semantically the same as iteratively making a series of RPCs on
295 all the nodes, but the multicall is faster, as all the requests
296 are sent at the same time and are collected one by one as they
297 come back.
298 The function evaluates apply(Module, Function, Args) on the
300 specified nodes and collects the answers. It returns {ResL,
301 BadNodes}, where BadNodes is a list of the nodes that do not
302 exist, and ResL is a list of the return values, or {badrpc, Rea‐
303 son} for failing calls. Timeout is a time (integer) in millisec‐
304 onds, or infinity.
305 The following example is useful when new object code is to be
307 loaded on all nodes in the network, and indicates some side
308 effects that RPCs can produce:
309 %% Find object code for module Mod
311 {Mod, Bin, File} = code:get_object_code(Mod),
312 %% and load it on all nodes including this one
314 {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
315 %% and then maybe check the ResL list.
317 nb_yield(Key) -> {value, Val} | timeout
319 Types:
321 Key = key()
323 Val = (Res :: term()) | {badrpc, Reason :: term()}
324 Equivalent to nb_yield(Key, 0).
326 nb_yield(Key, Timeout) -> {value, Val} | timeout
328 Types:
330 Key = key()
332 Timeout = timeout()
333 Val = (Res :: term()) | {badrpc, Reason :: term()}
334 Non-blocking version of yield/1. It returns the tuple {value,
336 Val} when the computation is finished, or timeout when Timeout
337 milliseconds has elapsed.
338 See the note in call/4 for more details of Val.
340 Note:
342 This function must be called by the same process from which
343 async_call/4 was made otherwise it will only return timeout.
344 parallel_eval(FuncCalls) -> ResL
347 Types:
349 FuncCalls = [{Module, Function, Args}]
351 Module = module()
352 Function = atom()
353 Args = ResL = [term()]
354 Evaluates, for every tuple in FuncCalls, apply(Module, Function,
356 Args) on some node in the network. Returns the list of return
357 values, in the same order as in FuncCalls.
358 pinfo(Pid) -> [{Item, Info}] | undefined
360 Types:
362 Pid = pid()
364 Item = atom()
365 Info = term()
366 Location transparent version of the BIF erlang:process_info/1 in
368 ERTS.
369 pinfo(Pid, Item) -> {Item, Info} | undefined | []
371 pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
373 Types:
375 Pid = pid()
377 Item = atom()
378 ItemList = [Item]
379 Info = term()
380 Location transparent version of the BIF erlang:process_info/2 in
382 ERTS.
383 pmap(FuncSpec, ExtraArgs, List1) -> List2
385 Types:
387 FuncSpec = {Module, Function}
389 Module = module()
390 Function = atom()
391 ExtraArgs = [term()]
392 List1 = [Elem :: term()]
393 List2 = [term()]
394 Evaluates apply(Module, Function, [Elem|ExtraArgs]) for every
396 element Elem in List1, in parallel. Returns the list of return
397 values, in the same order as in List1.
398 sbcast(Name, Msg) -> {GoodNodes, BadNodes}
400 Types:
402 Name = atom()
404 Msg = term()
405 GoodNodes = BadNodes = [node()]
406 Equivalent to sbcast([node()|nodes()], Name, Msg).
408 sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
410 Types:
412 Name = atom()
414 Msg = term()
415 Nodes = GoodNodes = BadNodes = [node()]
416 Broadcasts the message Msg synchronously to the registered
418 process Name on the specified nodes.
419 Returns {GoodNodes, BadNodes}, where GoodNodes is the list of
421 nodes that have Name as a registered process.
422 The function is synchronous in the sense that it is known that
424 all servers have received the message when the call returns. It
425 is not possible to know that the servers have processed the mes‐
426 sage.
427 Any further messages sent to the servers, after this function
429 has returned, are received by all servers after this message.
430 server_call(Node, Name, ReplyWrapper, Msg) ->
432 Reply | {error, Reason}
433 Types:
435 Node = node()
437 Name = atom()
438 ReplyWrapper = Msg = Reply = term()
439 Reason = nodedown
440 Can be used when interacting with a server called Name on node
442 Node. It is assumed that the server receives messages in the
443 format {From, Msg} and replies using From ! {ReplyWrapper, Node,
444 Reply}. This function makes such a server call and ensures that
445 the entire call is packed into an atomic transaction, which
446 either succeeds or fails. It never hangs, unless the server
447 itself hangs.
448 The function returns the answer Reply as produced by the server
450 Name, or {error, Reason}.
451 yield(Key) -> Res | {badrpc, Reason}
453 Types:
455 Key = key()
457 Res = Reason = term()
458 Returns the promised answer from a previous async_call/4. If the
460 answer is available, it is returned immediately. Otherwise, the
461 calling process is suspended until the answer arrives from Node.
462 Note:
464 This function must be called by the same process from which
465 async_call/4 was made otherwise it will never return.
466 See the note in call/4 for more details of the return value.
469Ericsson AB kernel 6.5.2 rpc(3)