path: root/lib/stdlib/doc/src/proc_lib.xml

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

<erlref>
  <header>
    <copyright>
      <year>1996</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>proc_lib</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module since="">proc_lib</module>
  <modulesummary>Functions for asynchronous and synchronous start of processes
    adhering to the OTP design principles.</modulesummary>
  <description>
    <p>This module is used to start processes adhering to
      the <seeguide marker="system/design_principles:des_princ">
      OTP Design Principles</seeguide>. Specifically, the functions in this
      module are used by the OTP standard behaviors (for example,
      <c>gen_server</c> and <c>gen_statem</c>)
      when starting new processes. The functions
      can also be used to start <em>special processes</em>, user-defined
      processes that comply to the OTP design principles. For an example,
      see section <seeguide marker="system/design_principles:spec_proc">
      sys and proc_lib</seeguide> in OTP Design Principles.</p>


    <p>Some useful information is initialized when a process starts.
      The registered names, or the process identifiers, of the parent
      process, and the parent ancestors, are stored together with
      information about the function initially called in the process.</p>

    <p>While in "plain Erlang", a process is said to terminate normally
      only for exit reason <c>normal</c>, a process started
      using <c>proc_lib</c> is also said to terminate normally if it
      exits with reason <c>shutdown</c> or <c>{shutdown,Term}</c>.
      <c>shutdown</c> is the reason used when
      an application (supervision tree) is stopped.</p>

    <p>When a process that is started using <c>proc_lib</c> terminates
      abnormally (that is, with another exit reason than <c>normal</c>,
      <c>shutdown</c>, or <c>{shutdown,Term}</c>), a <em>crash report</em>
      is generated, which is written to terminal by the default logger
      handler setup by Kernel. For more information about how crash reports
      were logged prior to Erlang/OTP 21.0, see
      <seeguide marker="sasl:error_logging">SASL Error Logging</seeguide>
      in the SASL User's Guide.</p>

    <p>Unlike in "plain Erlang", <c>proc_lib</c> processes will not generate
      <em>error reports</em>, which are written to the terminal by the
      emulator. All exceptions are
      converted to <em>exits</em> which are ignored by the default
      <c>logger</c> handler.</p>

    <p>The crash report contains the previously stored information, such
      as ancestors and initial function, the termination reason, and
      information about other processes that terminate as a result
      of this process terminating.</p>
  </description>

  <datatypes>
    <datatype>
      <name name="spawn_option"/>
      <desc>
        <p>See <seemfa marker="erts:erlang#spawn_opt/4">
          <c>erlang:spawn_opt/2,3,4,5</c></seemfa>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="start_spawn_option"/>
      <desc>
        <p>A restricted set of <seetype marker="#spawn_option">spawn
	options</seetype>. Most notably <c>monitor</c> is <em>not</em> part
	of these options.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="dict_or_pid"/>
    </datatype>
  </datatypes>

  <funcs>
    <func>
      <name name="format" arity="1" since=""/>
      <fsummary>Format a crash report.</fsummary>
      <desc>
        <p>Equivalent to <seemfa marker="#format/2">
          <c>format(<anno>CrashReport</anno>, latin1)</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="format" arity="2" since="OTP R16B"/>
      <fsummary>Format a crash report.</fsummary>
      <desc>
	<note>
	  <p>This function is deprecated in the sense that
	    the <c>error_logger</c> is no longer the preferred
	    interface for logging in Erlang/OTP. A
	    new <seeguide marker="kernel:logger_chapter">logging
	    API</seeguide> was added in Erlang/OTP 21.0, but
	    legacy <c>error_logger</c> handlers can still be used. New
	    Logger handlers do not need to use this function, since
	    the formatting callback (<c>report_cb</c>) is included as
	    metadata in the log event.</p>
	</note>
        <p>This function can be used by a user-defined legacy
	  <c>error_logger</c> event handler to
          format a crash report. The crash report is sent using
          <seeerl marker="kernel:logger">
          <c>logger(3)</c></seeerl>, and the event to be handled is of the format
          <c>{error_report, GL, {Pid, crash_report,
          <anno>CrashReport</anno>}}</c>,
          where <c>GL</c> is the group leader pid of process
          <c>Pid</c> that sent the crash report.</p>
      </desc>
    </func>

    <func>
      <name name="format" arity="3" since="OTP 18.1"/>
      <fsummary>Format a crash report.</fsummary>
      <desc>
	<note>
	  <p>This function is deprecated in the sense that
	    the <c>error_logger</c> is no longer the preferred
	    interface for logging in Erlang/OTP. A
	    new <seeguide marker="kernel:logger_chapter">logging
	    API</seeguide> was added in Erlang/OTP 21.0, but
	    legacy <c>error_logger</c> handlers can still be used. New
	    Logger handlers do not need to used this function, since
	    the formatting callback (<c>report_cb</c>) is included as
	    metadata in the log event.</p>
	</note>
        <p>This function can be used by a user-defined legacy
	  <c>error_logger</c> event handler to
          format a crash report. When <anno>Depth</anno> is specified as a
          positive integer, it is used in the format string to
          limit the output as follows: <c>io_lib:format("~P",
          [Term,<anno>Depth</anno>])</c>.</p>
      </desc>
    </func>

    <func>
      <name name="hibernate" arity="3" since=""/>
      <fsummary>Hibernate a process until a message is sent to it.</fsummary>
      <desc>
        <p>This function does the same as (and does call) the
          <seemfa marker="erts:erlang#hibernate/3">
          <c>hibernate/3</c></seemfa> BIF,
          but ensures that exception handling and logging continues to
          work as expected when the process wakes up.</p>
        <p>Always use this function instead of the BIF for processes started
          using <c>proc_lib</c> functions.</p>
      </desc>
    </func>

    <func>
      <name name="init_ack" arity="1" since=""/>
      <name name="init_ack" arity="2" since=""/>
      <fsummary>Used by a process when it has started.</fsummary>
      <desc>
        <p>
          This function must only be used by a process
          that has been started by a
          <seemfa marker="#start/3"><c>start[_link|_monitor]/3,4,5</c></seemfa>
          function. It tells <c><anno>Parent</anno></c> that the process has
          initialized itself and started.
        </p>
        <p>Function <c>init_ack/1</c> uses the parent value
          previously stored by the start function used.</p>
        <p>
          If neither this function nor
          <seemfa marker="#init_fail/2"><c>init_fail/2,3</c></seemfa>
          is called by the started process, the start function
          returns an error tuple when the started process exits,
          or when the start function time-out (if used) has passed,
          see <seemfa marker="#start/3"><c>start/3,4,5</c></seemfa>.
        </p>
        <warning>
          <p>
            Do not use this function to return an error indicating
            that the process start failed.  When doing so
            the start function can return before the failing
            process has exited, which may block VM resources
            required for a new start attempt to succeed. Use
            <seemfa marker="#init_fail/2"><c>init_fail/2,3</c></seemfa>
            for that purpose.
          </p>
        </warning>
        <p>The following example illustrates how this function and
          <c>proc_lib:start_link/3</c> are used:</p>
        <code type="none">
-module(my_proc).
-export([start_link/0]).
-export([init/1]).

start_link() ->
    proc_lib:start_link(my_proc, init, [self()]).

init(Parent) ->
    case do_initialization() of
        ok ->
            proc_lib:init_ack(Parent, {ok, self()});
        {error, Reason} ->
            exit(Reason)
    end,
    loop().

...</code>
      </desc>
    </func>

    <func>
      <name since="OTP-26.0">init_fail(Ret, Exception) -> no_return()</name>
      <name since="OTP-26.0">init_fail(Parent, Ret, Exception) -> no_return()</name>
      <fsummary>Used by a process that fails to start.</fsummary>
      <type>
        <v>Parent = <seetype marker="erts:erlang#pid">pid()</seetype></v>
        <v>Ret = <seetype marker="erts:erlang#term">term()</seetype></v>
        <v>Exception = {Class, Reason} | {Class, Reason, Stacktrace}</v>
      </type>
      <desc>
        <p>
          This function must only be used by a process
          that has been started by a
          <seemfa marker="#start/3"><c>start[_link|_monitor]/3,4,5</c></seemfa>
          function. It tells <c>Parent</c> that the process has failed to
          initialize, and immediately raises an exception
          according to <c>Exception</c>.
          The start function then returns <c>Ret</c>.
        </p>
        <p>
          See
          <seemfa marker="erts:erlang#raise/3"><c>erlang:raise/3</c></seemfa>
          for a description of <c>Class</c>, <c>Reason</c>
          and <c>Stacktrace</c>.
        </p>
        <p>
          Function <c>init_fail/2</c> uses the parent value
          previously stored by the start function used.
        </p>
        <warning>
          <p>
            Do not consider catching the exception from this function.
            That would defeat its purpose.  A process started by a
            <seemfa marker="#start/3"><c>start[_link|_monitor]/3,4,5</c></seemfa>
            function should end in a value (that will be ignored)
            or an exception that will be handled by this module.
            See <seeerl marker="#description">Description</seeerl>.
          </p>
        </warning>
        <p>
          If neither this function nor
          <seemfa marker="#init_ack/1"><c>init_ack/1,2</c></seemfa>
          is called by the started process, the start function
          returns an error tuple when the started process exits,
          or when the start function time-out (if used) has passed,
          see <seemfa marker="#start/3"><c>start/3,4,5</c></seemfa>.
        </p>
        <p>The following example illustrates how this function and
          <c>proc_lib:start_link/3</c> can be used:</p>
        <code type="none">
-module(my_proc).
-export([start_link/0]).
-export([init/1]).

start_link() ->
    proc_lib:start_link(my_proc, init, [self()]).

init(Parent) ->
    case do_initialization() of
        ok ->
            proc_lib:init_ack(Parent, {ok, self()});
        {error, Reason} = Error ->
            proc_lib:init_fail(Parent, Error, {exit, normal})
    end,
    loop().

...</code>
      </desc>
    </func>

    <func>
      <name name="initial_call" arity="1" since=""/>
      <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process.
      </fsummary>
      <desc>
        <p>Extracts the initial call of a process that was started
          using one of the spawn or start functions in this module.
          <c><anno>Process</anno></c> can either be a pid, an integer tuple
          (from which a pid can be created), or the process information of a
          process <c>Pid</c> fetched through an
          <c>erlang:process_info(Pid)</c> function call.</p>
        <note>
          <p>The list <c><anno>Args</anno></c> no longer contains the
            arguments, but the same number of atoms as the number of arguments;
            the first atom is <c>'Argument__1'</c>, the second
            <c>'Argument__2'</c>, and so on. The reason is that the argument
            list could waste a significant amount of memory, and if the
            argument list contained funs, it could be impossible to upgrade the
            code for the module.</p>
          <p>If the process was spawned using a fun, <c>initial_call/1</c> no
            longer returns the fun, but the module, function for the
            local function implementing the fun, and the arity, for example,
            <c>{some_module,-work/3-fun-0-,0}</c> (meaning that the fun was
            created in function <c>some_module:work/3</c>). The reason is that
            keeping the fun would prevent code upgrade for the module, and that
            a significant amount of memory could be wasted.</p>
        </note>
      </desc>
    </func>

    <func>
      <name name="spawn" arity="1" since=""/>
      <name name="spawn" arity="2" since=""/>
      <name name="spawn" arity="3" since=""/>
      <name name="spawn" arity="4" since=""/>
      <fsummary>Spawn a new process.</fsummary>
      <type variable="Node"/>
      <type variable="Fun" name_i="1"/>
      <type variable="Module"/>
      <type variable="Function"/>
      <type variable="Args"/>
      <desc>
        <p>Spawns a new process and initializes it as described in the
          beginning of this manual page. The process is spawned using the
          <seemfa marker="erts:erlang#spawn/1"><c>spawn</c></seemfa> BIFs.</p>
      </desc>
    </func>

    <func>
      <name name="spawn_link" arity="1" since=""/>
      <name name="spawn_link" arity="2" since=""/>
      <name name="spawn_link" arity="3" since=""/>
      <name name="spawn_link" arity="4" since=""/>
      <fsummary>Spawn and link to a new process.</fsummary>
      <type variable="Node"/>
      <type variable="Fun" name_i="1"/>
      <type variable="Module"/>
      <type variable="Function"/>
      <type variable="Args"/>
      <desc>
        <p>Spawns a new process and initializes it as described in the
          beginning of this manual page. The process is spawned using the
          <seemfa marker="erts:erlang#spawn_link/1"><c>spawn_link</c></seemfa>
          BIFs.</p>
      </desc>
    </func>

    <func>
      <name name="spawn_opt" arity="2" since=""/>
      <name name="spawn_opt" arity="3" since=""/>
      <name name="spawn_opt" arity="4" since=""/>
      <name name="spawn_opt" arity="5" since=""/>
      <fsummary>Spawn a new process with specified options.</fsummary>
      <type variable="Node"/>
      <type variable="Fun" name_i="1"/>
      <type variable="Module"/>
      <type variable="Function"/>
      <type variable="Args"/>
      <type variable="SpawnOpts"/>
      <desc>
        <p>Spawns a new process and initializes it as described in the
          beginning of this manual page. The process is spawned using the
          <seemfa marker="erts:erlang#spawn_opt/2"><c>erlang:spawn_opt</c></seemfa>
          BIFs.</p>
      </desc>
    </func>

    <func>
      <name name="start" arity="3" since=""/>
      <name name="start" arity="4" since=""/>
      <name name="start" arity="5" since=""/>
      <fsummary>Start a new process synchronously.</fsummary>
      <desc>
        <p>
          Starts a new process synchronously. Spawns the process and
          waits for it to start.
        </p>
        <p>
          To indicate a succesful start,
          the started process <em>must</em> call
          <seemfa marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seemfa>
          where <c>Parent</c> is the process that evaluates this function,
          or <seemfa marker="#init_ack/1"><c>init_ack(Ret)</c></seemfa>.
          <c>Ret</c> is then returned by this function.
        </p>
        <p>
          If the process fails to start, it <em>must</em> fail;
          preferably by calling
          <seemfa marker="#init_fail/3">
            <c>init_fail(Parent, Ret, Exception)</c>
          </seemfa>
          where <c>Parent</c> is the process that evaluates this function,
          or <seemfa marker="#init_fail/2"><c>init_fail(Ret, Exception)</c></seemfa>.
          <c>Ret</c> is then returned by this function,
          and the started process fails with <c>Exception</c>.
        </p>
        <p>
          If the process instead fails before calling
          <c>init_ack/1,2</c> or <c>init_fail/2,3</c>,
          this function returns <c>{error, Reason}</c>
          where <c>Reason</c> depends a bit on the exception
          just like for a process link <c>{'EXIT',Pid,Reason}</c>
          message.
        </p>
        <p>If <c><anno>Time</anno></c> is specified as an integer, this
          function waits for <c><anno>Time</anno></c> milliseconds for the
          new process to call <c>init_ack/1,2</c> or <c>init_fail/2,3</c>,
          otherwise the process gets killed
          and <c>Ret = {error, timeout}</c> is returned.</p>
        <p>Argument <c><anno>SpawnOpts</anno></c>, if specified, is passed
          as the last argument to the <seemfa marker="erts:erlang#spawn_opt/2">
          <c>spawn_opt/2,3,4,5</c></seemfa> BIF.</p>
        <note>
          <p>Using spawn option <c>monitor</c> is not
            allowed. It causes the function to fail with reason
            <c>badarg</c>.</p>
          <p>
            Using spawn option <c>link</c> will set a link to
            the spawned process, just like
            <seemfa marker="#start_link/3">start_link/3,4,5</seemfa>.
          </p>
        </note>
      </desc>
    </func>

    <func>
      <name name="start_link" arity="3" since=""/>
      <name name="start_link" arity="4" since=""/>
      <name name="start_link" arity="5" since=""/>
      <fsummary>Start a new process synchronously.</fsummary>
      <desc>
        <p>
	  Starts a new process synchronously. Spawns the process and
          waits for it to start. A link is atomically set on the
	  newly spawned process.
        </p>
        <note>
          <p>
            If the started process gets killed or crashes with a reason
            that is not `normal`, the process link will kill the calling
            process so this function does not return,
            unless the calling process traps exits.
            For example, if this function times out it will kill
            the spawned process, and then the link might kill
            the calling process.
          </p>
        </note>
        <p>
          Besides setting a link on the spawned process
          this function behaves like
          <seemfa marker="#start/3">start/3,4,5</seemfa>.
        </p>
	<p>
          When the calling process traps exits;
          if this function returns due to the spawned process exiting
          (any error return), this function receives (consumes)
          the <c>'EXIT'</c> message, also when this function times out
          and kills the spawned process.
	</p>
        <note>
          <p>Using spawn option <c>monitor</c> is not
            allowed. It causes the function to fail with reason
            <c>badarg</c>.</p>
        </note>
      </desc>
    </func>

    <func>
      <name name="start_monitor" arity="3" since="OTP 23.0"/>
      <name name="start_monitor" arity="4" since="OTP 23.0"/>
      <name name="start_monitor" arity="5" since="OTP 23.0"/>
      <fsummary>Start a new process synchronously.</fsummary>
      <desc>
        <p>
	  Starts a new process synchronously. Spawns the process and
          waits for it to start. A monitor is atomically set on the
	  newly spawned process.
        </p>
        <p>
          Besides setting a monitor on the spawned process
          this function behaves like
          <seemfa marker="#start/3">start/3,4,5</seemfa>.
        </p>
	<p>
	  The return value is <c>{Ret, Mon}</c> where <c>Ret</c> corresponds
	  to the <c>Ret</c> argument in the call to <c>init_ack/1,2</c>
          or <c>init_fail/2,3</c>, and <c>Mon</c> is the monitor reference
          of the monitor that has been set up.
	</p>
	<p>
          If this function returns due to the spawned process exiting,
          that is returns any error value,
          a <c>'DOWN'</c> message will be delivered to the calling process,
          also when this function times out and kills the spawned process.
	</p>
        <note>
          <p>
            Using spawn option <c>monitor</c> is not
            allowed. It causes the function to fail with reason
            <c>badarg</c>.
          </p>
          <p>
            Using spawn option <c>link</c> will set a link to
            the spawned process, just like
            <seemfa marker="#start_link/3">start_link/3,4,5</seemfa>.
          </p>
        </note>
      </desc>
    </func>

    <func>
      <name name="stop" arity="1" since="OTP 18.0"/>
      <fsummary>Terminate a process synchronously.</fsummary>
      <type variable="Process"/>
      <desc>
        <p>Equivalent to <seemfa marker="#stop/3">
          <c>stop(Process, normal, infinity)</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="stop" arity="3" since="OTP 18.0"/>
      <fsummary>Terminate a process synchronously.</fsummary>
      <type variable="Process"/>
      <type variable="Reason"/>
      <type variable="Timeout"/>
      <desc>
        <p>Orders the process to exit with the specified <c>Reason</c> and
          waits for it to terminate.</p>
        <p>Returns <c>ok</c> if the process exits with
          the specified <c>Reason</c> within <c>Timeout</c> milliseconds.</p>
        <p>If the call times out, a <c>timeout</c> exception is raised.</p>
        <p>If the process does not exist, a <c>noproc</c>
          exception is raised.</p>
        <p>The implementation of this function is based on the
          <c>terminate</c> system message, and requires that the
          process handles system messages correctly.
          For information about system messages, see
          <seeerl marker="sys"><c>sys(3)</c></seeerl> and section
          <seeguide marker="system/design_principles:spec_proc">
          sys and proc_lib</seeguide> in OTP Design Principles.</p>
      </desc>
    </func>

    <func>
      <name name="translate_initial_call" arity="1" since=""/>
      <fsummary>Extract and translate the initial call of a
        <c>proc_lib</c>spawned process.</fsummary>
      <desc>
        <p>This function is used by functions
          <seemfa marker="c#i/0"><c>c:i/0</c></seemfa> and
          <seemfa marker="c#regs/0"><c>c:regs/0</c></seemfa>
          to present process information.</p>
        <p>This function extracts the initial call of a process that was
          started using one of the spawn or start functions in this module,
          and translates it to more useful information.
          <c><anno>Process</anno></c>
          can either be a pid, an integer tuple (from which a pid can
          be created), or the process information of a process
          <c>Pid</c> fetched through an <c>erlang:process_info(Pid)</c>
          function call.</p>
        <p>If the initial call is to one of the system-defined behaviors
          such as <c>gen_server</c> or <c>gen_event</c>, it is
          translated to more useful information. If a <c>gen_server</c>
          is spawned, the returned <c><anno>Module</anno></c> is the name of
          the callback module and <c><anno>Function</anno></c> is <c>init</c>
          (the function that initiates the new server).</p>
        <p>A <c>supervisor</c> and a <c>supervisor_bridge</c> are also
          <c>gen_server</c> processes. To return information
          that this process is a supervisor and the name of the
          callback module, <c><anno>Module</anno></c> is <c>supervisor</c> and
          <c><anno>Function</anno></c> is the name of the supervisor callback
          module. <c><anno>Arity</anno></c> is <c>1</c>, as the <c>init/1</c>
          function is called initially in the callback module.</p>
        <p>By default, <c>{proc_lib,init_p,5}</c> is returned if no
          information about the initial call can be found. It is
          assumed that the caller knows that the process has been
          spawned with the <c>proc_lib</c> module.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p><seeerl marker="kernel:error_logger">
      <c>error_logger(3)</c></seeerl></p>
    <p><seeerl marker="kernel:logger">
      <c>logger(3)</c></seeerl></p>
  </section>
</erlref>