path: root/lib/kernel/doc/src/rpc.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2022</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>rpc</title>
    <prepared>Claes Wikstrom</prepared>
    <docno>1</docno>
    <date>1996-09-10</date>
    <rev>A</rev>
  </header>
  <module since="">rpc</module>
  <modulesummary>Remote Procedure Call services.</modulesummary>
  <description>
    <p>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.</p>
      <note><p>
	<c>rpc:call()</c> 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 <seeerl marker="erpc"><c>erpc</c></seeerl> was
	introduced in order to provide an API that makes it possible
	to distinguish between the different results. The <c>erpc</c>
	module provides a subset (however, the central subset) of the
	functionality available in the <c>rpc</c> module. The <c>erpc</c>
	implementation also provides a more scalable implementation with
	better performance than the original <c>rpc</c> implementation.
	However, since the introduction of <c>erpc</c>, the <c>rpc</c>
	module implements large parts of its central functionality using
	<c>erpc</c>, so the <c>rpc</c> module won't not suffer scalability
	wise and performance wise compared to <c>erpc</c>.
      </p></note>
      <note><p>
        For some important information about distributed signals, see the
        <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
          Blocking Signaling Over Distribution</seeguide> section in the
        <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
        Blocking signaling can, for example, cause timeouts in <c>rpc</c>
        to be significantly delayed.
      </p></note>
  </description>

  <datatypes>
    <datatype>
      <name name="key"/>
      <desc>
        <p>Opaque value returned by
          <seemfa marker="#async_call/4"><c>async_call/4</c></seemfa>.</p>
      </desc>
    </datatype>
  </datatypes>

  <funcs>
    <func>
      <name name="abcast" arity="2" since=""/>
      <fsummary>Broadcast a message asynchronously to a registered process on
        all nodes.</fsummary>
      <desc>
        <p>Equivalent to <c>abcast([node()|nodes()], <anno>Name</anno>,
        <anno>Msg</anno>)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="abcast" arity="3" since=""/>
      <fsummary>Broadcast a message asynchronously to a registered process on
        specific nodes.</fsummary>
      <desc>
        <p>Broadcasts the message <c><anno>Msg</anno></c> asynchronously to
          the registered process <c><anno>Name</anno></c> on the specified
          nodes.</p>
      </desc>
    </func>

    <func>
      <name name="async_call" arity="4" since=""/>
      <fsummary>Evaluate a function call on a node, asynchronous
      version.</fsummary>
      <desc>
        <p>Implements <em>call streams with promises</em>, 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.</p>
        <p>In this case, the key <c><anno>Key</anno></c> is returned, which
          can be used in a subsequent call to
          <seemfa marker="#yield/1"><c>yield/1</c></seemfa> or
          <seemfa marker="#nb_yield/1"><c>nb_yield/1,2</c></seemfa>
          to retrieve the value of evaluating <c>apply(<anno>Module</anno>,
          <anno>Function</anno>, <anno>Args</anno>)</c> on node
        <c><anno>Node</anno></c>.</p>
	<note>
	  <p>
	    If you want the ability to distinguish between results,
	    you may want to consider using the
	    <seemfa marker="erpc#send_request/4"><c>erpc:send_request()</c></seemfa>
	    function from the <c>erpc</c> module instead. This also
	    gives you the ability retrieve the results in other useful
	    ways.
	  </p>
	</note>
        <note>
          <p><seemfa marker="#yield/1"><c>yield/1</c></seemfa> and
            <seemfa marker="#nb_yield/1"><c>nb_yield/1,2</c></seemfa>
            must be called by the same process from which this function
            was made otherwise they will never yield correctly.</p>
        </note>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be an <c>rpc</c> server, another server, or a freshly
	    spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="block_call" arity="4" since=""/>
      <fsummary>Evaluate a function call on a node.</fsummary>
	<desc>
	<p>
	  The same as calling
	  <seemfa marker="#block_call/5"><c>rpc:block_call(<anno>Node</anno>,
	  <anno>Module</anno>, <anno>Function</anno>,
	  <anno>Args</anno>, infinity)</c></seemfa>.
	</p>
      </desc>
    </func>

    <func>
      <name name="block_call" arity="5" since=""/>
      <fsummary>Evaluate a function call on a node.</fsummary>
      <desc>
	  <p>
	    The same as calling
	    <seemfa marker="#call/5"><c>rpc:call(<anno>Node</anno>,
	    <anno>Module</anno>, <anno>Function</anno>,
	    <anno>Args</anno>, <anno>Timeout</anno>)</c></seemfa> with
	    the exception that it also blocks other <c>rpc:block_call()</c>
	    operations from executing concurrently on the node
	    <c><anno>Node</anno></c>.
	  </p>
	  <warning><p>
	    Note that it also blocks other operations than just
	    <c>rpc:block_call()</c> operations, so use it with care.
	  </p></warning>
      </desc>
    </func>

    <func>
      <name name="call" arity="4" since=""/>
      <fsummary>Evaluate a function call on a node.</fsummary>
      <desc>
        <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
        <anno>Args</anno>)</c> on node <c><anno>Node</anno></c> and returns
          the corresponding value <c><anno>Res</anno></c>, or
          <c>{badrpc, <anno>Reason</anno>}</c> if the call fails.
	  The same as calling
	  <seemfa marker="#call/5"><c>rpc:call(<anno>Node</anno>,
	  <anno>Module</anno>, <anno>Function</anno>,
	  <anno>Args</anno>, infinity)</c></seemfa>.
	</p>
      </desc>
    </func>

    <func>
      <name name="call" arity="5" since=""/>
      <fsummary>Evaluate a function call on a node.</fsummary>
      <desc>
        <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c> on node <c><anno>Node</anno></c> and returns
          the corresponding value <c><anno>Res</anno></c>, or
          <c>{badrpc, <anno>Reason</anno>}</c> if the call fails.
          <c><anno>Timeout</anno></c> is
          a time-out value in milliseconds. If the call times out,
          <c><anno>Reason</anno></c> is <c>timeout</c>.</p>
        <p>If the reply arrives after the call times out, no message
          contaminates the caller's message queue.</p>
	<note>
	  <p>
	    If you want the ability to distinguish between results,
	    you may want to consider using the
	    <seemfa marker="erpc#call/4"><c>erpc:call()</c></seemfa>
	    function from the <c>erpc</c> module instead.
	  </p>
	</note>
	<note>
	  <p>Here follows the details of what exactly is returned.</p>
	  <p><c>{badrpc, <anno>Reason</anno>}</c> will be returned in the
	  following circumstances:</p>
          <list type="bulleted">
            <item>The called function fails with an <c>exit</c> exception.</item>
            <item>The called function fails with an <c>error</c> exception.</item>
	    <item>The called function returns a term that matches
	    <c>{'EXIT', _}</c>.</item>
	    <item>The called function <c>throws</c>
	    a term that matches <c>{'EXIT', _}</c>.</item>
          </list>

	  <p><c><anno>Res</anno></c> is returned in the following circumstances:</p>
          <list type="bulleted">
            <item>The called function returns normally with a term that does
	    <strong>not</strong> match <c>{'EXIT',_}</c>.</item>
            <item>The called function <c>throw</c>s a term that does
	    <strong>not</strong> match <c>{'EXIT',_}</c>.</item>
          </list>
	</note>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be the calling process itself, an <c>rpc</c> server,
	    another server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="cast" arity="4" since=""/>
      <fsummary>Run a function on a node ignoring the result.</fsummary>
      <desc>
        <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c> on node
          <c><anno>Node</anno></c>. No response is delivered and the calling
          process is not suspended until the evaluation is complete, as
          is the case with
          <seemfa marker="#call/4"><c>call/4,5</c></seemfa>.</p>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be an <c>rpc</c> server, another server, or a
	    freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="eval_everywhere" arity="3" since=""/>
      <fsummary>Run a function on all nodes, ignoring the result.</fsummary>
      <desc>
        <p>Equivalent to <c>eval_everywhere([node()|nodes()],
          <anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="eval_everywhere" arity="4" since=""/>
      <fsummary>Run a function on specific nodes, ignoring the
        result.</fsummary>
      <desc>
        <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c> on
          the specified nodes. No answers are collected.</p>
      </desc>
    </func>

    <func>
      <name name="multi_server_call" arity="2" since=""/>
      <fsummary>Interact with the servers on a number of nodes.</fsummary>
      <desc>
        <p>Equivalent to <c>multi_server_call([node()|nodes()],
          <anno>Name</anno>, <anno>Msg</anno>)</c>.</p>
      </desc>
    </func>
    
    <func>
      <name name="multi_server_call" arity="3" since=""/>
      <fsummary>Interact with the servers on a number of nodes.</fsummary>
      <desc>
        <p>Can be used when interacting with servers called
          <c><anno>Name</anno></c> on the specified nodes. It is assumed that
          the servers receive messages in the format
          <c>{From, <anno>Msg</anno>}</c> and reply using
          <c>From ! {<anno>Name</anno>, Node, <anno>Reply</anno>}</c>, where
          <c>Node</c> is the name of the node where the server is located.
          The function returns <c>{<anno>Replies</anno>,
          <anno>BadNodes</anno>}</c>, where <c><anno>Replies</anno></c> is a
          list of all <c><anno>Reply</anno></c> values, and
          <c><anno>BadNodes</anno></c> is one of the following:</p>
        <list type="bulleted">
          <item>A list of the nodes that do not exist</item>
          <item>A list of the nodes where the server does not exist</item>
          <item>A list of the nodes where the server terminated before sending
          any reply.</item>
        </list>
      </desc>
    </func>

    <func>
      <name name="multicall" arity="3" since=""/>
      <fsummary>Evaluate a function call on a number of nodes.</fsummary>
      <desc>
        <p>Equivalent to <c>multicall([node()|nodes()], <anno>Module</anno>,
          <anno>Function</anno>, <anno>Args</anno>, infinity)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="multicall" arity="4" clause_i="1" since=""/>
      <fsummary>Evaluate a function call on a number of nodes.</fsummary>
      <desc>
        <p>Equivalent to <c>multicall(<anno>Nodes</anno>, <anno>Module</anno>,
          <anno>Function</anno>, <anno>Args</anno>, infinity)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="multicall" arity="4" clause_i="2" since=""/>
      <fsummary>Evaluate a function call on a number of nodes.</fsummary>
      <desc>
        <p>Equivalent to <c>multicall([node()|nodes()], <anno>Module</anno>,
          <anno>Function</anno>, <anno>Args</anno>,
          <anno>Timeout</anno>)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="multicall" arity="5" since=""/>
      <fsummary>Evaluate a function call on a number of nodes.</fsummary>
      <desc>
        <p>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.</p>
        <p>The function evaluates <c>apply(<anno>Module</anno>,
          <anno>Function</anno>, <anno>Args</anno>)</c>
          on the specified nodes and collects the answers. It returns
          <c>{<anno>ResL</anno>, <anno>BadNodes</anno>}</c>, where
          <c><anno>BadNodes</anno></c> is a list
          of the nodes that do not exist,
          and <c><anno>ResL</anno></c> is a list of the return values,
	  or <c>{badrpc, <anno>Reason</anno>}</c> for failing calls.
          <c><anno>Timeout</anno></c> is a time (integer) in milliseconds, or
          <c>infinity</c>.</p>
        <p>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:</p>
        <code type="none">
%% 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.</code>
	<note>
	  <p>
	    If you want the ability to distinguish between results,
	    you may want to consider using the
	    <seemfa marker="erpc#multicall/4"><c>erpc:multicall()</c></seemfa>
	    function from the <c>erpc</c> module instead.
	  </p>
	</note>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be the calling process itself, an <c>rpc</c> server,
	    another server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="nb_yield" arity="1" since=""/>
      <fsummary>Deliver the result of evaluating a function call on a node
        (non-blocking).</fsummary>
      <desc>
        <p>Equivalent to <c>nb_yield(<anno>Key</anno>, 0)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="nb_yield" arity="2" since=""/>
      <fsummary>Deliver the result of evaluating a function call on a node
        (non-blocking).</fsummary>
      <desc>
        <p>Non-blocking version of
          <seemfa marker="#yield/1"><c>yield/1</c></seemfa>. It returns
          the tuple <c>{value, <anno>Val</anno>}</c> when the computation is
          finished, or <c>timeout</c> when <c><anno>Timeout</anno></c>
          milliseconds has elapsed.</p>
	  <p>See the note in <seemfa marker="#call/4"><c>call/4</c></seemfa>
	  for more details of <anno>Val</anno>.</p>
        <note>
          <p>This function must be called by the same process from which
            <seemfa marker="#async_call/4"><c>async_call/4</c></seemfa>
            was made otherwise it will only return <c>timeout</c>.</p>
        </note>
      </desc>
    </func>

    <func>
      <name name="parallel_eval" arity="1" since=""/>
      <fsummary>Evaluate many function calls on all nodes in
        parallel.</fsummary>
      <desc>
        <p>Evaluates, for every tuple in <c><anno>FuncCalls</anno></c>,
          <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c> on some node in
          the network. Returns the list of return values, in the same
          order as in <c><anno>FuncCalls</anno></c>.</p>
      </desc>
    </func>

    <func>
      <name name="pinfo" arity="1" since=""/>
      <fsummary>Information about a process.</fsummary>
      <desc>
        <p>Location transparent version of the BIF
          <seemfa marker="erts:erlang#process_info/1"><c>erlang:process_info/1</c></seemfa> in ERTS.</p>
      </desc>
    </func>

    <func>
      <name name="pinfo" arity="2" clause_i="1" since=""/>
      <name name="pinfo" arity="2" clause_i="2" since=""/>
      <fsummary>Information about a process.</fsummary>
      <desc>
        <p>Location transparent version of the BIF
          <seemfa marker="erts:erlang#process_info/2"><c>erlang:process_info/2</c></seemfa> in ERTS.</p>
      </desc>
    </func>

    <func>
      <name name="pmap" arity="3" since=""/>
      <fsummary>Parallel evaluation of mapping a function over a
        list.</fsummary>
      <desc>
        <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          [<anno>Elem</anno>|<anno>ExtraArgs</anno>])</c> for every element
          <c><anno>Elem</anno></c> in <c><anno>List1</anno></c>, in parallel.
          Returns the list of return values, in the same order as in
          <c><anno>List1</anno></c>.</p>
      </desc>
    </func>

    <func>
      <name name="sbcast" arity="2" since=""/>
      <fsummary>Broadcast a message synchronously to a registered process on
        all nodes.</fsummary>
      <desc>
        <p>Equivalent to <c>sbcast([node()|nodes()], <anno>Name</anno>,
          <anno>Msg</anno>)</c>.</p>
      </desc>
    </func>

    <func>
      <name name="sbcast" arity="3" since=""/>
      <fsummary>Broadcast a message synchronously to a registered process on
        specific nodes.</fsummary>
      <desc>
        <p>Broadcasts the message <c><anno>Msg</anno></c> synchronously to
          the registered process <c><anno>Name</anno></c> on the specified
          nodes.</p>
        <p>Returns <c>{<anno>GoodNodes</anno>, <anno>BadNodes</anno>}</c>,
          where <c><anno>GoodNodes</anno></c> is the list of nodes that have
          <c><anno>Name</anno></c> as a registered process.</p>
        <p>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.</p>
        <p>Any further messages sent to the servers, after this
          function has returned, are received by all servers after
          this message.</p>
      </desc>
    </func>

    <func>
      <name name="server_call" arity="4" since=""/>
      <fsummary>Interact with a server on a node.</fsummary>
      <desc>
        <p>Can be used when interacting with a server called
          <c><anno>Name</anno></c> on node <c><anno>Node</anno></c>. It is
          assumed that the server receives messages in the format
          <c>{From, <anno>Msg</anno>}</c> and replies using
          <c>From ! {<anno>ReplyWrapper</anno>, <anno>Node</anno>,
          <anno>Reply</anno>}</c>. 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.</p>
        <p>The function returns the answer <c><anno>Reply</anno></c> as
          produced by the server <c><anno>Name</anno></c>, or
          <c>{error, <anno>Reason</anno>}</c>.</p>
      </desc>
    </func>

    <func>
      <name name="yield" arity="1" since=""/>
      <fsummary>Deliver the result of evaluating a function call on a node
        (blocking).</fsummary>
      <desc>
        <p>Returns the promised answer from a previous
          <seemfa marker="#async_call/4"><c>async_call/4</c></seemfa>.
          If the answer is available, it is
          returned immediately. Otherwise, the calling process is
          suspended until the answer arrives from <c>Node</c>.</p>
        <note>
          <p>This function must be called by the same process from which
            <seemfa marker="#async_call/4"><c>async_call/4</c></seemfa>
            was made otherwise it will never return.</p>
        </note>
	<p>See the note in <seemfa marker="#call/4"><c>call/4</c></seemfa>
	for more details of the return value.</p>
      </desc>
    </func>
  </funcs>
</erlref>