path: root/lib/stdlib/doc/src/gen_server.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>gen_server</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module since="">gen_server</module>
  <modulesummary>Generic server behavior.</modulesummary>
  <description>
    <p>This behavior module provides the server of a client-server
      relation. A generic server process (<c>gen_server</c>) implemented using
      this module has a standard set of interface functions and
      includes functionality for tracing and error reporting. It also
      fits into an OTP supervision tree. For more information, see section
      <seeguide marker="system/design_principles:gen_server_concepts">
      gen_server Behaviour</seeguide> in OTP Design Principles.</p>

    <p>A <c>gen_server</c> process assumes all specific parts to be located in
      a callback module exporting a predefined set of functions.
      The relationship between the behavior functions and the callback
      functions is as follows:</p>

    <pre>
gen_server module            Callback module
-----------------            ---------------
gen_server:start
gen_server:start_monitor
gen_server:start_link -----> Module:init/1

gen_server:stop       -----> Module:terminate/2

gen_server:call
gen_server:send_request
gen_server:multi_call -----> Module:handle_call/3

gen_server:cast
gen_server:abcast     -----> Module:handle_cast/2

-                     -----> Module:handle_info/2

-                     -----> Module:handle_continue/2

-                     -----> Module:terminate/2

-                     -----> Module:code_change/3</pre>

    <p>If a callback function fails or returns a bad value, the
      <c>gen_server</c> process terminates.</p>

    <p>A <c>gen_server</c> process handles system messages as described in
      <seeerl marker="sys"><c>sys(3)</c></seeerl>. The <c>sys</c> module
      can be used for debugging a <c>gen_server</c> process.</p>

    <p>Notice that a <c>gen_server</c> process does not trap exit signals
      automatically, this must be explicitly initiated in the callback
      module.</p>

    <p>Unless otherwise stated, all functions in this module fail if
      the specified <c>gen_server</c> process does not exist or if bad
      arguments are specified.</p>

    <p>The <c>gen_server</c> process can go into hibernation
      (see <seemfa marker="erts:erlang#hibernate/3">
      <c>erlang:hibernate/3</c></seemfa>) if a callback
      function specifies <c>'hibernate'</c> instead of a time-out value. This
      can be useful if the server is expected to be idle for a long
      time. However, use this feature with care, as hibernation
      implies at least two garbage collections (when hibernating and
      shortly after waking up) and is not something you want to do
      between each call to a busy server.</p>

    <p>If the <c>gen_server</c> process needs to perform an action
      immediately after initialization or to break the execution of a
      callback into multiple steps, it can return <c>{continue,Continue}</c>
      in place of the time-out or hibernation value, which will immediately
      invoke the <c>handle_continue/2</c> callback.</p>

    <p>If the <c>gen_server</c> process terminates, e.g.
      as a result of a function in the callback module returning
      <c>{stop,Reason,NewState}</c>, an exit signal with this <c>Reason</c>
      is sent to linked processes and ports. See
      <seeguide marker="system/reference_manual:processes#errors">
      Processes</seeguide> in the Reference Manual for details
      regarding error handling using exit signals.</p>

  </description>



  <datatypes>
    <datatype>
      <name name="server_name"/>
      <desc>
        <p>
          Name specification to use when starting a <c>gen_server</c>.
          See functions
          <seemfa marker="#start/3"><c>start/3,4</c></seemfa>,
          <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>,
          <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>,
          <seemfa marker="#enter_loop/3"><c>enter_loop/3,4,5</c></seemfa>,
          and the type
	  <seetype marker="#server_ref"><c>server_ref()</c></seetype>
	  below.
        </p>
        <taglist>
          <tag><c>{local,<anno>LocalName</anno>}</c></tag>
          <item>
            <p>
              Register the <c>gen_server</c> locally
              as <c><anno>LocalName</anno></c> using
              <seemfa marker="erts:erlang#register/2">
                <c>register/2</c></seemfa>.
            </p>
          </item>
          <tag><c>{global,<anno>GlobalName</anno>}</c></tag>
          <item>
            <p>
              Register the <c>gen_server</c> process id
              globally as <c>GlobalName</c> using
              <seemfa marker="kernel:global#register_name/2">
                <c>global:register_name/2</c></seemfa>.
            </p>
          </item>
          <tag><c>{via,<anno>RegMod</anno>,<anno>ViaName</anno>}</c></tag>
          <item>
            <p>
              Register the <c>gen_server</c> process with the registry
              represented by <c><anno>RegMod</anno></c>.
              The <c><anno>RegMod</anno></c> callback is to export
              the functions <c>register_name/2</c>, <c>unregister_name/1</c>,
              <c>whereis_name/1</c>, and <c>send/2</c>, which are to behave
              like the corresponding functions in
              <seeerl marker="kernel:global"><c>global</c></seeerl>.
              Thus, <c>{via,global,<anno>GlobalName</anno>}</c>
              is a valid reference equivalent to
              <c>{global,<anno>GlobalName</anno>}</c>.
            </p>
          </item>
        </taglist>
      </desc>
    </datatype>

    <datatype>
      <name name="server_ref"/>
      <desc>
	<p>
	  Server specification to use when addressing
	  a <c>gen_server</c>.
	  See <seemfa marker="#call/2"><c>call/2,3</c></seemfa>,
	  <seemfa marker="#cast/2"><c>cast/2</c></seemfa>,
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>,
	  <seemfa marker="#check_response/2"><c>check_response/2</c></seemfa>,
	  <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>,
	  <seemfa marker="#stop/1"><c>stop/2,3</c></seemfa>
          and the type
	  <seetype marker="#server_name"><c>server_name()</c></seetype>
	  above.
	</p>
	<p>It can be:</p>
	<taglist>
	  <tag><c>pid()</c></tag>
	  <item>
            <p>
              The <c>gen_server</c>'s process identifier.
            </p>
          </item>
	  <tag><c><anno>LocalName</anno></c></tag>
	  <item>
            <p>
              The <c>gen_server</c> is locally registered
              as <c><anno>LocalName</anno></c> with
              <seemfa marker="erts:erlang#register/2">
                <c>register/2</c></seemfa>.
            </p>
          </item>
	  <tag><c>{<anno>Name</anno>,<anno>Node</anno>}</c></tag>
	  <item>
            <p>
	      The <c>gen_server</c> is locally registered
	      on another node.
            </p>
	  </item>
	  <tag><c>{global,<anno>GlobalName</anno>}</c></tag>
	  <item>
            <p>
	      The <c>gen_server</c> is globally registered in
	      <seeerl marker="kernel:global"><c>global</c></seeerl>.
            </p>
	  </item>
	  <tag><c>{via,<anno>RegMod</anno>,<anno>ViaName</anno>}</c></tag>
	  <item>
            <p>
	      The <c>gen_server</c> is registered in
	      an alternative process registry.
	      The registry callback module <c><anno>RegMod</anno></c>
	      is to export functions
	      <c>register_name/2</c>, <c>unregister_name/1</c>,
	      <c>whereis_name/1</c>, and <c>send/2</c>,
	      which are to behave like the corresponding functions in
	      <seeerl marker="kernel:global"><c>global</c></seeerl>.
	      Thus, <c>{via,global,<anno>GlobalName</anno>}</c>
              is the same as <c>{global,<anno>GlobalName</anno>}</c>.
            </p>
	  </item>
	</taglist>
      </desc>
    </datatype>

    <datatype>
      <name name="start_opt"/>
      <desc>
	<p>
	  Options that can be used when starting
	  a <c>gen_server</c> server through, for example,
	  <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
	</p>
        <taglist>
          <tag><c>{timeout,<anno>Timeout</anno>}</c></tag>
          <item>
            <p>
              How many milliseconds the <c>gen_server</c> process is allowed
              to spend initializing or it is terminated and the
              start function returns <c>{error,timeout}</c>.
            </p>
          </item>
          <tag>
            <c>{spawn_opt,<anno>SpawnOptions</anno>}</c>
          </tag>
          <item>
            <p>
              The <c><anno>SpawnOptions</anno></c> option list
              is passed to the function used to spawn
              the <c>gen_server</c>; see
              <seemfa marker="erts:erlang#spawn_opt/2">
                <c>spawn_opt/2</c></seemfa>.
            </p>
            <note>
              <p>
                Using spawn option <c>monitor</c> is not
                allowed, it causes a <c>badarg</c> failure.
              </p>
            </note>
          </item>
          <tag><c>enter_loop_opt()</c></tag>
          <item>
            <p>
              See the type
              <seetype marker="#enter_loop_opt"><c>enter_loop_opt()</c></seetype>
              below for more start options that are also allowed by
              <seemfa marker="#enter_loop/3"><c>enter_loop/3,4,5</c></seemfa>.
            </p>
          </item>
        </taglist>
      </desc>
    </datatype>

    <datatype>
      <name name="enter_loop_opt"/>
      <desc>
	<p>
	  Options that can be used when starting
	  a <c>gen_server</c> server through
	  <seemfa marker="#enter_loop/3"><c>enter_loop/3-5</c></seemfa>
          or the start functions such as
	  <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
	</p>
	<taglist>
	  <tag><c>{hibernate_after,<anno>HibernateAfterTimeout</anno>}</c></tag>
	  <item>
            <p>
	      Specifies that the <c>gen_server</c> process awaits
	      any message for <c>HibernateAfterTimeout</c> milliseconds and
              if no message is received, the process goes into hibernation
	      automatically (by calling
	      <seemfa marker="proc_lib#hibernate/3">
                <c>proc_lib:hibernate/3</c></seemfa>).
            </p>
	  </item>
	  <tag><c>{debug,<anno>Dbgs</anno>}</c></tag>
	  <item>
            <p>
	      For every entry in <c><anno>Dbgs</anno></c>,
	      the corresponding function in
	      <seeerl marker="sys"><c>sys(3)</c></seeerl> is called.
            </p>
	  </item>
	</taglist>
      </desc>
    </datatype>

    <datatype>
      <name name="start_ret"/>
      <desc>
	<p>
	  Return value from the
          <seemfa marker="#start/3"><c>start/3,4</c></seemfa>
          and
          <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>
          functions.
	</p>
        <taglist>
          <tag><c>{ok,<anno>Pid</anno>}</c></tag>
          <item>
            <p>
              The <c>gen_server</c> process was succesfully created
              and initialized, with the process identifier
              <c><anno>Pid</anno></c>.
            </p>
          </item>
          <tag><c>{error,{already_started,OtherPid}}</c></tag>
          <item>
            <p>
              A process with the specified <c>ServerName</c> exists already
              with the process identifier <c>OtherPid</c>.
              This <c>gen_server</c> was not started.
            </p>
          </item>
          <tag><c>ignore</c></tag>
          <item>
            <p>
              <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
              returned <c>ignore</c>, the <c>gen_server</c> process
              is terminated.  An exit signal <c>normal</c> is sent
              to linked processes and ports.
            </p>
          </item>
          <tag><c>{error,<anno>Reason</anno>}</c></tag>
          <item>
            <p>
              <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
              returned <c>{stop,<anno>Reason</anno>}</c>
              or failed with <c><anno>Reason</anno></c>.
              The <c>gen_server</c> process is terminated and
              an exit signal with the same <c><anno>Reason</anno></c>
              is sent to linked processes and ports.
            </p>
          </item>
        </taglist>
      </desc>
    </datatype>

    <datatype>
      <name name="start_mon_ret"/>
      <desc>
	<p>
	  Return value from the
	  <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>
	  functions.
          The same as type
          <seetype marker="#start_ret"><c>start_ret()</c></seetype>
          except that for a succesful start it returns both
          the process identifier <c><anno>Pid</anno></c> and a
          <seemfa marker="erts:erlang#monitor/2"><c>monitor/2,3</c></seemfa>
          <c>reference()</c> <c><anno>MonRef</anno></c>.
	</p>
      </desc>
    </datatype>

    <datatype>
      <name name="from"/>
      <desc>
	<p>
          Destination, given to the <c>gen_server</c>
          as the first argument to the callback function
          <seemfa marker="#Module:handle_call/3"><c>Module:handle_call/3</c></seemfa>,
          to be used by the when replying through
	  <seemfa marker="#reply/2"><c>reply/2</c></seemfa>
          (instead of through the callback function's return value)
	  to the process <c><anno>Client</anno></c>
          that has called the <c>gen_server</c> using
	  <seemfa marker="#call/2"><c>call/2,3</c></seemfa>.
          <c><anno>Tag</anno></c> is a term that is unique
          for this call/request instance.
	</p>
      </desc>
    </datatype>

    <datatype>
      <name name="reply_tag"/>
      <desc>
        <p>
          A handle that associates a reply to the corresponding request.
        </p>
      </desc>
    </datatype>

    <datatype>
      <name name="request_id"/>
      <desc>
	<p>
	  An opaque request identifier. See
          <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>
	  for details.
	</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="response_timeout"/>
      <desc>
        <p>
          Used to set a time limit on how long to wait for a response using
          either 
          <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>,
          <seemfa marker="#receive_response/3"><c>receive_response/3</c></seemfa>,
          <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>,
          or
          <seemfa marker="#wait_response/3"><c>wait_response/3</c></seemfa>.
          The time unit used is <c>millisecond</c>. Currently valid values:
        </p>
        <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>

    <datatype>
      <name name="format_status"/>
      <desc>
        <p>
          A map that describes the <c>gen_server</c> status.
          The keys are:
        </p>
        <taglist>
          <tag><c>state</c></tag>
          <item>The internal state of the <c>gen_server</c> process.</item>
          <tag><c>message</c></tag>
          <item>The message that caused the server to terminate.</item>
          <tag><c>reason</c></tag>
          <item>The reason that caused the server to terminate.</item>
          <tag><c>log</c></tag>
          <item>
            The <seemfa marker="sys#log/2">sys log</seemfa> of the server.
          </item>
        </taglist>
        <p>
          New associations may be added to the status map
          without prior notice.
        </p>
      </desc>
    </datatype>
  </datatypes>



  <funcs>
    <func>
      <name name="abcast" arity="2" since=""/>
      <name name="abcast" arity="3" since=""/>
      <fsummary>
        Send an asynchronous request to many generic servers.
      </fsummary>
      <desc>
        <p>
          Sends an asynchronous request to the <c>gen_server</c> processes
          locally registered as <c><anno>Name</anno></c>
          at the specified nodes. The function
          returns immediately and ignores nodes that do not exist, or
          where the <c>gen_server</c>
          <c><anno>Name</anno></c> does not exist.
          The <c>gen_server</c> processes call
          <seemfa marker="#Module:handle_cast/2">
            <c>Module:handle_cast/2</c>
            </seemfa> to handle the request.
        </p>
        <p>
          For a description of the arguments, see
          <seemfa marker="#multi_call/2"><c>multi_call/2,3,4</c></seemfa>.
        </p>
      </desc>
    </func>

    <func>
      <name name="call" arity="2" since=""/>
      <name name="call" arity="3" since=""/>
      <fsummary>Make a synchronous call to a generic server.</fsummary>
      <desc>
        <p>
          Makes a synchronous call to the
          <c><anno>ServerRef</anno></c> of the <c>gen_server</c> process
          by sending a request and waiting until a reply arrives or a
          time-out occurs. The <c>gen_server</c> process calls
          <seemfa marker="#Module:handle_call/3">
            <c>Module:handle_call/3</c>
          </seemfa>
          to handle the request.
        </p>
        <p>
          See also <c><anno>ServerRef</anno></c>'s type
          <seetype marker="#server_ref"><c>server_ref()</c></seetype>.
        </p>
        <p>
          <c><anno>Request</anno></c> is any term that is passed as the
          first argument to <c>Module:handle_call/3</c>.
        </p>
        <p>
          <c><anno>Timeout</anno></c> is an integer that
          specifies how many milliseconds to wait for a reply, or
          the atom <c>infinity</c> to wait indefinitely.
          Defaults to 5000.
          If no reply is received within the specified time,
          this function exits the calling process with an exit term
          containing <c>Reason&nbsp;=&nbsp;timeout</c> as described below.
        </p>
        <note>
          <p>
            Before OTP 24, if the caller uses (<c>try</c>...)<c>catch</c>
            to avoid process exit,
            and the server happens to just be late with the reply,
            it may arrive to the process message queue any time later.
            The calling process must therefore after catching a time-out exit
            be prepared to receive garbage message(s)
            on the form <c>{reference(),&nbsp;_}</c>
            and deal with them appropriately (discard them)
            so they do not clog the process message queue
            or gets mistaken for other messages.
          </p>
          <p>
            Starting with OTP 24, <c>gen_server:call</c> uses process aliases,
            so late replies will not be received.
          </p>
        </note>
        <p>
          The return value <c><anno>Reply</anno></c>
          is passed from the return value of <c>Module:handle_call/3</c>.
        </p>
        <p>
          This call may exit the calling process
          with an exit term on the form
          <c>{Reason,&nbsp;Location}</c> where
          <c>Location&nbsp;=&nbsp;{gen_server,call,ArgList}</c>
          and <c>Reason</c> can be (at least) one of:
        </p>
        <taglist>
          <tag><c>timeout</c></tag>
          <item>
            <p>
              The call was aborted after waiting
              <c><anno>Timeout</anno></c> milliseconds for a reply,
              as described above.
            </p>
          </item>
          <tag><c>noproc</c></tag>
          <item>
            <p>
              The <c><anno>ServerRef</anno></c> refers to
              a server by name (it is not a <c>pid()</c>)
              and looking up the server process failed,
              or the <c>pid()</c> was already terminated.
            </p>
          </item>
          <tag><c>{nodedown,Node}</c></tag>
          <item>
            <p>
              The <c><anno>ServerRef</anno></c> refers to a server
              on the remote node <c>Node</c> and the connection
              to that node failed.
            </p>
          </item>
          <tag><c>calling_self</c></tag>
          <item>
            <p>A call to <c>self()</c> would hang indefinitely.</p>
          </item>
          <tag>
            <c>shutdown</c><br/>
          </tag>
          <item>
            <p>
              The server was stopped during the call
              by its supervisor.  See also
              <seemfa marker="#stop/3"><c>stop/3</c></seemfa>.
            </p>
          </item>
          <tag>
            <c>normal</c><br/>
            <c>{shutdown,Term}</c><br/>
          </tag>
          <item>
            <p>
              The server stopped during the call by returning
              <c>{stop,Reason,_}</c> from its
              <seemfa marker="#Module:handle_call/3">
                <c>Module:handle_call/3</c>
              </seemfa>
              callback, without replying.  See also
              <seemfa marker="#stop/3"><c>stop/3</c></seemfa>.
            </p>
          </item>
          <tag><c>_OtherTerm</c></tag>
          <item>
            <p>
              The server process exited during the call,
              with reason <c>Reason</c>.  Either by returning
              <c>{stop,Reason,_}</c> from its
              <seemfa marker="#Module:handle_call/3">
                <c>Module:handle_call/3</c>
              </seemfa>
              callback (without replying),
              by raising an exception,
              or due to getting an exit signal it did not trap.
            </p>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="cast" arity="2" since=""/>
      <fsummary>Send an asynchronous request to a generic server.</fsummary>
      <desc>
        <p>
          Sends an asynchronous request to the
          <c><anno>ServerRef</anno></c> of the
          <c>gen_server</c> process and returns <c>ok</c> immediately,
          ignoring if the destination node or <c>gen_server</c> process
          does not exist.
          The <c>gen_server</c> process calls
          <seemfa marker="#Module:handle_cast/2">
            <c>Module:handle_cast/2</c>
          </seemfa>
          to handle the request.
        </p>
        <p>
          See also <c><anno>ServerRef</anno></c>'s type
          <seetype marker="#server_ref"><c>server_ref()</c></seetype>.
        </p>
        <p>
          <c><anno>Request</anno></c> is any term that is passed as
          the first argument to <c>Module:handle_cast/2</c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="check_response" arity="2" since="OTP 23.0"/>
      <fsummary>Check if a message is a response from a server.</fsummary>
      <desc>
	<p>
	  Check if <c><anno>Msg</anno></c> is a response corresponding
          to the request identifier <c><anno>ReqId</anno></c>. The request
          must have been made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>,
	  and it must have been made by the same process calling
          this function.
	</p>
        <p>
          If <c><anno>Msg</anno></c> is a response corresponding to
          <c><anno>ReqId</anno></c> the response is returned; otherwise,
          <c>no_reply</c> is returned and no cleanup is done, and
	  thus the function must be invoked repeatedly until a response
	  is returned.
        </p>
	<p>
	  The return value <c><anno>Reply</anno></c> is passed from the
          return value of <c>Module:handle_call/3</c>.
	</p>
	<p>
	  The function returns an error if the <c>gen_server</c>
	  died before a reply was sent.
	</p>
      </desc>
    </func>
    
    <func>
      <name name="check_response" arity="3" since="OTP 25.0"/>
      <fsummary>Check if a message is a response from a server.</fsummary>
      <desc>
	<p>
	  Check if <c><anno>Msg</anno></c> is a response corresponding
          to a request identifier saved in <c><anno>ReqIdCollection</anno></c>.
          All request identifiers of <c><anno>ReqIdCollection</anno></c>
          must correspond to requests that have been made using
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> or
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>,
          and all request must have been made by the process calling this
          function.
	</p>
        <p>
          The <c><anno>Label</anno></c> in the response equals the
          <c><anno>Label</anno></c> associated with the request identifier
          that the response corresponds to. The <c><anno>Label</anno></c>
          of a request identifier is associated when
          <seemfa marker="#reqids_add/3">saving the request id</seemfa>
          in a request identifier collection, or when sending the request using
          <seemfa marker="#send_request/4"><c>send_request/4</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>NewReqIdCollection</anno></c> is a possibly  modified
          request identifier collection.
        </p>
        <p>
          If <c><anno>ReqIdCollection</anno></c> is empty, the atom
          <c>no_request</c> will be returned. If <c><anno>Msg</anno></c>
          does not correspond to any of the request identifiers in
          <c><anno>ReqIdCollection</anno></c>, the atom
          <c>no_reply</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>ReqIdCollection</anno></c> in the resulting
          <c><anno>NewReqIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewReqIdCollection</anno></c> will equal
          <c><anno>ReqIdCollection</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_reply</c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="enter_loop" arity="3" since=""/>
      <name name="enter_loop" arity="4" clause_i="1" since=""/>
      <name name="enter_loop" arity="4" clause_i="2" since=""/>
      <name name="enter_loop" arity="4" clause_i="3" since=""/>
      <name name="enter_loop" arity="4" clause_i="4" since=""/>
      <name name="enter_loop" arity="5" clause_i="1" since=""/>
      <name name="enter_loop" arity="5" clause_i="2" since=""/>
      <name name="enter_loop" arity="5" clause_i="3" since=""/>
      <fsummary>Enter the <c>gen_server</c> receive loop.</fsummary>
      <desc>
        <p>
          Makes an existing process a <c>gen_server</c> process.
          Does not return, instead the calling process enters
          the <c>gen_server</c> process receive loop
          and becomes a <c>gen_server</c> process.
          The process <em>must</em> have been started using
          one of the start functions in
          <seeerl marker="proc_lib"><c>proc_lib(3)</c></seeerl>.
          The user is responsible for any initialization of the process,
          including registering a name for it.
        </p>
        <p>
          This function is useful when a more complex
          initialization procedure is needed
          than the <c>gen_server</c> process behavior provides.
        </p>
        <p>
          <c><anno>Module</anno></c>, <c><anno>Options</anno></c>,
          and <c><anno>ServerName</anno></c> have
          the same meanings as when calling
          <seemfa marker="#start_link/3">
            <c>start[_link|_monitor]/3,4</c>
          </seemfa>
          or it can be <c>self()</c> for an anonymous server,
          which is the same as calling an <c>enter_loop/3,4</c> function
          without a <c><anno>ServerName</anno></c> argument.
          However, if <c><anno>ServerName</anno></c> is specified
          (and not as <c>self()</c>),
          the process must have been registered accordingly
          <em>before</em> this function is called.
        </p>
        <p>
          <c><anno>State</anno></c>, <c><anno>Timeout</anno></c>,
          <c><anno>Hibernate</anno></c> and <c><anno>Cont</anno></c> have the same meanings as in
          the return value of
          <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>,
          which is <em>not</em> called when <c>enter_loop/3,4,5</c> is used.
          Note that to adhere to the
          <seeguide marker="system/design_principles:gen_server_concepts">
            gen_server Behaviour
          </seeguide>
          such a callback function needs to be defined,
          and it might as well be the one used when starting
          the <c>gen_server</c> process through <c>proc_lib</c>,
          and then be the one that calls <c>enter_loop/3,4,5</c>.
          But if such a <c>Module:init/1</c> function
          in for example error cases cannot call
          <c>enter_loop/3,4,5</c>, it should return a value
          that follows the type specification for
          <c>Module:init/1</c> such as <c>ignore</c>,
          although that value will be lost
          when returning to the spawning function.
        </p>
        <p>
          This function fails if the calling process was not started by a
          <c>proc_lib</c> start function, or if it is not registered
          according to <c><anno>ServerName</anno></c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="multi_call" arity="2" since=""/>
      <name name="multi_call" arity="3" since=""/>
      <name name="multi_call" arity="4" since=""/>
      <fsummary>Make a synchronous call to many generic servers.</fsummary>
      <desc>
        <p>
          Makes a synchronous call to all <c>gen_server</c> processes
          locally registered as <c><anno>Name</anno></c>
          at the specified nodes,
          by first sending the request to the nodes,
          and then waiting for the replies.
          The <c>gen_server</c> processes on the nodes call
          <seemfa marker="#Module:handle_call/3">
            <c>Module:handle_call/3</c>
          </seemfa>
          to handle the request.
        </p>
        <p>
          The function returns a tuple
          <c>{<anno>Replies</anno>,<anno>BadNodes</anno>}</c>,
          where <c><anno>Replies</anno></c> is a list of
          <c>{<anno>Node</anno>,<anno>Reply</anno>}</c> tuples,
          and <c><anno>BadNodes</anno></c> is a list of nodes
          that either did not exist,
          where <c><anno>Name</anno></c>
          was not a registered <c>gen_server</c>,
          or where it did not reply.
        </p>
        <p>
          <c><anno>Nodes</anno></c> is a list of node names
          to which the request is to be sent.
          Default value is the list of all known nodes
          <c>[node()|nodes()]</c>.
        </p>
        <p>
          <c><anno>Name</anno></c> is the locally registered name
          for each <c>gen_server</c> process.
        </p>
        <p>
          <c><anno>Request</anno></c> is any term that is passed
          as the first argument to <c>Module:handle_call/3</c>.
        </p>
        <p>
          <c><anno>Timeout</anno></c> is an integer that
          specifies how many milliseconds to wait for all replies,
          or the atom <c>infinity</c> to wait indefinitely,
          which is the default.
          If no reply is received from a node within the specified time,
          the node is added to <c><anno>BadNodes</anno></c>.
        </p>
        <p>
          When a reply <c><anno>Reply</anno></c> is received
          from the <c>gen_server</c> process
          at a node <c><anno>Node</anno></c>,
          <c>{<anno>Node</anno>,<anno>Reply</anno>}</c> is added to
          <c><anno>Replies</anno></c>.
          <c><anno>Reply</anno></c> is passed from the return value of
          <c>Module:handle_call/3</c>.
        </p>
        <warning>
          <p>
            If one of the nodes cannot process monitors, for example,
            C or Java nodes, and the <c>gen_server</c> process is not started
            when the requests are sent, but starts within 2 seconds,
            this function waits the whole <c>Timeout</c>,
            which may be infinity.
          </p>
          <p>This problem does not exist if all nodes are Erlang nodes.</p>
        </warning>
        <p>
          To prevent late answers (after the time-out) from polluting
          the message queue of the caller, a middleman process is used
          to do the calls. Late answers are then discarded
          when they arrive to a terminated process.
        </p>
      </desc>
    </func>

    <func>
      <name name="receive_response" arity="2" since="OTP 24.0"/>
      <fsummary>Receive a response from a server.</fsummary>
      <desc>
	<p>
	  Receive a response corresponding to the request identifier
          <c><anno>ReqId</anno></c>. The request must have been made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>,
	  and it must have been made by the same process calling
          this function.
	</p>
	<p>
	  <c><anno>Timeout</anno></c> specifies how long to wait for
          a response. If no response is received within the specified time,
          the function returns <c>timeout</c>. Assuming that the
	  server executes on a node supporting aliases (introduced in
	  OTP 24) the request will also be abandoned. That is, no
          response will be received after a timeout. Otherwise, a
          stray response might be received at a later time.
	</p>
	<p>
	  The return value <c><anno>Reply</anno></c> is passed from the
          return value of <c>Module:handle_call/3</c>.
	</p>
	<p>
	  The function returns an error if the <c>gen_server</c>
	  died before a reply was sent.
	</p>
	<p>
	  The difference between <c>receive_response/2</c> and
          <seemfa marker="#wait_response/2"><c>wait_response/2</c></seemfa>
	  is that <c>receive_response/2</c> abandons the request at
          timeout so that a potential future response is ignored, while
          <c>wait_response/2</c> does not.
	</p>
      </desc>
    </func>

    <func>
      <name name="receive_response" arity="3" since="OTP 25.0"/>
      <fsummary>Receive a response from a server.</fsummary>
      <desc>
	<p>
	  Receive a response corresponding to a request identifier saved
          in <c><anno>ReqIdCollection</anno></c>. All request identifiers
          of <c><anno>ReqIdCollection</anno></c> must correspond to requests
          that have been made using
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> or
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>,
          and all request must have been made by the process calling this
          function.
	</p>
        <p>
          The <c><anno>Label</anno></c> in the response equals the
          <c><anno>Label</anno></c> associated with the request identifier
          that the response corresponds to. The <c><anno>Label</anno></c>
          of a request identifier is associated when
          <seemfa marker="#reqids_add/3">adding the request id</seemfa>
          in a request identifier collection, or when sending the request using
          <seemfa marker="#send_request/4"><c>send_request/4</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
          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>NewReqIdCollection</anno></c> is a possibly modified
          request identifier collection.
        </p>
        <p>
          If <c><anno>ReqIdCollection</anno></c> is empty, the atom
          <c>no_request</c> will be returned.
        </p>
	<p>
	  <c><anno>Timeout</anno></c> specifies how long to wait for
          a response. If no response is received within the specified time,
          the function returns <c>timeout</c>. Assuming that the
	  server executes on a node supporting aliases (introduced in
	  OTP 24) all requests identified by <c><anno>ReqIdCollection</anno></c>
          will also be abandoned. That is, no responses will be received
          after a timeout. Otherwise, stray responses might be received
          at a later time.
	</p>
	<p>
	  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 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>ReqIdCollection</anno></c> in the resulting
          <c><anno>NewReqIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewReqIdCollection</anno></c> will equal
          <c><anno>ReqIdCollection</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>
      </desc>
    </func>
    
    <func>
      <name name="reply" arity="2" since=""/>
      <fsummary>Send a reply to a client.</fsummary>
      <desc>
        <p>
          This function can be used by a <c>gen_server</c> process to
          explicitly send a reply to a client that called
          <seemfa marker="#call/2"><c>call/2,3</c></seemfa> or
          <seemfa marker="#multi_call/2"><c>multi_call/2,3,4</c></seemfa>,
          when the reply cannot be passed in the return value of
          <seemfa marker="#Module:handle_call/3">
            <c>Module:handle_call/3</c></seemfa>.
        </p>
        <p>
          <c><anno>Client</anno></c> must be the <c>From</c> argument
          provided to the <c>handle_call</c> callback function.
          <c><anno>Reply</anno></c> is any term
          passed back to the client as the return value of
          <c>call/2,3</c> or <c>multi_call/2,3,4</c>.
        </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>ReqId</anno></c> and associates a <c><anno>Label</anno></c>
          with the request identifier by adding this information to
          <c><anno>ReqIdCollection</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/2"><c>send_request/2</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="#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>
          <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>ReqIdCollection</anno></c>.
        </p>
      </desc>
    </func>

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

    <func>
      <name name="send_request" arity="2" since="OTP 23.0"/>
      <fsummary>Sends a request to a generic server.</fsummary>
      <desc>
        <p>
	  Sends an asynchronous <c>call</c> request <c><anno>Request</anno></c>
          to the <c>gen_server</c> process identified by <c><anno>ServerRef</anno></c>
          and returns a request identifier <c><anno>ReqId</anno></c>. The return
          value <c><anno>ReqId</anno></c> shall later be used with
          <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>
	  to fetch the actual result of the request. Besides passing
          the request identifier directly to these functions, it can also 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="#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/4"><c>send_request/4</c></seemfa>
          instead.
	</p>
	<p>
          The call <c>gen_server:receive_response(gen_server:send_request(<anno>ServerRef</anno>,
          <anno>Request</anno>), Timeout)</c> can be seen as equivalent to
	  <seemfa marker="#call/3"><c>gen_server:call(<anno>ServerRef</anno>, <anno>Request</anno>,
          Timeout)</c></seemfa>, ignoring the error handling.
	</p>
	<p>
	  The <c>gen_server</c> process calls
	  <seemfa marker="#Module:handle_call/3">
            <c>Module:handle_call/3</c>
          </seemfa>
	  to handle the request.
	</p>
        <p>
          See the type
          <seetype marker="#server_ref"><c>server_ref()</c></seetype>
          for the possible values for <c><anno>ServerRef</anno></c>.
        </p>
        <p>
          <c><anno>Request</anno></c> is any term that is passed
          as the first argument to <c>Module:handle_call/3</c>.
        </p>
      </desc>
    </func>

    <func>
      <name name="send_request" arity="4" since="OTP 25.0"/>
      <fsummary>Sends a request to a generic server.</fsummary>
      <desc>
	<p>
          Sends an asynchronous <c>call</c> request <c><anno>Request</anno></c>
          to the <c>gen_server</c> process identified by <c><anno>ServerRef</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>NewReqIdCollection</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>gen_server:reqids_add</c></seemfa>(<seemfa
          marker="#send_request/2"><c>gen_server:send_request</c></seemfa><c>(<anno>ServerRef</anno>,
          <anno>Request</anno>), <anno>Label</anno>,
          <anno>ReqIdCollection</anno>)</c>, but calling <c>send_request/4</c>
          is slightly more efficient.
        </p>
      </desc>
    </func>

    <func>
      <name name="start" arity="3" since=""/>
      <name name="start" arity="4" since=""/>
      <fsummary>Create a standalone <c>gen_server</c> process.</fsummary>
      <desc>
        <p>
          Creates a standalone <c>gen_server</c> process, that is, a
          <c>gen_server</c> process that is not part of a supervision tree
          and thus has no supervisor.</p>
          <p>
            Other than that see
            <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
          </p>
      </desc>
    </func>

    <func>
      <name name="start_link" arity="3" since=""/>
      <name name="start_link" arity="4" since=""/>
      <fsummary>
        Create a <c>gen_server</c> process in a supervision tree.
      </fsummary>
      <desc>
        <p>
          Creates a <c>gen_server</c> process as part of a supervision tree.
          This function is to be called, directly or indirectly, by
          the supervisor. For example, it ensures that
          the <c>gen_server</c> process is linked to the supervisor.
        </p>
        <p>
          The <c>gen_server</c> process calls
          <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
          to initialize.
          To ensure a synchronized startup procedure,
          <c>start_link/3,4</c> does not return until
          <c>Module:init/1</c> has returned.
        </p>
        <p>
          Using the argument <c><anno>ServerName</anno></c>
          creates a <c>gen_server</c> with a registered name.
          See type
          <seetype marker="#server_name"><c>server_name()</c></seetype>
          for different name registrations.
          If no <c><anno>ServerName</anno></c> is provided,
          the <c>gen_server</c> process is not registered.
        </p>
        <p>
          <c><anno>Module</anno></c> is the name of the callback module.
        </p>
        <p>
          <c><anno>Args</anno></c> is any term that is passed as
          the argument to
          <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>.
        </p>
        <p>
          See type
          <seetype marker="#start_opt"><c>start_opt()</c></seetype>
          for <c><anno>Options</anno></c> when starting
          the <c>gen_server</c> process.
        </p>
        <p>
          See type
          <seetype marker="#start_ret"><c>start_ret()</c></seetype>
          for a description this function's return values.
        </p>
      </desc>
    </func>

    <func>
      <name name="start_monitor" arity="3" since="OTP 23.0"/>
      <name name="start_monitor" arity="4" since="OTP 23.0"/>
      <fsummary>Create a standalone <c>gen_server</c> process.</fsummary>
      <desc>
        <p>
          Creates a standalone <c>gen_server</c> process, that is, a
          <c>gen_server</c> process that is not part of a supervision tree
          (and thus has no supervisor) and atomically sets up a monitor to
	  the newly created server.
        </p>
        <p>
          Other than that see
          <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.
	  Note that the return value for a successful start differs
          in that it returns a monitor <c>reference</c>.
          See type
          <seetype marker="#start_mon_ret"><c>start_mon_ret()</c></seetype>.
        </p>
        <p>
          If the start is not successful,
	  the caller will be blocked until the monitor's
          <c>'DOWN'</c> message has been received
          and removed from the message queue.
        </p>
      </desc>
    </func>

    <func>
      <name name="stop" arity="1"  since="OTP 18.0"/>
      <name name="stop" arity="3"  since="OTP 18.0"/>
      <fsummary>Synchronously stop a generic server.</fsummary>
      <desc>
        <p>
          Orders the generic server specified by
          <c><anno>ServerRef</anno></c> to exit
          with the specified <c><anno>Reason</anno></c>,
          default 'normal', and waits for it to terminate.
          The <c>gen_server</c> process calls
          <seemfa marker="#Module:terminate/2">
            <c>Module:terminate/2</c>
          </seemfa>
          before exiting.
        </p>
        <p>
          The function returns <c>ok</c> if the server terminates
          with the expected reason. Any other reason than <c>normal</c>,
          <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an
          error report to be issued using
          <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>.
          An exit signal with the same reason
          is sent to linked processes and ports.
        </p>
        <p>
          <c><anno>Timeout</anno></c> is an integer that
          specifies how many milliseconds to wait for the server to
          terminate, or the atom <c>infinity</c> to wait
          indefinitely, which is the default.  If the
          server has not terminated within the specified time,
          the call exits the calling process
          with reason <c>timeout</c>.
        </p>
        <p>
          If the process does not exist, the call exits
          the calling process with reason <c>noproc</c>,
          and with reason <c>{nodedown,Node}</c>
          if the connection fails to the remote <c>Node</c>
          where the server runs.
        </p>
      </desc>
    </func>

    <func>
      <name name="wait_response" arity="2" since="OTP 23.0"/>
      <fsummary>Wait or poll for a response from a server.</fsummary>
      <desc>
	<p>
	  Wait for a response corresponding to the request identifier
          <c><anno>ReqId</anno></c>. The request must have been made by
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>,
	  and it must have been made by the same process calling
          this function.
	</p>
	<p>
	  <c><anno>WaitTime</anno></c> specifies how long to wait for
          a reply. If no reply is received within the specified
	  time, the function returns <c>timeout</c> and no cleanup is
	  done, and thus the function can be invoked repeatedly until a
	  reply is returned.
	</p>
	<p>
	  The return value <c><anno>Reply</anno></c> is passed from the
          return value of <c>Module:handle_call/3</c>.
	</p>
	<p>
	  The function returns an error if the <c>gen_server</c>
	  died before a reply was sent.
	</p>
	<p>
	  The difference between
	  <seemfa marker="#receive_response/2"><c>receive_response/2</c></seemfa>
	  and <c>wait_response/2</c> is that <c>receive_response/2</c>
	  abandons the request at time-out so that a potential future
	  response is ignored, while <c>wait_response/2</c> does not.
	</p>
      </desc>
    </func>
    
    <func>
      <name name="wait_response" arity="3" since="OTP 25.0"/>
      <fsummary>Wait or poll for a response from a server.</fsummary>
      <desc>
	<p>
	  Wait for a response corresponding to a request identifier saved
          in <c><anno>ReqIdCollection</anno></c>. All request identifiers
          of <c><anno>ReqIdCollection</anno></c> must correspond to requests
          that have been made using
	  <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> or
          <seemfa marker="#send_request/4"><c>send_request/4</c></seemfa>,
          and all request must have been made by the process calling this
          function.
	</p>
        <p>
          The <c><anno>Label</anno></c> in the response equals the
          <c><anno>Label</anno></c> associated with the request identifier
          that the response corresponds to. The <c><anno>Label</anno></c>
          of a request identifier is associated when
          <seemfa marker="#reqids_add/3">saving the request id</seemfa> in
          a request identifier collection, or when sending the request using
          <seemfa marker="#send_request/4"><c>send_request/4</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>NewReqIdCollection</anno></c> is a possibly  modified
          request identifier collection.
        </p>
        <p>
          If <c><anno>ReqIdCollection</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>timeout</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>.
        </p>
	<p>
	  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 a 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>ReqIdCollection</anno></c> in the resulting
          <c><anno>NewReqIdCollection</anno></c>. If
          <c><anno>Delete</anno></c> equals <c>false</c>,
          <c><anno>NewReqIdCollection</anno></c> will equal
          <c><anno>ReqIdCollection</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_reply</c>.
        </p>
      </desc>
    </func>
  </funcs>

 

  <funcs>
    <fsdescription>
      <title>Callback Functions</title>
      <p>The following functions
        are to be exported from a <c>gen_server</c> callback module.</p>
    </fsdescription>
    <func>
      <name since="">Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}</name>
      <fsummary>Update the internal state during upgrade/downgrade.</fsummary>
      <type>
        <v>OldVsn = Vsn | {down, Vsn}</v>
        <v>&nbsp;&nbsp;Vsn = term()</v>
        <v>State = NewState = term()</v>
        <v>Extra = term()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <note>
          <p>This callback is optional, so callback modules need not export it.
            If a release upgrade/downgrade with <c>Change={advanced,Extra}</c>
            specified in the <c>appup</c> file is made when <c>code_change/3</c>
            isn't implemented the process will crash with an <c>undef</c> exit
            reason.</p>
        </note>
        <p>This function is called by a <c>gen_server</c> process when it is
          to update its internal state during a release upgrade/downgrade,
          that is, when the instruction <c>{update,Module,Change,...}</c>,
          where <c>Change={advanced,Extra}</c>, is specifed in
          the <c>appup</c> file. For more information, see section
          <seeguide marker="system/design_principles:release_handling#instr">
          Release Handling Instructions</seeguide> in OTP Design Principles.</p>
        <p>For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
          for a downgrade, <c>OldVsn</c> is
          <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c>
          attribute(s) of the old version of the callback module
          <c>Module</c>. If no such attribute is defined, the version
          is the checksum of the Beam file.</p>
        <p><c>State</c> is the internal state of the <c>gen_server</c>
          process.</p>
        <p><c>Extra</c> is passed "as is" from the <c>{advanced,Extra}</c>
          part of the update instruction.</p>
        <p>If successful, the function must return the updated
          internal state.</p>
        <p>If the function returns <c>{error,Reason}</c>, the ongoing
          upgrade fails and rolls back to the old release.</p>
      </desc>
    </func>

    <func>
      <name since="OTP 25.0">Module:format_status(Status) -> NewStatus</name>
      <fsummary>Optional function for providing a term describing the
        current <c>gen_server</c> status.</fsummary>
      <type>
        <v>Status = <seetype marker="#format_status">format_status()</seetype></v>
        <v>NewStatus = <seetype marker="#format_status">format_status()</seetype></v>
      </type>
      <desc>
        <note>
          <p>This callback is optional, so callback modules need not
            export it. The <c>gen_server</c> module provides a default
            implementation of this function that returns the callback
            module state.</p>
          <p>
	    If this callback is exported but fails, to hide possibly sensitive
            data, the default function will instead return the fact that
	    <c>format_status/1</c> has crashed.</p>
        </note>
        <p>This function is called by a <c>gen_server</c> process in the following situations:</p>
        <list type="bulleted">
          <item>
            <p><seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
              is invoked to get the <c>gen_server</c> status.</p>
          </item>
          <item>
            <p>The <c>gen_server</c> process terminates abnormally and logs an error.</p>
          </item>
        </list>
        <p>
          This callback is used to limit the status of the process
          returned by
          <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa>
          or sent to <seeerl marker="kernel:logger"><c>logger</c></seeerl>.
        </p>
        <p>
          The callback gets a map <c>Status</c>
          describing the current status and shall return a map
          <c>NewStatus</c> with the same keys,
          but it may transform some values.
        </p>
        <p>
          Two possible use cases for this callback is to
          remove sensitive information from the state
          to prevent it from being printed in log files,
          or to compact large irrelevant status items
          that would only clutter the logs.
        </p>
        <p>Example:</p>
        <code type="erl"><![CDATA[
format_status(Status) ->
  maps:map(
    fun(state,State) ->
            maps:remove(private_key, State);
       (message,{password, _Pass}) ->
            {password, removed};
       (_,Value) ->
            Value
    end, Status).
]]></code>
      </desc>
    </func>

    <func>
      <name since="OTP R13B04">Module:format_status(Opt, [PDict, State]) -> Status</name>
      <fsummary>Optional function for providing a term describing the
        current <c>gen_server</c> status.</fsummary>
      <type>
        <v>Opt = normal | terminate</v>
        <v>PDict = [{Key, Value}]</v>
        <v>State = term()</v>
        <v>Status = term()</v>
      </type>
      <desc>
        <warning>
          <p>This callback is deprecated, in new code use <seemfa marker="#Module:format_status/1">
          format_status/1</seemfa>. If a <seemfa marker="#Module:format_status/1">format_status/1</seemfa>
            callback exists, then this function will never be called.</p>
        </warning>
        <note>
          <p>This callback is optional, so callback modules need not
            export it. The <c>gen_server</c> module provides a default
            implementation of this function that returns the callback
            module state.</p>
        </note>
        <p>This function is called by a <c>gen_server</c> process in the
          following situations:</p>
        <list type="bulleted">
          <item>
            <p>One of <seemfa marker="sys#get_status/1">
              <c>sys:get_status/1,2</c></seemfa>
              is invoked to get the <c>gen_server</c> status. <c>Opt</c> is set
              to the atom <c>normal</c>.</p>
          </item>
          <item>
            <p>The <c>gen_server</c> process terminates abnormally and logs an
              error. <c>Opt</c> is set to the atom <c>terminate</c>.</p>
          </item>
        </list>
        <p>This function is useful for changing the form and
          appearance of the <c>gen_server</c> status for these cases. A
          callback module wishing to change
          the <c>sys:get_status/1,2</c> return value, as well as how
          its status appears in termination error logs, exports an
          instance of <c>format_status/2</c> that returns a term
          describing the current status of the <c>gen_server</c> process.</p>
        <p><c>PDict</c> is the current value of the process dictionary of
          the <c>gen_server</c> process..</p>
        <p><c>State</c> is the internal state of the <c>gen_server</c>
          process.</p>
        <p>The function is to return <c>Status</c>, a term that
          changes the details of the current state and status of
          the <c>gen_server</c> process. There are no restrictions on the
          form <c>Status</c> can take, but for
          the <c>sys:get_status/1,2</c> case (when <c>Opt</c>
          is <c>normal</c>), the recommended form for
          the <c>Status</c> value is <c>[{data, [{"State",
          Term}]}]</c>, where <c>Term</c> provides relevant details of
          the <c>gen_server</c> state. Following this recommendation is not
          required, but it makes the callback module status
          consistent with the rest of the <c>sys:get_status/1,2</c>
          return value.</p>
        <p>One use for this function is to return compact alternative
          state representations to avoid that large state terms are
          printed in log files.</p>
      </desc>
    </func>

    <func>
      <name since="">Module:handle_call(Request, From, State) -> Result</name>
      <fsummary>Handle a synchronous request.</fsummary>
      <type>
        <v>Request = term()</v>
        <v>From = <seetype marker="#from">from()</seetype></v>
        <v>State = term()</v>
        <v>Result = {reply,Reply,NewState}</v>
        <v>&nbsp;&nbsp;| {reply,Reply,NewState,Timeout}</v>
        <v>&nbsp;&nbsp;| {reply,Reply,NewState,hibernate}</v>
        <v>&nbsp;&nbsp;| {reply,Reply,NewState,{continue,Continue}}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,Timeout}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
        <v>&nbsp;&nbsp;| {stop,Reason,Reply,NewState}</v>
        <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
        <v>&nbsp;Reply = term()</v>
        <v>&nbsp;NewState = term()</v>
        <v>
          &nbsp;Timeout =
          <seetype marker="erts:erlang#timeout">timeout()</seetype>
        </v>
        <v>&nbsp;Continue = term()</v>
        <v>&nbsp;Reason = term()</v>
      </type>
      <desc>
        <p>Whenever a <c>gen_server</c> process receives a request sent using
          <seemfa marker="#call/2"><c>call/2,3</c></seemfa> or
          <seemfa marker="#multi_call/2"><c>multi_call/2,3,4</c></seemfa>,
          this function is called to handle the request.</p>
        <p><c>State</c> is the internal state of the <c>gen_server</c>
          process, and <c>NewState</c> a possibly updated one.</p>
        <p><c>Request</c> is passed from the same argument provided
        to <c>call</c> or <c>multi_call</c>.</p>
        <p>The return value <c>Result</c> is interpreted as follows:</p>
        <taglist>
          <tag>
            <c>{reply,Reply,NewState}</c><br/>
            <c>{reply,Reply,NewState,_}</c>
          </tag>
          <item>
            <p>
              The <c>Reply</c> value is sent back to the client request
              and there becomes its return value.
            </p>
            <p>
              The <c>gen_server</c> process continues executing
              with the possibly updated internal state <c>NewState</c>.
            </p>
          </item>
          <tag>
            <c>{noreply,NewState}</c><br/>
            <c>{noreply,NewState,_}</c>
          </tag>
          <item>
            <p>
              The <c>gen_server</c> process continues executing
              with the possibly updated internal state <c>NewState</c>.
            </p>
            <p>
              A reply to the client request has to be created by calling
              <seemfa marker="#reply/2"><c>reply(From,&nbsp;Reply)</c></seemfa>,
              either in this or in a later callback.
            </p>
          </item>
          <tag>
            <c>{reply,_,_,Timeout}</c><br/>
            <c>{noreply,_,Timeout}</c>
          </tag>
          <item>
            <p>
              If an integer <c>Timeout</c> is provided, a time-out occurs
              unless a request or a message is received within
              that many milliseconds. A time-out is represented by
              the atom <c>timeout</c> to be handled by the
              <seemfa marker="#Module:handle_info/2">
                <c>Module:handle_info/2</c>
              </seemfa>
              callback function.
              <c>Timeout&nbsp;=:=&nbsp;infinity</c>
              can be used to wait indefinitely, which is the same as
              returning a value without a <c>Timeout</c> member.
            </p>
          </item>
          <tag>
            <c>{reply,_,_,hibernate}</c><br/>
            <c>{noreply,_,hibernate}</c>
          </tag>
          <item>
            <p>
              The process goes into hibernation waiting for
              the next message to arrive (by calling
              <seemfa marker="proc_lib#hibernate/3">
                <c>proc_lib:hibernate/3</c></seemfa>).
            </p>
          </item>
          <tag>
            <c>{reply,_,_,{continue,Continue}}</c><br/>
            <c>{noreply,_,{continue,Continue}}</c>
          </tag>
          <item>
            <p>
              The process will execute the
              <seemfa marker="#Module:handle_continue/2">
                <c>Module:handle_continue/2</c>
              </seemfa>
              callback function, with <c>Continue</c> as the first argument.
            </p>
          </item>
          <tag>
            <c>{stop,Reason,NewState}</c><br/>
            <c>{stop,Reason,Reply,NewState}</c>
          </tag>
          <item>
            <p>
              The <c>gen_server</c> process will call
              <seemfa marker="#Module:terminate/2">
                <c>Module:terminate(Reason,NewState)</c>
              </seemfa>
              and then terminate.
            </p>
            <p>
              <c>{stop,_,Reply,_}</c> will create
              a reply to the client request just as
              <c>{reply,Reply,...}</c> while
              <c>{stop,_,_}</c> will not,
              so just as for <c>{noreply,NewState,...}</c>
              a reply has to be created by calling
              <c>reply(From,&nbsp;Reply)</c>
              before returning <c>{stop,_,_}</c>.
            </p>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name since="">Module:handle_cast(Request, State) -> Result</name>
      <fsummary>Handle an asynchronous request.</fsummary>
      <type>
        <v>Request = term()</v>
        <v>State = term()</v>
        <v>Result = {noreply,NewState}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,Timeout}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
        <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
        <v>&nbsp;NewState = term()</v>
        <v>
          &nbsp;Timeout =
          <seetype marker="erts:erlang#timeout">timeout()</seetype>
        </v>
        <v>&nbsp;Continue = term()</v>
        <v>&nbsp;Reason = term()</v>
      </type>
      <desc>
        <p>Whenever a <c>gen_server</c> process receives a request sent using
          <seemfa marker="#cast/2"><c>cast/2</c></seemfa> or
          <seemfa marker="#abcast/2"><c>abcast/2,3</c></seemfa>,
          this function is called to handle the request.</p>
        <p>For a description of the arguments and possible return values, see
          <seemfa marker="#Module:handle_call/3">
          <c>Module:handle_call/3</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name since="OTP 21.0">Module:handle_continue(Continue, State) -> Result</name>
      <fsummary>Handle a continue instruction.</fsummary>
      <type>
        <v>Continue = term()</v>
        <v>State = term()</v>
        <v>Result = {noreply,NewState}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,Timeout}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
        <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
        <v>&nbsp;NewState = term()</v>
        <v>
          &nbsp;Timeout =
          <seetype marker="erts:erlang#timeout">timeout()</seetype>
        </v>
        <v>&nbsp;Continue = term()</v>
        <v>&nbsp;Reason = normal | term()</v>
      </type>
      <desc>
        <note>
          <p>This callback is optional, so callback modules need to
            export it only if they return one of the tuples containing
            <c>{continue,Continue}</c>
            from another callback. If such a <c>{continue,_}</c> tuple
            is used and the callback is not implemented,
            the process will exit with <c>undef</c> error.</p>
        </note>
        <p>This function is called by a <c>gen_server</c> process
          whenever a previous callback returns
          one of the tuples containing <c>{continue, Continue}</c>.
          <c>handle_continue/2</c> is invoked immediately after the previous
          callback, which makes it useful for performing work after
          initialization or for splitting the work in a callback in
          multiple steps, updating the process state along the way.</p>
        <p>For a description of the other arguments and possible return values,
          see <seemfa marker="#Module:handle_call/3">
          <c>Module:handle_call/3</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name since="">Module:handle_info(Info, State) -> Result</name>
      <fsummary>Handle an incoming message.</fsummary>
      <type>
        <v>Info = timeout | term()</v>
        <v>State = term()</v>
        <v>Result = {noreply,NewState}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,Timeout}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
        <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
        <v>&nbsp;NewState = term()</v>
        <v>
          &nbsp;Timeout =
          <seetype marker="erts:erlang#timeout">timeout()</seetype>
        </v>
        <v>&nbsp;Reason = normal | term()</v>
      </type>
      <desc>
        <note>
          <p>This callback is optional, so callback modules need not
            export it. The <c>gen_server</c> module provides a default
            implementation of this function that logs about the unexpected
            <c>Info</c> message, drops it and returns <c>{noreply, State}</c>.</p>
        </note>
        <p>This function is called by a <c>gen_server</c> process when a
          time-out occurs or when it receives any other message than a
          synchronous or asynchronous request (or a system message).</p>
        <p><c>Info</c> is either the atom <c>timeout</c>, if a time-out
          has occurred, or the received message.</p>
        <p>For a description of the other arguments and possible return values,
          see <seemfa marker="#Module:handle_call/3">
          <c>Module:handle_call/3</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name since="">Module:init(Args) -> Result</name>
      <fsummary>Initialize process and internal state.</fsummary>
      <type>
        <v>Args = term()</v>
        <v>Result = {ok,State}</v>
        <v>&nbsp;&nbsp;| {ok,State,Timeout}</v>
        <v>&nbsp;&nbsp;| {ok,State,hibernate}</v>
        <v>&nbsp;&nbsp;| {ok,State,{continue,Continue}}</v>
        <v>&nbsp;&nbsp;| {stop,Reason}</v>
        <v>&nbsp;&nbsp;| ignore</v>
        <v>&nbsp;State = term()</v>
        <v>
          &nbsp;Timeout =
          <seetype marker="erts:erlang#timeout">timeout()</seetype>
        </v>
        <v>&nbsp;Reason = term()</v>
      </type>
      <desc>
        <p>Whenever a <c>gen_server</c> process is started using
          <seemfa marker="#start/3"><c>start/3,4</c></seemfa>,
          <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>,
          or <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>,
          this function is called by the new process to initialize.</p>
        <p><c>Args</c> is the <c>Args</c> argument provided to the start
          function.</p>
        <p>The return value <c>Result</c> is interpreted as follows:</p>
        <taglist>
          <tag>
            <c>{ok,State}</c><br/>
            <c>{ok,State,_}</c>
          </tag>
          <item>
            <p>
              Initialization was succesful and <c>State</c>
              is the internal state of the <c>gen_server</c> process.
            </p>
          </item>
          <tag>
            <c>{ok,_,Timeout}</c><br/>
            <c>{ok,_,hibernate}</c><br/>
            <c>{ok,_,{continue,Continue}}</c>
          </tag>
          <item>
            <p>
              See the corresponding return values from
              <seemfa marker="#Module:handle_call/3">
                <c>Module:handle_call/3</c>
              </seemfa>
              for a description of this tuple member.
            </p>
          </item>
          <tag>
            <c>{stop,Reason}</c><br/>
            <c>ignore</c>
          </tag>
          <item>
            <p>
              Initialization failed.
              An exit signal with this <c>Reason</c>
              (or with reason <c>normal</c> if <c>ignore</c> is returned)
              is sent to linked processes and ports,
              notably to the process starting the gen_server when
              <seemfa marker="#start_link/3">
                <c>start_link/3,4</c>
              </seemfa>
              is used.
            </p>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name since="">Module:terminate(Reason, State)</name>
      <fsummary>Clean up before termination.</fsummary>
      <type>
        <v>Reason = normal | shutdown | {shutdown,term()} | term()</v>
        <v>State = term()</v>
      </type>
      <desc>
        <note>
          <p>This callback is optional, so callback modules need not
            export it. The <c>gen_server</c> module provides a default
            implementation without cleanup.</p>
        </note>
        <p>This function is called by a <c>gen_server</c> process when it is
          about to terminate. It is to be the opposite of
          <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>
          and do any necessary cleaning up. When it returns,
          the <c>gen_server</c> process terminates with <c>Reason</c>.
          The return value is ignored.</p>
        <p><c>Reason</c> is a term denoting the stop reason and <c>State</c>
          is the internal state of the <c>gen_server</c> process.</p>
        <p><c>Reason</c> depends on why the <c>gen_server</c> process is
          terminating. If it is because another callback function has returned
          a stop tuple <c>{stop,..}</c>, <c>Reason</c> has
          the value specified in that tuple. If it is because of a failure,
          <c>Reason</c> is the error reason.</p>
        <p>If the <c>gen_server</c> process is part of a supervision tree and
          is ordered by its supervisor to terminate, this function is
          called with <c>Reason=shutdown</c> if the following
          conditions apply:</p>
        <list type="bulleted">
          <item>
            <p>The <c>gen_server</c> process has been set to trap exit
              signals.</p>
          </item>
          <item>
            <p>The shutdown strategy as defined in the child specification
              of the supervisor is an integer time-out value, not
              <c>brutal_kill</c>.</p>
           </item>
        </list>
        <p>Even if the <c>gen_server</c> process is <em>not</em> part of a
          supervision tree, this function is called if it receives an
          <c>'EXIT'</c> message from its parent. <c>Reason</c> is the same
          as in the <c>'EXIT'</c> message.</p>
        <p>Otherwise, the <c>gen_server</c> process terminates immediately.</p>
        <p>
          Notice that for any other reason than <c>normal</c>,
          <c>shutdown</c>, or <c>{shutdown,Term}</c>, see
          <seemfa marker="#stop/3"><c>stop/3</c></seemfa>,
          the <c>gen_server</c> process is assumed to terminate
          because of an error, and an error report is issued using
          <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>.
        </p>
        <p>When the gen_server process exits, an exit signal with the same
          reason is sent to linked processes and ports.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p><seeerl marker="gen_event"><c>gen_event(3)</c></seeerl>,
      <seeerl marker="gen_statem"><c>gen_statem(3)</c></seeerl>,
      <seeerl marker="proc_lib"><c>proc_lib(3)</c></seeerl>,
      <seeerl marker="supervisor"><c>supervisor(3)</c></seeerl>,
      <seeerl marker="sys"><c>sys(3)</c></seeerl></p>
  </section>
</erlref>