檢視原始碼 rpc (核心 v10.2)

遠端程序呼叫服務。

此模組包含類似於遠端程序呼叫的服務。它還包含廣播機制和平行求值器。遠端程序呼叫是一種在遠端節點上呼叫函數並收集答案的方法。它用於收集遠端節點上的資訊，或在遠端節點上執行具有特定副作用的函數。

注意
rpc:call/4 及其相關函數使得很難區分成功結果、引發的例外狀況和其他錯誤。由於相容性原因，這無法更改。從 OTP 23 開始，引入了一個新的模組 erpc，以便提供一個 API，使其能夠區分不同的結果。erpc 模組提供了 rpc 模組中可用功能的一個子集（但核心子集）。erpc 實作也提供了比原始 rpc 實作更具擴展性和效能的實作。但是，自 erpc 引入以來，rpc 模組使用 erpc 實作了其大部分核心功能，因此與 erpc 相比，rpc 模組在擴展性和效能方面不會受到影響。

注意
有關分散式訊號的一些重要資訊，請參閱《Erlang 參考手冊》的「程序」章節中的分散式阻塞訊號部分。阻塞訊號可能會導致 rpc 中的逾時顯著延遲。

摘要

類型

key()

由 async_call/4 傳回的不透明值。

函數

abcast(Name, Msg)

等同於 abcast([node()|nodes()], Name, Msg)。

abcast(Nodes, Name, Msg)

將訊息 Msg 非同步廣播到指定節點上已註冊的程序 Name。

async_call(Node, Module, Function, Args)

實作帶有 Promise 的呼叫流，這是一種 RPC 類型，不會暫停呼叫者，直到結果完成。相反，會傳回一個鍵，稍後可用於收集值。此鍵可視為交付答案的 Promise。

block_call(Node, Module, Function, Args)

與呼叫 rpc:block_call(Node, Module, Function, Args, infinity) 相同。

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

與呼叫 rpc:call(Node, Module, Function, Args, Timeout) 相同，但例外的是，它也會阻止在節點 Node 上同時執行其他 rpc:block_call/5 操作。

call(Node, Module, Function, Args)

在節點 Node 上評估 apply(Module, Function, Args) 並傳回對應的值 Res，如果呼叫失敗，則傳回 {badrpc, Reason}。與呼叫 rpc:call(Node, Module, Function, Args, infinity) 相同。

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

在節點 Node 上評估 apply(Module, Function, Args) 並傳回對應的值 Res，如果呼叫失敗，則傳回 {badrpc, Reason}。Timeout 是以毫秒為單位的逾時值。如果呼叫逾時，Reason 為 timeout。

cast(Node, Module, Function, Args)

在節點 Node 上評估 apply(Module, Function, Args)。不會傳回回應，且呼叫程序不會暫停，直到評估完成，就像 call/4,5 一樣。

eval_everywhere(Module, Function, Args)

等同於 eval_everywhere([node()|nodes()], Module, Function, Args)。

eval_everywhere(Nodes, Module, Function, Args)

在指定的節點上評估 apply(Module, Function, Args)。不會收集任何答案。

multi_server_call(Name, Msg)

等同於 multi_server_call([node()|nodes()], Name, Msg)。

multi_server_call(Nodes, Name, Msg)

在與指定節點上名為 Name 的伺服器互動時可以使用。假設伺服器接收 {From, Msg} 格式的訊息，並使用 From ! {Name, Node, Reply} 回覆，其中 Node 是伺服器所在節點的名稱。此函數傳回 {Replies, BadNodes}，其中 Replies 是所有 Reply 值的列表，而 BadNodes 是下列其中之一

multicall(Module, Function, Args)

等同於 multicall([node()|nodes()], Module, Function, Args, infinity)。

multicall/4

等同於 multicall(Nodes, Module, Function, Args, infinity)。

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

與 RPC 相反，多重呼叫是從一個用戶端同時傳送到多個伺服器的 RPC。這對於從一組節點收集資訊，或在多個節點上呼叫函數以達到某些副作用很有用。它的語義與在所有節點上反覆進行一系列 RPC 相同，但多重呼叫更快，因為所有請求同時傳送，並在它們返回時逐一收集。

nb_yield(Key)

等同於 nb_yield(Key, 0)。

nb_yield(Key, Timeout)

yield/1 的非阻塞版本。當計算完成時，它會傳回元組 {value, Val}，或當經過 Timeout 毫秒時，會傳回 timeout。

parallel_eval(FuncCalls)

針對 FuncCalls 中的每個元組，在網路中的某個節點上評估 apply(Module, Function, Args)。傳回傳回值的列表，其順序與 FuncCalls 中的順序相同。

pinfo(Pid)

ERTS 中 BIF erlang:process_info/1 的位置透明版本。

pinfo/2

ERTS 中 BIF erlang:process_info/2 的位置透明版本。

pmap(FuncSpec, ExtraArgs, List1)

針對 List1 中的每個元素 Elem，平行評估 apply(Module, Function, [Elem|ExtraArgs])。傳回傳回值的列表，其順序與 List1 中的順序相同。

sbcast(Name, Msg)

等同於 sbcast([node()|nodes()], Name, Msg)。

sbcast(Nodes, Name, Msg)

將訊息 Msg 同步廣播到指定節點上已註冊的程序 Name。

server_call(Node, Name, ReplyWrapper, Msg)

在與節點 Node 上名為 Name 的伺服器互動時可以使用。假設伺服器接收 {From, Msg} 格式的訊息，並使用 From ! {ReplyWrapper, Node, Reply} 回覆。此函數會進行此類伺服器呼叫，並確保整個呼叫會封裝在一個原子交易中，此交易會成功或失敗。它永遠不會掛起，除非伺服器本身掛起。

yield(Key)

從先前的 async_call/4 傳回已 Promise 的答案。如果答案可用，則會立即傳回。否則，呼叫程序會暫停，直到從 Node 收到答案為止。

類型

key()

-opaque key()

由 async_call/4 傳回的不透明值。

函數

abcast(Name, Msg)

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

等同於 abcast([node()|nodes()], Name, Msg)。

abcast(Nodes, Name, Msg)

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

將訊息 Msg 非同步廣播到指定節點上已註冊的程序 Name。

async_call(Node, Module, Function, Args)

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

在此情況下，會傳回鍵 Key，該鍵可用於後續呼叫 yield/1 或 nb_yield/1,2，以擷取在節點 Node 上評估 apply(Module, Function, Args) 的值。

注意
如果您需要區分結果的能力，則可能需要考慮改用 erpc 模組中的 erpc:send_request() 函數。這也會讓您能夠以其他有用的方式擷取結果。

注意
yield/1 和 nb_yield/1,2 必須由發出此函數的同一個程序呼叫，否則它們永遠不會正確產生結果。

注意
您無法對將執行 apply() 的程序做出任何假設。它可能是 rpc 伺服器、另一個伺服器或新產生程序。

block_call(Node, Module, Function, Args)

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

與呼叫 rpc:block_call(Node, Module, Function, Args, infinity) 相同。

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

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

與呼叫 rpc:call(Node, Module, Function, Args, Timeout) 相同，但例外的是，它也會阻止在節點 Node 上同時執行其他 rpc:block_call/5 操作。

警告
請注意，它也會封鎖除 rpc:block_call/5 操作之外的其他操作，因此請謹慎使用。

call(Node, Module, Function, Args)

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

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

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

如果回覆在呼叫逾時後到達，則不會有訊息污染呼叫者的訊息佇列。

注意
如果您需要區分結果的能力，則可能需要考慮改用 erpc 模組中的 erpc:call() 函數。

注意
以下是傳回值的確切詳細資訊。
在下列情況下，將傳回 {badrpc, Reason}
被呼叫的函數因 exit 例外狀況而失敗。
被呼叫的函數因 error 例外狀況而失敗。
被呼叫的函數傳回一個符合 {'EXIT', _} 的詞彙。
被呼叫的函數 throws 一個符合 {'EXIT', _} 的詞彙。
在下列情況下，將傳回 Res
被呼叫的函數正常傳回一個不符合 {'EXIT',_} 的詞彙。
被呼叫的函數 throw 一個不符合 {'EXIT',_} 的詞彙。

注意
您無法對將執行 apply() 的程序做出任何假設。它可能是呼叫程序本身、rpc 伺服器、另一個伺服器或新產生程序。

cast(Node, Module, Function, Args)

-spec cast(Node, Module, Function, Args) -> true
              when Node :: node(), Module :: module(), Function :: atom(), Args :: [term()].

在節點 Node 上評估 apply(Module, Function, Args)。不會傳回回應，且呼叫程序不會暫停，直到評估完成，就像 call/4,5 一樣。

注意
您無法對將執行 apply() 的程序做出任何假設。它可能是 rpc 伺服器、另一個伺服器或新產生程序。

eval_everywhere(Module, Function, Args)

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

等同於 eval_everywhere([node()|nodes()], Module, Function, Args)。

eval_everywhere(Nodes, Module, Function, Args)

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

在指定的節點上評估 apply(Module, Function, Args)。不會收集任何答案。

multi_server_call(Name, Msg)

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

等同於 multi_server_call([node()|nodes()], Name, Msg)。

multi_server_call(Nodes, Name, Msg)

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

不存在的節點清單
伺服器不存在的節點清單
伺服器在傳送任何回覆之前終止的節點清單。

multicall(Module, Function, Args)

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

等同於 multicall([node()|nodes()], Module, Function, Args, infinity)。

multicall/4

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

等同於 multicall(Nodes, Module, Function, Args, infinity)。

等同於 multicall([node()|nodes()], Module, Function, Args, Timeout)。

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

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

此函數會在指定的節點上評估 apply(Module, Function, Args) 並收集答案。它傳回 {ResL, BadNodes}，其中 BadNodes 是不存在的節點清單，而 ResL 是傳回值的列表，或失敗呼叫的 {badrpc, Reason}。Timeout 是以毫秒為單位的時間（整數）或 infinity。

以下範例在網路中所有節點上載入新物件程式碼時很有用，並指出 RPC 可能產生的一些副作用

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

注意
如果您需要區分結果的能力，您可能會考慮使用 erpc:multicall() 函式，它來自 erpc 模組。

注意
您無法對將執行 apply() 的程序做出任何假設。它可能是呼叫程序本身、rpc 伺服器、另一個伺服器或新產生程序。

nb_yield(Key)

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

等同於 nb_yield(Key, 0)。

nb_yield(Key, Timeout)

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

yield/1 的非阻塞版本。當計算完成時，它會傳回元組 {value, Val}，或當經過 Timeout 毫秒時，會傳回 timeout。

關於 Val 的更多詳細資訊，請參閱 call/4 中的註解。

注意
這個函式必須由發出 async_call/4 的同一個程序調用，否則只會返回 timeout。

parallel_eval(FuncCalls)

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

針對 FuncCalls 中的每個元組，在網路中的某個節點上評估 apply(Module, Function, Args)。傳回傳回值的列表，其順序與 FuncCalls 中的順序相同。

pinfo(Pid)

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

ERTS 中 BIF erlang:process_info/1 的位置透明版本。

pinfo/2

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

ERTS 中 BIF erlang:process_info/2 的位置透明版本。

pmap(FuncSpec, ExtraArgs, List1)

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

針對 List1 中的每個元素 Elem，平行評估 apply(Module, Function, [Elem|ExtraArgs])。傳回傳回值的列表，其順序與 List1 中的順序相同。

sbcast(Name, Msg)

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

等同於 sbcast([node()|nodes()], Name, Msg)。

sbcast(Nodes, Name, Msg)

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

將訊息 Msg 同步廣播到指定節點上已註冊的程序 Name。

返回 {GoodNodes, BadNodes}，其中 GoodNodes 是將 Name 作為註冊程序的節點列表。

此函數是同步的，意指當調用返回時，已知所有伺服器都已收到消息。但無法得知伺服器是否已處理該消息。

在此函數返回後，任何發送至伺服器的訊息，都會在此訊息之後由所有伺服器接收。

server_call(Node, Name, ReplyWrapper, Msg)

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

此函數返回伺服器 Name 產生的答案 Reply，或返回 {error, Reason}。

yield(Key)

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

從先前的 async_call/4 傳回已 Promise 的答案。如果答案可用，則會立即傳回。否則，呼叫程序會暫停，直到從 Node 收到答案為止。

注意
這個函式必須由發出 async_call/4 的同一個程序調用，否則永遠不會返回。

關於返回值的更多詳細資訊，請參閱 call/4 中的註解。