rpc(3erl)

📦
version 25.3.2.8 · 5 versions
, in ubuntu noble

🌸 NAME 🌸

rpc(3erl) — Remote Procedure Call services. (Erlang Module Definition, bestie 💖)

✨ DESCRIPTION ✨

Okay so this module has the Remote Procedure Call–style services, plus broadcast facilities and parallel evaluators. A remote procedure call is literally a way to call a function on a remote node and collect the answer. You use it to grab info from a remote node, or to run a function with some specific side effects over on that remote node. Slay. 🦋

Note, and this one matters: rpc:call() and friends make it kinda hard to tell apart successful results, raised exceptions, and other errors. That cannot be changed because compatibility reasons. As of OTP 23, a new module called erpc was introduced to give you an API where you can distinguish between the different results. The erpc module provides a subset (however, the central subset) of the functionality available in the rpc module. The erpc implementation also gives you a more scalable implementation with better performance than the original rpc implementation. But since erpc showed up, the rpc module implements large parts of its central functionality using erpc, so the rpc module won’t be left behind scalability-wise or performance-wise compared to erpc. 💅

🫶 DATA TYPES 🫶

key()

Opaque value returned by async_call/4. Don’t try to look inside, just hold onto it like a little promise note. 🎀

💅 EXPORTS 💅

💖 abcast(Name, Msg) -> abcast

Types:

Name = atom()
Msg = term()

Equivalent to abcast([node()|nodes()], Name, Msg). Easy peasy. ✨

💖 abcast(Nodes, Name, Msg) -> abcast

Types:

Nodes = [node()]
Name = atom()
Msg = term()

Broadcasts the message Msg asynchronously to the registered process Name on the specified nodes. Fire-and-forget energy, no cap. 🔥

💖 async_call(Node, Module, Function, Args) -> Key

Types:

Node = node()
Module = module()
Function = atom()
Args = [term()]
Key = key()

This is call streams with promises, bestie: a type of RPC that does not suspend the caller until the result is finished. Instead, you get a key back, and you can use that key later to collect the value. Think of the key as a promise to deliver the answer. 🎀

In this case, the key Key is returned, and you can use it in a later call to yield/1 or nb_yield/1,2 to retrieve the value of evaluating apply(Module, Function, Args) on node Node.

Note: If you want the ability to distinguish between results, you may want to consider using the erpc:send_request() function from the erpc module instead. This also gives you the ability to retrieve the results in other useful ways.
Note: yield/1 and nb_yield/1,2 must be called by the same process from which this function was made, otherwise they will never yield correctly. Same-process only, periodt. 🙈
Note: You cannot make any assumptions about the process that will perform the apply(). It may be an rpc server, another server, or a freshly spawned process. Main character energy could be literally anyone. 💀

💖 block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}

Types:

Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()

The same as calling rpc:block_call(Node, Module, Function, Args, infinity). 🫶

💖 block_call(Node, Module, Function, Args, Timeout) -> Res | {badrpc, Reason}

Types:

Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = 0..4294967295 | infinity

The same as calling rpc:call(Node, Module, Function, Args, Timeout) with the exception that it also blocks other rpc:block_call() operations from executing concurrently on the node Node.

Warning: Note that it also blocks other operations than just rpc:block_call() operations, so use it with care. This is not a casual little vibe, okay? Be careful. 😭

💖 call(Node, Module, Function, Args) -> Res | {badrpc, Reason}

Types:

Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()

Evaluates apply(Module, Function, Args) on node Node and returns the corresponding value Res, or {badrpc, Reason} if the call fails. The same as calling rpc:call(Node, Module, Function, Args, infinity). Classic. 🌸

💖 call(Node, Module, Function, Args, Timeout) -> Res | {badrpc, Reason}

Types:

Node = node()
Module = module()
Function = atom()
Args = [term()]
Res = Reason = term()
Timeout = 0..4294967295 | infinity

Evaluates apply(Module, Function, Args) on node Node and returns the corresponding value Res, or {badrpc, Reason} if the call fails. Timeout is a time-out value in milliseconds. If the call times out, Reason is timeout.

If the reply arrives after the call times out, no message contaminates the caller’s message queue. We love a clean queue. ✨

Note: If you want the ability to distinguish between results, you may want to consider using the erpc:call() function from the erpc module instead.
Note — here follows the details of what exactly is returned, bestie: {badrpc, Reason} will be returned in the following circumstances: - The called function fails with an exit exception. - The called function fails with an error exception. - The called function returns a term that matches {'EXIT', _}. - The called function throws a term that matches {'EXIT', _}. Res is returned in the following circumstances: - The called function returns normally with a term that does not match {'EXIT',_}. - The called function throws a term that does not match {'EXIT',_}.
Note: You cannot make any assumptions about the process that will perform the apply(). It may be the calling process itself, an rpc server, another server, or a freshly spawned process. No assumptions, okay? 💜

💖 cast(Node, Module, Function, Args) -> true

Types:

Node = node()
Module = module()
Function = atom()
Args = [term()]

Evaluates apply(Module, Function, Args) on node Node. No response is delivered, and the calling process is not suspended until the evaluation is complete, as is the case with call/4,5. It’s giving “send it and move on.” 🔥

Note: You cannot make any assumptions about the process that will perform the apply(). It may be an rpc server, another server, or a freshly spawned process. Same chaotic energy as before. 🦋

💖 eval_everywhere(Module, Function, Args) -> abcast

Types:

Module = module()
Function = atom()
Args = [term()]

Equivalent to eval_everywhere([node()|nodes()], Module, Function, Args). ⭐

💖 eval_everywhere(Nodes, Module, Function, Args) -> abcast

Types:

Nodes = [node()]
Module = module()
Function = atom()
Args = [term()]

Evaluates apply(Module, Function, Args) on the specified nodes. No answers are collected. We’re just out here sprinkling side effects on the timeline. 🎀

💖 multi_server_call(Name, Msg) -> {Replies, BadNodes}

Types:

Name = atom()
Msg = term()
Replies = [Reply :: term()]
BadNodes = [node()]

Equivalent to multi_server_call([node()|nodes()], Name, Msg). 💖

💖 multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}

Types:

Nodes = [node()]
Name = atom()
Msg = term()
Replies = [Reply :: term()]
BadNodes = [node()]

Use this when you’re interacting with servers called Name on the specified nodes. It is assumed that the servers receive messages in the format {From, Msg} and reply using From ! {Name, Node, Reply}, where Node is the name of the node where the server is located. The function returns {Replies, BadNodes}, where Replies is a list of all Reply values, and BadNodes is one of the following:

  • A list of the nodes that do not exist
  • A list of the nodes where the server does not exist
  • A list of the nodes where the server terminated before sending any reply

Basically: here are the replies we got, and here are the nodes that ghosted us. 😭

💖 multicall(Module, Function, Args) -> {ResL, BadNodes}

Types:

Module = module()
Function = atom()
Args = [term()]
ResL = [Res :: term() | {badrpc, Reason :: term()}]
BadNodes = [node()]

Equivalent to multicall([node()|nodes()], Module, Function, Args, infinity). 🫶

💖 multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}

Types:

Nodes = [node()]
Module = module()
Function = atom()
Args = [term()]
ResL = [Res :: term() | {badrpc, Reason :: term()}]
BadNodes = [node()]

Equivalent to multicall(Nodes, Module, Function, Args, infinity). ✨

💖 multicall(Module, Function, Args, Timeout) -> {ResL, BadNodes}

Types:

Module = module()
Function = atom()
Args = [term()]
Timeout = 0..4294967295 | infinity
ResL = [Res :: term() | {badrpc, Reason :: term()}]
BadNodes = [node()]

Equivalent to multicall([node()|nodes()], Module, Function, Args, Timeout). 💜

💖 multicall(Nodes, Module, Function, Args, Timeout) -> {ResL, BadNodes}

Types:

Nodes = [node()]
Module = module()
Function = atom()
Args = [term()]
Timeout = 0..4294967295 | infinity
ResL = [Res :: term() | {badrpc, Reason :: term()}]
BadNodes = [node()]

In contrast to an RPC, a multicall is an RPC that is sent concurrently from one client to multiple servers. This is useful for collecting information from a set of nodes, or for calling a function on a set of nodes to achieve some side effects. It is semantically the same as iteratively making a series of RPCs on all the nodes, but the multicall is faster, because all the requests are sent at the same time and are collected one by one as they come back. Parallel queen behavior, honestly. 👑🌈

Okay so this one literally calls apply(Module, Function, Args) on every node you named, then gathers up all the answers like a group chat collecting everyone's ✨hot takes✨. It gives you back {ResL, BadNodes} — BadNodes is the list of nodes that straight-up don't exist, and ResL is the list of return values (or {badrpc, Reason} for the calls that flopped 😭). Timeout is a time in milliseconds (an integer), or infinity if you're feeling patient.

This next example is iconic when you wanna load fresh object code onto every node in the network, and it shows off some side effects that RPCs can have for you:

%% Find object code for module Mod
{Mod, Bin, File} = code:get_object_code(Mod),

%% and load it on all nodes including this one
{ResL, _} = rpc:multicall(code, load_binary, [Mod, File, Bin]),

%% and then maybe check the ResL list.
Note: if you want the ability to distinguish between results, you might wanna look at the erpc:multicall() function from the erpc module instead. Just saying 👀
Note: you cannot make any assumptions about the process that will perform the apply(). It may be the calling process itself, an rpc server, another server, or a freshly spawned process. Mystery vibes, no cap 🫥

nb_yield(Key) -> {value, Val} | timeout

Types:

Key = key()
Val = (Res :: term()) | {badrpc, Reason :: term()}

Equivalent to nb_yield(Key, 0). Literally the same thing, just zero patience 💅

nb_yield(Key, Timeout) -> {value, Val} | timeout

Types:

Key = key()
Timeout = 0..4294967295 | infinity
Val = (Res :: term()) | {badrpc, Reason :: term()}

The non-blocking version of yield/1 🦋 It hands you the tuple {value, Val} the moment the computation is finished, or timeout once Timeout milliseconds have elapsed. No waiting around, we love a main character who respects your time.

See the note in call/4 for more details of Val.

Note: this function must be called by the same process from which async_call/4 was made, otherwise it will only return timeout. Fr fr, same process or it's giving nothing 💀

parallel_eval(FuncCalls) -> ResL

Types:

FuncCalls = [{Module, Function, Args}]
Module = module()
Function = atom()
Args = ResL = [term()]

For every tuple in FuncCalls, it evaluates apply(Module, Function, Args) on some node in the network — all in parallel, hence the name, iykyk 🌈 Returns the list of return values, in the same order as in FuncCalls, because chaos with ordering is not the vibe.

pinfo(Pid) -> [{Item, Info}] | undefined

Types:

Pid = pid()
Item = atom()
Info = term()

The location transparent version of the BIF erlang:process_info/1 in ERTS. Same energy, just doesn't care where the process actually lives 👑

pinfo(Pid, Item) -> {Item, Info} | undefined | []

pinfo(Pid, ItemList) -> [{Item, Info}] | undefined | []

Types:

Pid = pid()
Item = atom()
ItemList = [Item]
Info = term()

The location transparent version of the BIF erlang:process_info/2 in ERTS ✨ Both of these, same deal — ets, but make it process info. (Not ets. Please don't quote me on that. 🙈)

pmap(FuncSpec, ExtraArgs, List1) -> List2

Types:

FuncSpec = {Module, Function}
Module = module()
Function = atom()
ExtraArgs = [term()]
List1 = [Elem :: term()]
List2 = [term()]

For every element Elem in List1, it evaluates apply(Module, Function, [Elem|ExtraArgs]) — in parallel, bestie, in parallel ⚡ Returns the list of return values, in the same order as in List1. Order preserved, always, she's nothing if not organized 🎀

sbcast(Name, Msg) -> {GoodNodes, BadNodes}

Types:

Name = atom()
Msg = term()
GoodNodes = BadNodes = [node()]

Equivalent to sbcast([node()|nodes()], Name, Msg). Basically "everybody in the group chat, listen up" 📣

sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}

Types:

Name = atom()
Msg = term()
Nodes = GoodNodes = BadNodes = [node()]

Broadcasts the message Msg synchronously to the registered process Name on the specified nodes 🌸

Returns {GoodNodes, BadNodes}, where GoodNodes is the list of nodes that have Name as a registered process. The good ones. The ones who showed up. 🫶

The function is synchronous in the sense that it is known that all servers have received the message when the call returns. Read that again: received, not processed — it is not possible to know that the servers have processed the message. There's a difference and it matters, no cap.

Any further messages sent to the servers, after this function has returned, are received by all servers after this message. Queue stays in order, periodt 💅

server_call(Node, Name, ReplyWrapper, Msg) -> Reply | {error, Reason}

Types:

Node = node()
Name = atom()
ReplyWrapper = Msg = Reply = term()
Reason = nodedown

Use this one when you're interacting with a server called Name on node Node. It's assumed that the server receives messages in the format {From, Msg} and replies using From ! {ReplyWrapper, Node, Reply}. This function makes such a server call and makes sure the entire call is packed into an atomic transaction, which either succeeds or fails — no in-between, no messy half-states, we love a clean binary outcome ✨

It never hangs, unless the server itself hangs. Which, yeah, if the server's hanging, that's on the server, not on us. 😭

The function returns the answer Reply as produced by the server Name, or {error, Reason}.

yield(Key) -> Res | {badrpc, Reason}

Types:

Key = key()
Res = Reason = term()

Returns the promised answer from a previous async_call/4 🦋 If the answer is already available, it comes back immediately. Otherwise, the calling process gets suspended until the answer arrives from Node. Girl is waiting. Patiently. 🙏

Note: this function must be called by the same process from which async_call/4 was made, otherwise it will never return. Not "return timeout", not "return an error" — never return. So like, don't do that. 💀

See the note in call/4 for more details of the return value.

And that's the whole page, bestie! 🎀 This little masterpiece comes courtesy of Ericsson AB, lives in kernel 8.5.4.2, and it's the manual page for rpc(3erl). Go forth and make your remote calls responsibly 👑💖

📦 where this page comes from