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 block_call(Node, Module, Function, Args, Timeout) ->
86 Res | {badrpc, Reason}
87 Types:
89 Node = node()
91 Module = module()
92 Function = atom()
93 Args = [term()]
94 Res = Reason = term()
95 Timeout = timeout()
96 Same as block_call/4, but with a time-out value in the same man‐
98 ner as call/5.
99 call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
101 Types:
103 Node = node()
105 Module = module()
106 Function = atom()
107 Args = [term()]
108 Res = Reason = term()
109 Evaluates apply(Module, Function, Args) on node Node and returns
111 the corresponding value Res, or {badrpc, Reason} if the call
112 fails.
113 call(Node, Module, Function, Args, Timeout) ->
115 Res | {badrpc, Reason}
116 Types:
118 Node = node()
120 Module = module()
121 Function = atom()
122 Args = [term()]
123 Res = Reason = term()
124 Timeout = timeout()
125 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 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 cast(Node, Module, Function, Args) -> true
138 Types:
140 Node = node()
142 Module = module()
143 Function = atom()
144 Args = [term()]
145 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 eval_everywhere(Module, Function, Args) -> abcast
151 Types:
153 Module = module()
155 Function = atom()
156 Args = [term()]
157 Equivalent to eval_everywhere([node()|nodes()], Module, Func‐
159 tion, Args).
160 eval_everywhere(Nodes, Module, Function, Args) -> abcast
162 Types:
164 Nodes = [node()]
166 Module = module()
167 Function = atom()
168 Args = [term()]
169 Evaluates apply(Module, Function, Args) on the specified nodes.
171 No answers are collected.
172 multi_server_call(Name, Msg) -> {Replies, BadNodes}
174 Types:
176 Name = atom()
178 Msg = term()
179 Replies = [Reply :: term()]
180 BadNodes = [node()]
181 Equivalent to multi_server_call([node()|nodes()], Name, Msg).
183 multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
185 Types:
187 Nodes = [node()]
189 Name = atom()
190 Msg = term()
191 Replies = [Reply :: term()]
192 BadNodes = [node()]
193 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 * A list of the nodes that do not exist
203 * A list of the nodes where the server does not exist
205 * A list of the nodes where the server terminatd before send‐
207 ing any reply.
208 multicall(Module, Function, Args) -> {ResL, BadNodes}
210 Types:
212 Module = module()
214 Function = atom()
215 Args = ResL = [term()]
216 BadNodes = [node()]
217 Equivalent to multicall([node()|nodes()], Module, Function,
219 Args, infinity).
220 multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
222 Types:
224 Nodes = [node()]
226 Module = module()
227 Function = atom()
228 Args = ResL = [term()]
229 BadNodes = [node()]
230 Equivalent to multicall(Nodes, Module, Function, Args, infin‐
232 ity).
233 multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
235 Types:
237 Module = module()
239 Function = atom()
240 Args = [term()]
241 Timeout = timeout()
242 ResL = [term()]
243 BadNodes = [node()]
244 Equivalent to multicall([node()|nodes()], Module, Function,
246 Args, Timeout).
247 multicall(Nodes, Module, Function, Args, Timeout) ->
249 {ResL, BadNodes}
250 Types:
252 Nodes = [node()]
254 Module = module()
255 Function = atom()
256 Args = [term()]
257 Timeout = timeout()
258 ResL = [term()]
259 BadNodes = [node()]
260 In contrast to an RPC, a multicall is an RPC that is sent con‐
262 currently from one client to multiple servers. This is useful
263 for collecting information from a set of nodes, or for calling a
264 function on a set of nodes to achieve some side effects. It is
265 semantically the same as iteratively making a series of RPCs on
266 all the nodes, but the multicall is faster, as all the requests
267 are sent at the same time and are collected one by one as they
268 come back.
269 The function evaluates apply(Module, Function, Args) on the
271 specified nodes and collects the answers. It returns {ResL,
272 BadNodes}, where BadNodes is a list of the nodes that terminated
273 or timed out during computation, and ResL is a list of the
274 return values. Timeout is a time (integer) in milliseconds, or
275 infinity.
276 The following example is useful when new object code is to be
278 loaded on all nodes in the network, and indicates some side
279 effects that RPCs can produce:
280 %% Find object code for module Mod
282 {Mod, Bin, File} = code:get_object_code(Mod),
283 %% and load it on all nodes including this one
285 {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
286 %% and then maybe check the ResL list.
288 nb_yield(Key) -> {value, Val} | timeout
290 Types:
292 Key = key()
294 Val = (Res :: term()) | {badrpc, Reason :: term()}
295 Equivalent to nb_yield(Key, 0).
297 nb_yield(Key, Timeout) -> {value, Val} | timeout
299 Types:
301 Key = key()
303 Timeout = timeout()
304 Val = (Res :: term()) | {badrpc, Reason :: term()}
305 Non-blocking version of yield/1. It returns the tuple {value,
307 Val} when the computation is finished, or timeout when Timeout
308 milliseconds has elapsed.
309 Note:
311 This function must be called by the same process from which
312 async_call/4 was made otherwise it will only return timeout.
313 parallel_eval(FuncCalls) -> ResL
316 Types:
318 FuncCalls = [{Module, Function, Args}]
320 Module = module()
321 Function = atom()
322 Args = ResL = [term()]
323 Evaluates, for every tuple in FuncCalls, apply(Module, Function,
325 Args) on some node in the network. Returns the list of return
326 values, in the same order as in FuncCalls.
327 pinfo(Pid) -> [{Item, Info}] | undefined
329 Types:
331 Pid = pid()
333 Item = atom()
334 Info = term()
335 Location transparent version of the BIF erlang:process_info/1 in
337 ERTS.
338 pinfo(Pid, Item) -> {Item, Info} | undefined | []
340 pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
342 Types:
344 Pid = pid()
346 Item = atom()
347 ItemList = [Item]
348 Info = term()
349 Location transparent version of the BIF erlang:process_info/2 in
351 ERTS.
352 pmap(FuncSpec, ExtraArgs, List1) -> List2
354 Types:
356 FuncSpec = {Module, Function}
358 Module = module()
359 Function = atom()
360 ExtraArgs = [term()]
361 List1 = [Elem :: term()]
362 List2 = [term()]
363 Evaluates apply(Module, Function, [Elem|ExtraArgs]) for every
365 element Elem in List1, in parallel. Returns the list of return
366 values, in the same order as in List1.
367 sbcast(Name, Msg) -> {GoodNodes, BadNodes}
369 Types:
371 Name = atom()
373 Msg = term()
374 GoodNodes = BadNodes = [node()]
375 Equivalent to sbcast([node()|nodes()], Name, Msg).
377 sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
379 Types:
381 Name = atom()
383 Msg = term()
384 Nodes = GoodNodes = BadNodes = [node()]
385 Broadcasts the message Msg synchronously to the registered
387 process Name on the specified nodes.
388 Returns {GoodNodes, BadNodes}, where GoodNodes is the list of
390 nodes that have Name as a registered process.
391 The function is synchronous in the sense that it is known that
393 all servers have received the message when the call returns. It
394 is not possible to know that the servers have processed the mes‐
395 sage.
396 Any further messages sent to the servers, after this function
398 has returned, are received by all servers after this message.
399 server_call(Node, Name, ReplyWrapper, Msg) ->
401 Reply | {error, Reason}
402 Types:
404 Node = node()
406 Name = atom()
407 ReplyWrapper = Msg = Reply = term()
408 Reason = nodedown
409 Can be used when interacting with a server called Name on node
411 Node. It is assumed that the server receives messages in the
412 format {From, Msg} and replies using From ! {ReplyWrapper, Node,
413 Reply}. This function makes such a server call and ensures that
414 the entire call is packed into an atomic transaction, which
415 either succeeds or fails. It never hangs, unless the server
416 itself hangs.
417 The function returns the answer Reply as produced by the server
419 Name, or {error, Reason}.
420 yield(Key) -> Res | {badrpc, Reason}
422 Types:
424 Key = key()
426 Res = Reason = term()
427 Returns the promised answer from a previous async_call/4. If the
429 answer is available, it is returned immediately. Otherwise, the
430 calling process is suspended until the answer arrives from Node.
431 Note:
433 This function must be called by the same process from which
434 async_call/4 was made otherwise it will never return.
435Ericsson AB kernel 5.4.3.2 rpc(3)