View Source rpc (kernel v9.3)

Remote Procedure Call services.

This module contains services similar to Remote Procedure Calls. It also contains broadcast facilities and parallel evaluators. A remote procedure call is a method to call a function on a remote node and collect the answer. It is used for collecting information on a remote node, or for running a function with some specific side effects on the remote node.

Note

rpc:call/4 and friends makes it quite hard to distinguish between successful results, raised exceptions, and other errors. This cannot be changed due to compatibility reasons. As of OTP 23, a new module erpc was introduced in order to provide an API that makes it possible to 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 provides a more scalable implementation with better performance than the original rpc implementation. However, since the introduction of erpc, the rpc module implements large parts of its central functionality using erpc, so the rpc module won't not suffer scalability wise and performance wise compared to erpc.

Note

For some important information about distributed signals, see the Blocking Signaling Over Distribution section in the Processes chapter of the Erlang Reference Manual. Blocking signaling can, for example, cause timeouts in rpc to be significantly delayed.

Summary

Types

Opaque value returned by async_call/4.

Functions

Broadcasts the message Msg asynchronously to the registered process Name on the specified nodes.

Implements call streams with promises, a type of RPC that does not suspend the caller until the result is finished. Instead, a key is returned, which can be used later to collect the value. The key can be viewed as a promise to deliver the answer.

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

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).

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.

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.

Evaluates apply(Module, Function, Args) on the specified nodes. No answers are collected.

Can be used when 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

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, as all the requests are sent at the same time and are collected one by one as they come back.

Non-blocking version of yield/1. It returns the tuple {value, Val} when the computation is finished, or timeout when Timeout milliseconds has elapsed.

Evaluates, for every tuple in FuncCalls, apply(Module, Function, Args) on some node in the network. Returns the list of return values, in the same order as in FuncCalls.

Location transparent version of the BIF erlang:process_info/1 in ERTS.

Location transparent version of the BIF erlang:process_info/2 in ERTS.

Evaluates apply(Module, Function, [Elem|ExtraArgs]) for every element Elem in List1, in parallel. Returns the list of return values, in the same order as in List1.

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

Can be used when interacting with a server called Name on node Node. It is 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 ensures that the entire call is packed into an atomic transaction, which either succeeds or fails. It never hangs, unless the server itself hangs.

Returns the promised answer from a previous async_call/4. If the answer is available, it is returned immediately. Otherwise, the calling process is suspended until the answer arrives from Node.

Types

-opaque key()

Opaque value returned by async_call/4.

Functions

-spec abcast(Name, Msg) -> abcast when Name :: atom(), Msg :: term().

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

Link to this function

abcast(Nodes, Name, Msg)

View Source
-spec abcast(Nodes, Name, Msg) -> abcast when Nodes :: [node()], Name :: atom(), Msg :: term().

Broadcasts the message Msg asynchronously to the registered process Name on the specified nodes.

Link to this function

async_call(Node, Module, Function, Args)

View Source
-spec async_call(Node, Module, Function, Args) -> Key
              when
                  Node :: node(),
                  Module :: module(),
                  Function :: atom(),
                  Args :: [term()],
                  Key :: key().

Implements call streams with promises, a type of RPC that does not suspend the caller until the result is finished. Instead, a key is returned, which can be used later to collect the value. The key can be viewed as a promise to deliver the answer.

In this case, the key Key is returned, which can be used in a subsequent 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 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.

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.

Link to this function

block_call(Node, Module, Function, Args)

View Source
-spec block_call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
              when
                  Node :: node(),
                  Module :: module(),
                  Function :: atom(),
                  Args :: [term()],
                  Res :: term(),
                  Reason :: term().

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

Link to this function

block_call(Node, Module, Function, Args, Timeout)

View Source
-spec block_call(Node, Module, Function, Args, Timeout) -> Res | {badrpc, Reason}
              when
                  Node :: node(),
                  Module :: module(),
                  Function :: atom(),
                  Args :: [term()],
                  Res :: term(),
                  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/5 operations from executing concurrently on the node Node.

Warning

Note that it also blocks other operations than just rpc:block_call/5 operations, so use it with care.

Link to this function

call(Node, Module, Function, Args)

View Source
-spec call(Node, Module, Function, Args) -> Res | {badrpc, Reason}
        when
            Node :: node(),
            Module :: module(),
            Function :: atom(),
            Args :: [term()],
            Res :: term(),
            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).

Link to this function

call(Node, Module, Function, Args, Timeout)

View Source
-spec call(Node, Module, Function, Args, Timeout) -> Res | {badrpc, Reason}
        when
            Node :: node(),
            Module :: module(),
            Function :: atom(),
            Args :: [term()],
            Res :: term(),
            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.

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.

{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.

Link to this function

cast(Node, Module, Function, Args)

View Source
-spec cast(Node, Module, Function, Args) -> true
        when 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.

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.

Link to this function

eval_everywhere(Module, Function, Args)

View Source
-spec eval_everywhere(Module, Function, Args) -> abcast
                   when Module :: module(), Function :: atom(), Args :: [term()].

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

Link to this function

eval_everywhere(Nodes, Module, Function, Args)

View Source
-spec eval_everywhere(Nodes, Module, Function, Args) -> abcast
                   when
                       Nodes :: [node()], Module :: module(), Function :: atom(), Args :: [term()].

Evaluates apply(Module, Function, Args) on the specified nodes. No answers are collected.

Link to this function

multi_server_call(Name, Msg)

View Source
-spec multi_server_call(Name, Msg) -> {Replies, BadNodes}
                     when
                         Name :: atom(),
                         Msg :: term(),
                         Replies :: [Reply :: term()],
                         BadNodes :: [node()].

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

Link to this function

multi_server_call(Nodes, Name, Msg)

View Source
-spec multi_server_call(Nodes, Name, Msg) -> {Replies, BadNodes}
                     when
                         Nodes :: [node()],
                         Name :: atom(),
                         Msg :: term(),
                         Replies :: [Reply :: term()],
                         BadNodes :: [node()].

Can be used when 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.
Link to this function

multicall(Module, Function, Args)

View Source
-spec multicall(Module, Function, Args) -> {ResL, BadNodes}
             when
                 Module :: module(),
                 Function :: atom(),
                 Args :: [term()],
                 ResL :: [Res :: term() | {badrpc, Reason :: term()}],
                 BadNodes :: [node()].

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

-spec multicall(Nodes, Module, Function, Args) -> {ResL, BadNodes}
             when
                 Nodes :: [node()],
                 Module :: module(),
                 Function :: atom(),
                 Args :: [term()],
                 ResL :: [Res :: term() | {badrpc, Reason :: term()}],
                 BadNodes :: [node()];
         (Module, Function, Args, Timeout) -> {ResL, BadNodes}
             when
                 Module :: module(),
                 Function :: atom(),
                 Args :: [term()],
                 Timeout :: 0..4294967295 | infinity,
                 ResL :: [Res :: term() | {badrpc, Reason :: term()}],
                 BadNodes :: [node()].

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

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

Link to this function

multicall(Nodes, Module, Function, Args, Timeout)

View Source
-spec multicall(Nodes, Module, Function, Args, Timeout) -> {ResL, BadNodes}
             when
                 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, as all the requests are sent at the same time and are collected one by one as they come back.

The function evaluates apply(Module, Function, Args) on the specified nodes and collects the answers. It returns {ResL, BadNodes}, where BadNodes is a list of the nodes that do not exist, and ResL is a list of the return values, or {badrpc, Reason} for failing calls. Timeout is a time (integer) in milliseconds, or infinity.

The following example is useful when new object code is to be loaded on all nodes in the network, and indicates some side effects that RPCs can produce:

%% 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 may want to consider using the erpc:multicall() function from the erpc module instead.

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.

-spec nb_yield(Key) -> {value, Val} | timeout
            when Key :: key(), Val :: (Res :: term()) | {badrpc, Reason :: term()}.

Equivalent to nb_yield(Key, 0).

-spec nb_yield(Key, Timeout) -> {value, Val} | timeout
            when
                Key :: key(),
                Timeout :: 0..4294967295 | infinity,
                Val :: (Res :: term()) | {badrpc, Reason :: term()}.

Non-blocking version of yield/1. It returns the tuple {value, Val} when the computation is finished, or timeout when Timeout milliseconds has elapsed.

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.

Link to this function

parallel_eval(FuncCalls)

View Source
-spec parallel_eval(FuncCalls) -> ResL
                 when
                     FuncCalls :: [{Module, Function, Args}],
                     Module :: module(),
                     Function :: atom(),
                     Args :: [term()],
                     ResL :: [term()].

Evaluates, for every tuple in FuncCalls, apply(Module, Function, Args) on some node in the network. Returns the list of return values, in the same order as in FuncCalls.

-spec pinfo(Pid) -> [{Item, Info}] | undefined when Pid :: pid(), Item :: atom(), Info :: term().

Location transparent version of the BIF erlang:process_info/1 in ERTS.

-spec pinfo(Pid, Item) -> {Item, Info} | undefined | []
         when Pid :: pid(), Item :: atom(), Info :: term();
     (Pid, ItemList) -> [{Item, Info}] | undefined | []
         when Pid :: pid(), Item :: atom(), ItemList :: [Item], Info :: term().

Location transparent version of the BIF erlang:process_info/2 in ERTS.

Link to this function

pmap(FuncSpec, ExtraArgs, List1)

View Source
-spec pmap(FuncSpec, ExtraArgs, List1) -> List2
        when
            FuncSpec :: {Module, Function},
            Module :: module(),
            Function :: atom(),
            ExtraArgs :: [term()],
            List1 :: [Elem :: term()],
            List2 :: [term()].

Evaluates apply(Module, Function, [Elem|ExtraArgs]) for every element Elem in List1, in parallel. Returns the list of return values, in the same order as in List1.

-spec sbcast(Name, Msg) -> {GoodNodes, BadNodes}
          when Name :: atom(), Msg :: term(), GoodNodes :: [node()], BadNodes :: [node()].

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

Link to this function

sbcast(Nodes, Name, Msg)

View Source
-spec sbcast(Nodes, Name, Msg) -> {GoodNodes, BadNodes}
          when
              Name :: atom(),
              Msg :: term(),
              Nodes :: [node()],
              GoodNodes :: [node()],
              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 function is synchronous in the sense that it is known that all servers have received the message when the call returns. It is not possible to know that the servers have processed the message.

Any further messages sent to the servers, after this function has returned, are received by all servers after this message.

Link to this function

server_call(Node, Name, ReplyWrapper, Msg)

View Source
-spec server_call(Node, Name, ReplyWrapper, Msg) -> Reply | {error, Reason}
               when
                   Node :: node(),
                   Name :: atom(),
                   ReplyWrapper :: term(),
                   Msg :: term(),
                   Reply :: term(),
                   Reason :: nodedown.

Can be used when interacting with a server called Name on node Node. It is 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 ensures that the entire call is packed into an atomic transaction, which either succeeds or fails. It never hangs, unless the server itself hangs.

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

-spec yield(Key) -> Res | {badrpc, Reason} when Key :: key(), Res :: term(), Reason :: term().

Returns the promised answer from a previous async_call/4. If the answer is available, it is returned immediately. Otherwise, the calling process is suspended until the answer arrives from Node.

Note

This function must be called by the same process from which async_call/4 was made otherwise it will never return.

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