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 terminated before send‐
207 ing any reply.
208 multicall(Module, Function, Args) -> {ResL, BadNodes}
210 Types:
212 Module = module()
214 Function = atom()
215 Args = [term()]
216 ResL = [Res :: term() | {badrpc, Reason :: term()}]
217 BadNodes = [node()]
218 Equivalent to multicall([node()|nodes()], Module, Function,
220 Args, infinity).
221 multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
223 Types:
225 Nodes = [node()]
227 Module = module()
228 Function = atom()
229 Args = [term()]
230 ResL = [Res :: term() | {badrpc, Reason :: term()}]
231 BadNodes = [node()]
232 Equivalent to multicall(Nodes, Module, Function, Args, infin‐
234 ity).
235 multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}
237 Types:
239 Module = module()
241 Function = atom()
242 Args = [term()]
243 Timeout = timeout()
244 ResL = [Res :: term() | {badrpc, Reason :: term()}]
245 BadNodes = [node()]
246 Equivalent to multicall([node()|nodes()], Module, Function,
248 Args, Timeout).
249 multicall(Nodes, Module, Function, Args, Timeout) ->
251 {ResL, BadNodes}
252 Types:
254 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 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 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 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 %% Find object code for module Mod
284 {Mod, Bin, File} = code:get_object_code(Mod),
285 %% and load it on all nodes including this one
287 {ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),
288 %% and then maybe check the ResL list.
290 nb_yield(Key) -> {value, Val} | timeout
292 Types:
294 Key = key()
296 Val = (Res :: term()) | {badrpc, Reason :: term()}
297 Equivalent to nb_yield(Key, 0).
299 nb_yield(Key, Timeout) -> {value, Val} | timeout
301 Types:
303 Key = key()
305 Timeout = timeout()
306 Val = (Res :: term()) | {badrpc, Reason :: term()}
307 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 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 parallel_eval(FuncCalls) -> ResL
318 Types:
320 FuncCalls = [{Module, Function, Args}]
322 Module = module()
323 Function = atom()
324 Args = ResL = [term()]
325 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 pinfo(Pid) -> [{Item, Info}] | undefined
331 Types:
333 Pid = pid()
335 Item = atom()
336 Info = term()
337 Location transparent version of the BIF erlang:process_info/1 in
339 ERTS.
340 pinfo(Pid, Item) -> {Item, Info} | undefined | []
342 pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []
344 Types:
346 Pid = pid()
348 Item = atom()
349 ItemList = [Item]
350 Info = term()
351 Location transparent version of the BIF erlang:process_info/2 in
353 ERTS.
354 pmap(FuncSpec, ExtraArgs, List1) -> List2
356 Types:
358 FuncSpec = {Module, Function}
360 Module = module()
361 Function = atom()
362 ExtraArgs = [term()]
363 List1 = [Elem :: term()]
364 List2 = [term()]
365 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 sbcast(Name, Msg) -> {GoodNodes, BadNodes}
371 Types:
373 Name = atom()
375 Msg = term()
376 GoodNodes = BadNodes = [node()]
377 Equivalent to sbcast([node()|nodes()], Name, Msg).
379 sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
381 Types:
383 Name = atom()
385 Msg = term()
386 Nodes = GoodNodes = BadNodes = [node()]
387 Broadcasts the message Msg synchronously to the registered
389 process Name on the specified nodes.
390 Returns {GoodNodes, BadNodes}, where GoodNodes is the list of
392 nodes that have Name as a registered process.
393 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 Any further messages sent to the servers, after this function
400 has returned, are received by all servers after this message.
401 server_call(Node, Name, ReplyWrapper, Msg) ->
403 Reply | {error, Reason}
404 Types:
406 Node = node()
408 Name = atom()
409 ReplyWrapper = Msg = Reply = term()
410 Reason = nodedown
411 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 The function returns the answer Reply as produced by the server
421 Name, or {error, Reason}.
422 yield(Key) -> Res | {badrpc, Reason}
424 Types:
426 Key = key()
428 Res = Reason = term()
429 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 Note:
435 This function must be called by the same process from which
436 async_call/4 was made otherwise it will never return.
437Ericsson AB kernel 6.3.1.1 rpc(3)