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

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

<erlref>
  <header>
    <copyright>
      <year>2020</year><year>2023</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>erpc</title>
    <prepared>Rickard Green</prepared>
    <docno>1</docno>
    <date>2020-02-20</date>
    <rev>A</rev>
  </header>
  <module since="OTP 23.0">erpc</module>
  <modulesummary>Enhanced Remote Procedure Call</modulesummary>
  <description>
    <p>
      This module provide services similar to Remote Procedure Calls.
      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>
    <p>
      This is an enhanced subset of the operations provided by the
      <seeerl marker="rpc"><c>rpc</c></seeerl> module. Enhanced in the
      sense that it makes it possible to distinguish between returned
      value, raised exceptions, and other errors. <c>erpc</c> also has
      better performance and scalability than the original <c>rpc</c>
      implementation. However, current <c>rpc</c> module will utilize
      <c>erpc</c> in order to also provide these properties when
      possible.
    </p>
    <p>
      In order for an <c>erpc</c> operation to succeed, the remote
      node also needs to support <c>erpc</c>. Typically only ordinary
      Erlang nodes as of OTP 23 have <c>erpc</c> support.
    </p>
    <p>
      Note that it is up to the user to ensure that correct code to
      execute via <c>erpc</c> is available on the involved nodes.
    </p>
    <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>erpc</c>
      to be significantly delayed.
    </p></note>
  </description>

  <datatypes>
    <datatype>
      <name name="request_id"/>
      <desc>
        <p>
	  An opaque request identifier. For more information see
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="request_id_collection"/>
      <desc>
        <p>
	  An opaque collection of request identifiers
          (<seetype marker="#request_id"><c>request_id()</c></seetype>)
          where each request identifier can be associated with a label
          chosen by the user. For more information see
          <seemfa marker="#reqids_new/0"><c>reqids_new/0</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="timeout_time"/>
      <desc>
        <taglist>
          <tag><c>0..4294967295</c></tag>
          <item><p>
            Timeout relative to current time in milliseconds.
          </p></item>
          <tag><c>infinity</c></tag>
          <item><p>
            Infinite timeout. That is, the operation will never time out.
          </p></item>
          <tag><c>{abs, Timeout}</c></tag>
          <item><p>
            An absolute
            <seemfa marker="erts:erlang#monotonic_time/1">Erlang monotonic time</seemfa>
            timeout in milliseconds. That is, the operation will time out when
            <seemfa marker="erts:erlang#monotonic_time/1"><c>erlang:monotonic_time(millisecond)</c></seemfa>
            returns a value larger than or equal to <c>Timeout</c>. <c>Timeout</c>
            is not allowed to identify a time further into the future than <c>4294967295</c>
            milliseconds. Identifying the timeout using an absolute timeout value
            is especially handy when you have a deadline for responses corresponding
            to a complete collection of requests
            (<seetype marker="#request_id_collection"><c>request_id_collection()</c></seetype>)
,
            since you do not have to recalculate the relative time until the deadline
            over and over again.
	  </p></item>
        </taglist>
      </desc>
    </datatype>

  </datatypes>

  <funcs>

    <func>
      <name name="call" arity="2" since="OTP 23.0"/>
      <name name="call" arity="3" since="OTP 23.0"/>
      <fsummary>Evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  The same as calling
	  <seemfa marker="#call/5"><c>erpc:call(<anno>Node</anno>,
          erlang, apply, [<anno>Fun</anno>,[]], <anno>Timeout</anno>)</c></seemfa>.
	  May raise all the same exceptions as <c>call/5</c>
	  plus an <c>{erpc, badarg}</c> <c>error</c>
	  exception if <c><anno>Fun</anno></c> is not a fun of
	  zero arity.
	</p>
	<p>
	  The call <c>erpc:call(<anno>Node</anno>,<anno>Fun</anno>)</c>
	  is the same as the call
	  <c>erpc:call(<anno>Node</anno>,<anno>Fun</anno>,infinity)</c>.
	</p>
      </desc>
    </func>

    <func>
      <name name="call" arity="4" since="OTP 23.0"/>
      <name name="call" arity="5" since="OTP 23.0"/>
      <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>Result</anno></c>.
          <c><anno>Timeout</anno></c> sets an upper time limit
          for the <c>call</c> operation to complete.
	</p>
	<p>The call <c>erpc:call(<anno>Node</anno>, <anno>Module</anno>,
	<anno>Function</anno>, <anno>Args</anno>)</c> is equivalent
	to the call <c>erpc:call(<anno>Node</anno>, <anno>Module</anno>,
	<anno>Function</anno>, <anno>Args</anno>, infinity)</c></p>
	<p>
	  The <c>call()</c> function only returns if the applied
	  function successfully returned without raising any uncaught
	  exceptions, the operation did not time out, and no failures
	  occurred. In all other cases an exception is raised. The
	  following exceptions, listed by exception class, can
	  currently be raised by <c>call()</c>:
	</p>
	<taglist>
	  <tag><c>throw</c></tag>
	  <item><p>
	    The applied function called <c>throw(Value)</c>
	    and did not catch this exception. The exception
	    reason <c>Value</c> equals the argument passed to
	    <c>throw/1</c>.
	  </p></item>
	  
	  <tag><c>exit</c></tag>
	  <item><p>
	    Exception reason:
	  </p>
	  <taglist>
	    <tag><c>{exception, ExitReason}</c></tag>
	    <item><p>
	      The applied function called <c>exit(ExitReason)</c>
	      and did not catch this exception. The exit
	      reason <c>ExitReason</c> equals the argument passed
	      to <c>exit/1</c>.
	    </p></item>
	    <tag><c>{signal, ExitReason}</c></tag>
	    <item><p>
	      The process that applied the function received an
	      exit signal and terminated due to this signal. The
	      process terminated with exit reason <c>ExitReason</c>.
	    </p></item>
	  </taglist>
	  </item>
	  
	  <tag><c>error</c></tag>
	  <item><p>
	    Exception reason:
	  </p>
	  <taglist>
	    
	    <tag><c>{exception, ErrorReason, StackTrace}</c></tag>
	    <item><p>
	      A runtime error occurred which raised an error
	      exception while applying the function,
	      and the applied function did not catch the
	      exception. The error reason <c>ErrorReason</c>
	      indicates the type of error that occurred.
	      <c>StackTrace</c> is formatted as when caught in a
	      <c>try/catch</c> construct. The <c>StackTrace</c>
	      is limited to the applied function and functions
	      called by it.
	    </p></item>
	    
	    <tag><c>{erpc, ERpcErrorReason}</c></tag>
	    <item><p>
	      The <c>erpc</c> operation failed. The following
	      <c>ERpcErrorReason</c>s are the most common ones:
	    </p>
	    
	    <taglist>
	      <tag><c>badarg</c></tag>
	      <item>
		<p>If any one of these are true:</p>
		<list>
		  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
		  <item><p><c><anno>Module</anno></c> is not an atom.</p></item>
		  <item><p><c><anno>Function</anno></c> is not an atom.</p></item>
		  <item><p><c><anno>Args</anno></c> is not a list.
		  Note that the list is not verified to be
		  a proper list at the client side.</p></item>
		  <item><p><c><anno>Timeout</anno></c> is
                  invalid.</p></item>
		</list>
	      </item>
	      
	      <tag><c>noconnection</c></tag>
	      <item><p>
		The connection to <c>Node</c> was lost or could
		not be established. The function may or may not
		be applied.
	      </p></item>
	      
	      <tag><c>system_limit</c></tag>
	      <item><p>
		The <c>erpc</c> operation failed due to some system
		limit being reached. This typically due to failure
		to create a process on the remote node <c>Node</c>,
		but can be other things as well.
	      </p></item>
	      
	      <tag><c>timeout</c></tag>
	      <item><p>
		The <c>erpc</c> operation timed out. The function may
		or may not be applied.
	      </p></item>
	      
	      <tag><c>notsup</c></tag>
	      <item><p>
		The remote node <c>Node</c> does not support
		this <c>erpc</c> operation.
	      </p>
	      </item>
	      
	    </taglist>
	    </item>
	    
	  </taglist>
	  </item>
	</taglist>

	<p>
	  If the <c>erpc</c> operation fails, but it is unknown if
	  the function is/will be applied (that is, a timeout or
	  a connection loss), the caller will not receive any
	  further information about the result if/when the applied
	  function completes. If the applied function explicitly
	  communicates with the calling process, such communication
	  may, of course, reach the calling process.
        </p>

	<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, a server, or a freshly
	    spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="cast" arity="2" since="OTP 23.0"/>
      <fsummary>Evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  The same as calling
	  <seemfa marker="#cast/4"><c>erpc:cast(<anno>Node</anno>,erlang,apply,[<anno>Fun</anno>,[]])</c></seemfa>.
	</p>
	<p><c>cast/2</c> fails with an <c>{erpc, badarg}</c>
	<c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Fun</anno></c> is not a a fun of zero arity.</p></item>
	</list>
      </desc>
    </func>

    <func>
      <name name="cast" arity="4" since="OTP 23.0"/>
      <fsummary>Evaluate a function call 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 to the
	  calling process. <c>cast()</c> returns immediately
	  after the cast request has been sent. Any failures beside
	  bad arguments are silently ignored.
	</p>
	<p><c>cast/4</c> fails with an <c>{erpc, badarg}</c>
	<c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Module</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Function</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Args</anno></c> is not a list. Note that
	  the list is not verified to be a proper list at the client
	  side.</p></item>
	</list>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be a server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>
    
    <func>
      <name name="check_response" arity="2" since="OTP 23.0"/>
      <fsummary>Check if a message is a response corresponding to a
      previously sent call request.</fsummary>
      <desc>
	<p>
	  Check if a message is a response to a <c>call</c> request
	  previously made by the calling process using
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
	  <c><anno>RequestId</anno></c> should be the value returned
	  from the previously made <c>send_request/4</c> call,
	  and the corresponding response should not already have been
	  received and handled to completion by <c>check_response/2</c>,
	  <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>, or
	  <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>.
	  <c><anno>Message</anno></c> is the message to check.
	</p>
	<p>
	  If <c><anno>Message</anno></c> does not correspond to the
	  response, the atom <c>no_response</c> is returned. If
	  <c><anno>Message</anno></c> corresponds to the response, the
	  <c>call</c> operation is completed and either the result is
	  returned as <c>{response, Result}</c> where <c>Result</c>
	  corresponds to the value returned from the applied function
	  or an exception is raised. The exceptions that can be raised
	  corresponds to the same exceptions as can be raised by
	  <seemfa marker="#call/4"><c>call/4</c></seemfa>.
	  That is, no <c>{erpc, timeout}</c> <c>error</c> exception
	  can be raised. <c>check_response()</c> will fail with
	  an <c>{erpc, badarg}</c> exception if/when an invalid
	  <c><anno>RequestId</anno></c> is detected.
	</p>
	<p>
	  If the <c>erpc</c> operation fails, but it is unknown if
	  the function is/will be applied (that is, a connection loss),
	  the caller will not receive any further information about the
	  result if/when the applied function completes. If the applied
	  function explicitly communicates with the calling process,
	  such communication may, of course, reach the calling process.
        </p>
      </desc>
    </func>

    <func>
      <name name="check_response" arity="3" since="OTP 25.0"/>
      <fsummary>Check if a message is a response corresponding to a
      previously sent call request.</fsummary>
      <desc>
        <p>
	  Check if a message is a response to a <c>call</c> request corresponding
          to a request identifier saved in <c><anno>RequestIdCollection</anno></c>.
          All request identifiers of <c><anno>RequestIdCollection</anno></c> must
          correspond to requests that have been made using
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa> or
	  <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>,
          and all requests must have been made by the process calling this
          function.
	</p>
        <p>
          <c><anno>Label</anno></c> is the label associated with the request
          identifier of the request that the response corresponds to.
          A request identifier is associated with a label when
          <seemfa marker="#reqids_add/3">adding a request identifier</seemfa>
          in a <seetype marker="#request_id_collection">request identifier
          collection</seetype>, or when sending the request using
          <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>.
        </p>
        <p>
          Compared to
          <seemfa marker="#check_response/2"><c>check_response/2</c></seemfa>,
          the returned result associated with a specific request identifier
          or an exception associated with a specific request identifier will
          be wrapped in a 3-tuple. The first element of this tuple equals the
          value that would have been produced by <c>check_response/2</c>,
          the second element equals the <c><anno>Label</anno></c> associated
          with the specific request identifier, and the third element
          <c><anno>NewRequestIdCollection</anno></c> is a possibly  modified
          request identifier collection. The <c>error</c> exception <c>{erpc,
          badarg}</c> is not associated with any specific request identifier,
          and will hence not be wrapped.
        </p>
        <p>
          If <c><anno>RequestIdCollection</anno></c> is empty, the atom
          <c>no_request</c> will be returned. If <c><anno>Message</anno></c>
          does not correspond to any of the request identifiers in
          <c><anno>RequestIdCollection</anno></c>, the atom
          <c>no_response</c> is returned.
        </p>
        <p>
          If <c><anno>Delete</anno></c> equals <c>true</c>, the association
          with <c><anno>Label</anno></c> will have been deleted from
          <c><anno>RequestIdCollection</anno></c> in the resulting
          <c><anno>NewRequestIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewRequestIdCollection</anno></c> will equal
          <c><anno>RequestIdCollection</anno></c>. Note that deleting an
          association is not for free and that a collection containing
          already handled requests can still be used by subsequent calls to
          <c>check_response/3</c>,
 	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
          and
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
          However, without deleting handled associations, the above calls will
          not be able to detect when there are no more outstanding requests to
          handle, so you will have to keep track of this some other way than
          relying on a <c>no_request</c> return. Note that if you pass a
          collection only containing associations of already handled or
          abandoned requests to <c>check_response/3</c>, it will always
          return <c>no_response</c>.
        </p>
        <p>
          Note that a response might have been consumed uppon an <c>{erpc,
          badarg}</c> exception and if so, will be lost for ever.
        </p>
      </desc>
    </func>

    <func>
      <name name="multicall" arity="2" since="OTP 23.0"/>
      <name name="multicall" arity="3" since="OTP 23.0"/>
      <fsummary>Evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  The same as calling
	  <seemfa marker="#multicall/5"><c>erpc:multicall(<anno>Nodes</anno>,
          erlang, apply, [<anno>Fun</anno>,[]], <anno>Timeout</anno>)</c></seemfa>.
	  May raise all the same exceptions as <c>multicall/5</c>
	  plus an <c>{erpc, badarg}</c> <c>error</c>
	  exception if <c><anno>Fun</anno></c> is not a fun of
	  zero arity.
	</p>
	<p>
	  The call <c>erpc:multicall(<anno>Nodes</anno>,<anno>Fun</anno>)</c>
	  is the same as the call
	  <c>erpc:multicall(<anno>Nodes</anno>,<anno>Fun</anno>, infinity)</c>.
	</p>
      </desc>
    </func>

    <func>
      <name name="multicall" arity="4" since="OTP 23.0"/>
      <name name="multicall" arity="5" since="OTP 23.0"/>
      <fsummary>Evaluate a function call on a number of nodes.</fsummary>
      <type name="caught_call_exception"/>
      <type name="stack_item"/>
      <desc>
	<p>
	  Performs multiple <c>call</c> operations in parallel
	  on multiple nodes. That is, evaluates
	  <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c> on the nodes <c><anno>Nodes</anno></c>
          in parallel. <c><anno>Timeout</anno></c> sets an upper time
          limit for all <c>call</c> operations to complete. The result
          is returned as a list where the result from each node is placed
          at the same position as the node name is placed in
          <c><anno>Nodes</anno></c>. Each item in the resulting list is
          formatted as either:
	</p>
	<taglist>
	  <tag><c>{ok, Result}</c></tag>
	  <item><p>
	    The <c>call</c> operation for this specific node
	    returned <c>Result</c>.
	  </p></item>
	  <tag><c>{Class, ExceptionReason}</c></tag>
	  <item><p>
	    The <c>call</c> operation for this specific node
	    raised an exception of class <c>Class</c> with
	    exception reason <c>ExceptionReason</c>. These
	    correspond to the exceptions that
	    <seemfa marker="#call/5"><c>call/5</c></seemfa>
	    can raise.
	  </p></item>
	</taglist>
	<p><c>multicall/5</c> fails with an <c>{erpc, badarg}</c>
	<c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Nodes</anno></c> is not a proper list of
	  atoms. Note that some requests may already have
	  been sent when the failure occurs. That is, the function
	  may or may not be applied on some nodes.</p></item>
	  <item><p><c><anno>Module</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Function</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Args</anno></c> is not a list. Note that the
	  list is not verified to be a proper list at the client side.</p></item>
	</list>
	<p>
	  The call <c>erpc:multicall(<anno>Nodes</anno>, <anno>Module</anno>,
	  <anno>Function</anno>, <anno>Args</anno>)</c> is equivalent
	  to the call <c>erpc:multicall(<anno>Nodes</anno>, <anno>Module</anno>,
	  <anno>Function</anno>, <anno>Args</anno>, infinity)</c>. These
	  calls are also equivalent to calling <c>my_multicall(Nodes, Module,
	  Function, Args)</c> below if one disregard performance and failure
	  behavior. <c>multicall()</c> can utilize a selective receive
          optimization which removes the need to scan the message queue from
          the beginning in order to find a matching message. The
	  <c>send_request()/receive_response()</c> combination can,
          however, not utilize this optimization.
	</p>
	<pre>
my_multicall(Nodes, Module, Function, Args) ->
  ReqIds = lists:map(fun (Node) ->
                       <seemfa marker="#send_request/4">erpc:send_request(Node, Module, Function, Args)</seemfa>
                     end,
                     Nodes),
  lists:map(fun (ReqId) ->
              try
                {ok, <seemfa marker="#receive_response/2">erpc:receive_response(ReqId, infinity)</seemfa>}
              catch
                Class:Reason ->
                  {Class, Reason}
              end
            end,
            ReqIds).
</pre>

	<p>
	  If an <c>erpc</c> operation fails, but it is unknown if
	  the function is/will be applied (that is, a timeout,
	  connection loss, or an improper <c><anno>Nodes</anno></c>
	  list), the caller will not receive any further information
	  about the result if/when the applied function completes.
	  If the applied function communicates
	  with the calling process, such communication may, of
	  course, reach the calling process.
	</p>

	<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, a server, or a freshly
	    spawned process.
	  </p>
	</note>
      </desc>
      
    </func>

    <func>
      <name name="multicast" arity="2" since="OTP 23.0"/>
      <fsummary>Evaluate a function call on a set nodes.</fsummary>
      <desc>
	<p>
	  The same as calling
	  <seemfa marker="#multicast/4"><c>erpc:multicast(<anno>Nodes</anno>,erlang,apply,[<anno>Fun</anno>,[]])</c></seemfa>.
	</p>
	<p><c>multicast/2</c> fails with an <c>{erpc, badarg}</c>
	<c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Nodes</anno></c> is not a proper list of atoms.</p></item>
	  <item><p><c><anno>Fun</anno></c> is not a a fun of zero arity.</p></item>
	</list>
      </desc>
    </func>

    <func>
      <name name="multicast" arity="4" since="OTP 23.0"/>
      <fsummary>Evaluate a function call on a set of nodes ignoring the result.</fsummary>
      <desc>
        <p>
	  Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
          <anno>Args</anno>)</c> on the nodes
          <c><anno>Nodes</anno></c>. No response is delivered to the
	  calling process. <c>multicast()</c> returns immediately
	  after the cast requests have been sent. Any failures beside
	  bad arguments are silently ignored.
	</p>
	<p><c>multicast/4</c> fails with an <c>{erpc, badarg}</c>
	<c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Nodes</anno></c> is not a proper list of
	  atoms. Note that some requests may already have
	  been sent when the failure occurs. That is, the function
	  may or may not be applied on some nodes.</p></item>
	  <item><p><c><anno>Module</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Function</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Args</anno></c> is not a list. Note that the
	  list is not verified to be a proper list at the client side.</p></item>
	</list>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be a server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="receive_response" arity="1" since="OTP 23.0"/>
      <fsummary>Receive a call response corresponding to a
      previously sent call request.</fsummary>
      <desc>
        <p>
          The same as calling
          <seemfa marker="#receive_response/2"><c>erpc:receive_response(<anno>RequestId</anno>,
          infinity)</c></seemfa>.
        </p>
      </desc>
    </func>

    <func>
      <name name="receive_response" arity="2" since="OTP 23.0"/>
      <fsummary>Receive a call response corresponding to a
      previously sent call request.</fsummary>
      <desc>
	<p>
	  Receive a response to a <c>call</c> request previously
	  made by the calling process using
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
	  <c><anno>RequestId</anno></c> should be the value returned from
	  the previously made <c>send_request/4</c> call, and
	  the corresponding response should not already have been received
	  and handled to completion by <c>receive_response()</c>,
	  <seemfa marker="#check_response/2"><c>check_response/4</c></seemfa>,
          or
	  <seemfa marker="#wait_response/2"><c>wait_response/4</c></seemfa>.
        </p>
        <p>
          <c><anno>Timeout</anno></c> sets an upper time limit on how
          long to wait for a response. If the operation times out, the request
          identified by <c><anno>RequestId</anno></c> will be abandoned, then an
          <c>{erpc, timeout}</c> <c>error</c> exception will be raised. That is,
          no response corresponding to the request will ever be received after a
          timeout. If a response is received, the <c>call</c> operation is
          completed and either the result is returned or an exception is raised. The
          exceptions that can be raised corresponds to the same exceptions as can
          be raised by <seemfa marker="#call/5"><c>call/5</c></seemfa>.
	  <c>receive_response/2</c> will fail with an <c>{erpc, badarg}</c>
	  exception if/when an invalid <c><anno>RequestId</anno></c> is detected
	  or if an invalid <c><anno>Timeout</anno></c> is passed.
	</p>

	<p>
	  A call to the function
	  <c>my_call(Node, Module, Function, Args, Timeout)</c>
	  below is equivalent to the call
	  <seemfa marker="#call/5"><c>erpc:call(Node, Module, Function, Args,
	  Timeout)</c></seemfa> if one disregards performance. <c>call()</c>
	  can utilize a selective receive optimization which removes
          the need to scan the message queue from the beginning in
          order to find a matching message. The
	  <c>send_request()/receive_response()</c> combination can,
          however, not utilize this optimization.
	</p>
	<pre>
my_call(Node, Module, Function, Args, Timeout) ->
  RequestId = <seemfa marker="#send_request/4">erpc:send_request(Node, Module, Function, Args)</seemfa>,
  erpc:receive_response(RequestId, Timeout).
</pre>
	<p>
	  If the <c>erpc</c> operation fails, but it is unknown if
	  the function is/will be applied (that is, a timeout, or
	  a connection loss), the caller will not receive any
	  further information about the result if/when the applied
	  function completes. If the applied function explicitly
	  communicates with the calling process, such communication
	  may, of course, reach the calling process.
        </p>
      </desc>
    </func>

    <func>
      <name name="receive_response" arity="3" since="OTP 25.0"/>
      <fsummary>Receive a call response corresponding to a
      previously sent call request.</fsummary>
      <desc>
        <p>
	  Receive a response to a <c>call</c> request corresponding to a request
          identifier saved in <c><anno>RequestIdCollection</anno></c>. All
          request identifiers of <c><anno>RequestIdCollection</anno></c> must
          correspond to requests that have been made using
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa> or
	  <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>,
          and all requests must have been made by the process calling this
          function.
	</p>
        <p>
          <c><anno>Label</anno></c> is the label associated with the request
          identifier of the request that the response corresponds to.
          A request identifier is associated with a label when
          <seemfa marker="#reqids_add/3">adding a request identifier</seemfa>
          in a <seetype marker="#request_id_collection">request identifier
          collection</seetype>, or when sending the request using
          <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>.
        </p>
        <p>
          Compared to
          <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>,
          the returned result associated with a specific request identifier
          or an exception associated with a specific request identifier will
          be wrapped in a 3-tuple. The first element of this tuple equals the
          value that would have been produced by <c>receive_response/2</c>,
          the second element equals the <c><anno>Label</anno></c> associated
          with the specific request identifier, and the third element
          <c><anno>NewRequestIdCollection</anno></c> is a possibly  modified
          request identifier collection. The <c>error</c> exceptions <c>{erpc,
          badarg}</c> and <c>{erpc, timeout}</c> are not associated with any
          specific request identifiers, and will hence not be wrapped.
        </p>
        <p>
          If <c><anno>RequestIdCollection</anno></c> is empty, the atom
          <c>no_request</c> will be returned.
        </p>
        <p>
          If the operation times out, all requests identified by
          <c><anno>RequestIdCollection</anno></c> will be abandoned, then an
          <c>{erpc, timeout}</c> <c>error</c> exception will be raised. That is,
          no responses corresponding to any of the request identifiers in
          <c><anno>RequestIdCollection</anno></c> will ever be received after a
          timeout. The difference between <c>receive_response/3</c> and
          <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>
          is that <c>receive_response/3</c> abandons the requests at timeout
          so that any potential future responses are ignored, while
          <c>wait_response/3</c> does not.
	</p>
        <p>
          If <c><anno>Delete</anno></c> equals <c>true</c>, the association
          with <c><anno>Label</anno></c> will have been deleted from
          <c><anno>RequestIdCollection</anno></c> in the resulting
          <c><anno>NewRequestIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewRequestIdCollection</anno></c> will equal
          <c><anno>RequestIdCollection</anno></c>. Note that deleting an
          association is not for free and that a collection containing
          already handled requests can still be used by subsequent calls to
          <c>receive_response/3</c>,
 	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>,
          and
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
          However, without deleting handled associations, the above calls will
          not be able to detect when there are no more outstanding requests to
          handle, so you will have to keep track of this some other way than
          relying on a <c>no_request</c> return. Note that if you pass a
          collection only containing associations of already handled or
          abandoned requests to <c>receive_response/3</c>, it will always block
          until a timeout determined by <c><anno>Timeout</anno></c> is
          triggered.
        </p>
        <p>
          Note that a response might have been consumed uppon an <c>{erpc,
          badarg}</c> exception and if so, will be lost for ever.
        </p>
      </desc>
    </func>
    
    <func>
      <name name="reqids_add" arity="3" since="OTP 25.0"/>
      <fsummary>Save a request identifier.</fsummary>
      <desc>
	<p>
          Saves <c><anno>RequestId</anno></c> and associates a
          <c><anno>Label</anno></c> with the request identifier by adding this
          information to <c><anno>RequestIdCollection</anno></c> and returning
          the resulting request identifier collection.
        </p>
      </desc>
    </func>

    <func>
      <name name="reqids_new" arity="0" since="OTP 25.0"/>
      <fsummary>Create a new empty request identifier collection.</fsummary>
      <desc>
	<p>
          Returns a new empty request identifier collection. A 
          request identifier collection can be utilized in order
          the handle multiple outstanding requests.
        </p>
        <p>
          Request identifiers of requests made by
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>
          can be saved in a request identifier collection using 
	  <seemfa marker="#reqids_add/3"><c>reqids_add/3</c></seemfa>.
          Such a collection of request identifiers can later be used in
          order to get one response corresponding to a request in the
          collection by passing the collection as argument to
          <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>,
	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
          and
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
        </p>
        <p>
          <seemfa marker="#reqids_size/1"><c>reqids_size/1</c></seemfa>
          can be used to determine the amount of request identifiers in a
          request identifier collection.
        </p>
      </desc>
    </func>

    <func>
      <name name="reqids_size" arity="1" since="OTP 25.0"/>
      <fsummary>Get size of a request identifier collection.</fsummary>
      <desc>
	<p>
          Returns the amount of request identifiers saved in
          <c><anno>RequestIdCollection</anno></c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="reqids_to_list" arity="1" since="OTP 25.0"/>
      <fsummary>Get a list a request identifier/label associations in a collection.</fsummary>
      <desc>
	<p>
          Returns a list of <c>{<anno>RequestId</anno>, <anno>Label</anno>}</c>
          tuples which corresponds to all request identifiers with their
          associated labels present in the <c><anno>RequestIdCollection</anno></c>
          collection.
        </p>
      </desc>
    </func>

    <func>
      <name name="send_request" arity="2" since="OTP 23.0"/>
      <fsummary>Send a request to evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  The same as calling
	  <seemfa marker="#send_request/4"><c>erpc:send_request(<anno>Node</anno>,
          erlang, apply, [<anno>Fun</anno>, []])</c></seemfa>.
	</p>
	<p>Fails with an <c>{erpc, badarg}</c> <c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Fun</anno></c> is not a fun of
	  zero arity.</p></item>
	</list>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be a server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>
    
    <func>
      <name name="send_request" arity="4" clause_i="1" since="OTP 23.0"/>
      <fsummary>Send a request to evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  Send an asynchronous <c>call</c> request to the node
	  <c><anno>Node</anno></c>. <c>send_request/4</c>
	  returns a request identifier that later is to be passed
	  to either
	  <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>,
	  <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>,
	  or,
	  <seemfa marker="#check_response/2"><c>check_response/2</c></seemfa>
	  in order to get the response of the call request. Besides passing
          the request identifier directly to these functions, it can also be
          added in a request identifier collection using 
	  <seemfa marker="#reqids_add/3"><c>reqids_add/3</c></seemfa>.
          Such a collection of request identifiers can later be used in
          order to get one response corresponding to a request in the
          collection by passing the collection as argument to
	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>,
	  or,
	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>.
          If you are about to save the request identifier in a request identifier
          collection, you may want to consider using
          <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>
          instead.
        </p>
        <p>
	  A call to the function
	  <c>my_call(Node, Module, Function, Args, Timeout)</c>
	  below is equivalent to the call
	  <seemfa marker="#call/5"><c>erpc:call(Node, Module, Function, Args,
	  Timeout)</c></seemfa> if one disregards performance. <c>call()</c>
	  can utilize a selective receive optimization which removes
          the need to scan the message queue from the beginning in
          order to find a matching message. The
	  <c>send_request()/receive_response()</c> combination can,
          however, not utilize this optimization.
	</p>
	<pre>
my_call(Node, Module, Function, Args, Timeout) ->
  RequestId = erpc:send_request(Node, Module, Function, Args),
  <seemfa marker="#receive_response/2">erpc:receive_response(RequestId, Timeout)</seemfa>.
</pre>
	<p>Fails with an <c>{erpc, badarg}</c> <c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Module</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Function</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Args</anno></c> is not a list. Note that the
	  list is not verified to be a proper list at the client side.</p></item>
	</list>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be a server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="send_request" arity="4" clause_i="2" since="OTP 25.0"/>
      <fsummary>Send a request to evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  The same as calling
	  <seemfa marker="#send_request/6"><c>erpc:send_request(<anno>Node</anno>,
          erlang, apply, [<anno>Fun</anno>,[]]), <anno>Label</anno>,
          <anno>RequestIdCollection</anno>)</c></seemfa>.
	</p>
	<p>Fails with an <c>{erpc, badarg}</c> <c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Fun</anno></c> is not a fun of zero arity.</p></item>
	  <item><p><c><anno>RequestIdCollection</anno></c> is detected not to
          be request identifier collection.</p></item>
	</list>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be a server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="send_request" arity="6" since="OTP 25.0"/>
      <fsummary>Send a request to evaluate a function call on a node.</fsummary>
      <desc>
	<p>
	  Send an asynchronous <c>call</c> request to the node
	  <c><anno>Node</anno></c>. The <c><anno>Label</anno></c> will be
          associated with the request identifier of the operation and
          added to the returned request identifier collection
          <c><anno>NewRequestIdCollection</anno></c>. The collection can
          later be used in order to get one response corresponding to a
          request in the collection by passing the collection as argument to
	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
	  <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>,
	  or,
	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>.
        </p>

        <p>
          The same as calling
          <seemfa marker="#reqids_add/3"><c>erpc:reqids_add</c></seemfa>(<seemfa
          marker="#send_request/4"><c>erpc:send_request</c></seemfa><c>(<anno>Node</anno>,
          <anno>Module</anno>, <anno>Function</anno>, <anno>Args</anno>),
          <anno>Label</anno>, <anno>RequestIdCollection</anno>)</c>, but
          calling <c>send_request/6</c> is slightly more efficient.
        </p>

	<p>Fails with an <c>{erpc, badarg}</c> <c>error</c> exception if:</p>
	<list>
	  <item><p><c><anno>Node</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Module</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Function</anno></c> is not an atom.</p></item>
	  <item><p><c><anno>Args</anno></c> is not a list. Note that the
	  list is not verified to be a proper list at the client side.</p></item>
	  <item><p><c><anno>RequestIdCollection</anno></c> is detected not to
          be request identifier collection.</p></item>
	</list>
	<note>
	  <p>
	    You cannot make <em>any</em> assumptions about the
	    process that will perform the <c>apply()</c>. It may
	    be a server, or a freshly spawned process.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="wait_response" arity="1" clause_i="1" since="OTP 23.0"/>
      <fsummary>Poll for a call response corresponding to a previously
      sent call request.</fsummary>
      <desc>
        <p>
          The same as calling
          <seemfa marker="#wait_response/2"><c>erpc:wait_response(<anno>RequestId</anno>,
          0)</c></seemfa>. That is, poll for a response message to a <c>call</c>
          request previously made by the calling process.
        </p>
      </desc>
    </func>

    <func>
      <name name="wait_response" arity="2" since="OTP 23.0"/>
      <fsummary>Wait or poll for a call response corresponding to a previously
      sent call request.</fsummary>
      <desc>
	<p>
	  Wait or poll for a response message to a <c>call</c> request
	  previously made by the calling process using
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>.
	  <c><anno>RequestId</anno></c> should be the value returned from
	  the previously made <c>send_request()</c> call, and the
	  corresponding response should not already have been received and handled
	  to completion by
	  <seemfa marker="#check_response/2"><c>check_response/2</c></seemfa>,
	  <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>,
	  or <c>wait_response()</c>.
	</p>
	<p>
          <c><anno>WaitTime</anno></c> sets an upper time limit on how long to wait
          for a response. If no response is received before the
          <c><anno>WaitTime</anno></c> timeout has triggered, the atom
          <c>no_response</c> is returned. It is valid to continue waiting for a
          response as many times as needed up until a response has been received
          and completed by <c>check_response()</c>, <c>receive_response()</c>, or
          <c>wait_response()</c>. If a response is received, the <c>call</c>
          operation is completed and either the result is returned as
          <c>{response, Result}</c> where <c>Result</c> corresponds to the value
          returned from the applied function or an exception is raised. The
          exceptions that can be raised corresponds to the same exceptions as can
          be raised by <seemfa marker="#call/4"><c>call/4</c></seemfa>.
	  That is, no <c>{erpc, timeout}</c> <c>error</c> exception can be raised.
	  <c>wait_response/2</c> will fail with an <c>{erpc, badarg}</c>
	  exception if/when an invalid <c><anno>RequestId</anno></c> is detected
	  or if an invalid <c><anno>WaitTime</anno></c> is passed.
	</p>
	<p>
	  If the <c>erpc</c> operation fails, but it is unknown if
	  the function is/will be applied (that is, a too large wait time
	  value, or a connection loss), the caller will not receive any
	  further information about the result if/when the applied function
	  completes. If the applied function explicitly communicates with the
	  calling process, such communication may, of course, reach the
	  calling process.
        </p>
      </desc>
    </func>

    <func>
      <name name="wait_response" arity="3" since="OTP 25.0"/>
      <fsummary>Wait or poll for a call response corresponding to a previously
      sent call request.</fsummary>
      <desc>
        <p>
	  Wait or poll for a response to a <c>call</c> request corresponding
          to a request identifier saved in <c><anno>RequestIdCollection</anno></c>. All
          request identifiers of <c><anno>RequestIdCollection</anno></c> must
          correspond to requests that have been made using
	  <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa> or
	  <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>,
          and all requests must have been made by the process calling this
          function.
	</p>
        <p>
          <c><anno>Label</anno></c> is the label associated with the request
          identifier of the request that the response corresponds to.
          A request identifier is associated with a label when
          <seemfa marker="#reqids_add/3">adding a request identifier</seemfa>
          in a <seetype marker="#request_id_collection">request identifier
          collection</seetype>, or when sending the request using
          <seemfa marker="#send_request/6"><c>send_request/6</c></seemfa>.
        </p>
        <p>
          Compared to
          <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>,
          the returned result associated with a specific request identifier
          or an exception associated with a specific request identifier will
          be wrapped in a 3-tuple. The first element of this tuple equals the
          value that would have been produced by <c>wait_response/2</c>,
          the second element equals the <c><anno>Label</anno></c> associated
          with the specific request identifier, and the third element
          <c><anno>NewRequestIdCollection</anno></c> is a possibly  modified
          request identifier collection. The <c>error</c> exception <c>{erpc,
          badarg}</c> is not associated with any specific request identifier,
          and will hence not be wrapped.
        </p>
        <p>
          If <c><anno>RequestIdCollection</anno></c> is empty, <c>no_request</c>
          will be returned. If no response is received before the
          <c><anno>WaitTime</anno></c> timeout has triggered, the atom
          <c>no_response</c> is returned. It is valid to continue waiting for a
          response as many times as needed up until a response has been received
          and completed by <c>check_response()</c>, <c>receive_response()</c>,
          or <c>wait_response()</c>. The difference between
          <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>
	  and <c>wait_response/3</c> is that <c>receive_response/3</c>
	  abandons requests at timeout so that any potential future
	  responses are ignored, while <c>wait_response/3</c> does not.
        </p>
        <p>
          If <c><anno>Delete</anno></c> equals <c>true</c>, the association
          with <c><anno>Label</anno></c> will have been deleted from
          <c><anno>RequestIdCollection</anno></c> in the resulting
          <c><anno>NewRequestIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewRequestIdCollection</anno></c> will equal
          <c><anno>RequestIdCollection</anno></c>. Note that deleting an
          association is not for free and that a collection containing
          already handled requests can still be used by subsequent calls to
          <c>wait_response/3</c>,
 	  <seemfa marker="#check_response/3"><c>check_response/3</c></seemfa>,
          and
	  <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>.
          However, without deleting handled associations, the above calls will
          not be able to detect when there are no more outstanding requests to
          handle, so you will have to keep track of this some other way than
          relying on a <c>no_request</c> return. Note that if you pass a
          collection only containing associations of already handled or
          abandoned requests to <c>wait_response/3</c>, it will always block
          until a timeout determined by <c><anno>WaitTime</anno></c> is
          triggered and then return <c>no_response</c>.
        </p>
        <p>
          Note that a response might have been consumed uppon an <c>{erpc,
          badarg}</c> exception and if so, will be lost for ever.
        </p>
      </desc>
    </func>
    
  </funcs>
</erlref>