Provided by: erlang-manpages_22.0.7+dfsg-1build1_all bug

NAME

       proc_lib - Functions for asynchronous and synchronous start of processes
           adhering to the OTP design principles.

DESCRIPTION

       This  module  is  used  to  start  processes  adhering  to  the   OTP  Design  Principles.
       Specifically, the functions in this module are used by the  OTP  standard  behaviors  (for
       example, gen_server and gen_statem) when starting new processes. The functions can also be
       used to start special processes, user-defined processes that  comply  to  the  OTP  design
       principles. For an example, see section  sys and proc_lib in OTP Design Principles.

       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.

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

       When a process that is started using proc_lib terminates abnormally (that is, with another
       exit reason than normal, shutdown, or {shutdown,Term}), a crash report 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 SASL Error Logging in
       the SASL User's Guide.

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

       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.

DATA TYPES

       spawn_option() =
           link | monitor |
           {priority, priority_level()} |
           {max_heap_size, max_heap_size()} |
           {min_heap_size, integer() >= 0} |
           {min_bin_vheap_size, integer() >= 0} |
           {fullsweep_after, integer() >= 0} |
           {message_queue_data, off_heap | on_heap | mixed}

              See erlang:spawn_opt/2,3,4,5.

       priority_level() = high | low | max | normal

       max_heap_size() =
           integer() >= 0 |
           #{size => integer() >= 0,
             kill => true,
             error_logger => true}

              See  erlang:process_flag(max_heap_size, MaxHeapSize).

       dict_or_pid() =
           pid() |
           (ProcInfo :: [term()]) |
           {X :: integer(), Y :: integer(), Z :: integer()}

EXPORTS

       format(CrashReport) -> string()

              Types:

                 CrashReport = [term()]

              Equivalent to format(CrashReport, latin1).

       format(CrashReport, Encoding) -> string()

              Types:

                 CrashReport = [term()]
                 Encoding = latin1 | unicode | utf8

          Note:
              This function is deprecated in the sense that the error_logger  is  no  longer  the
              preferred  interface  for  logging  in  Erlang/OTP.  A new logging API was added in
              Erlang/OTP 21.0, but legacy error_logger handlers can still  be  used.  New  Logger
              handlers  do  not  need  to  use  this  function,  since  the  formatting  callback
              (report_cb) is included as metadata in the log event.

              This function can be used by a user-defined legacy error_logger  event  handler  to
              format  a  crash report. The crash report is sent using logger(3erl), and the event
              to  be  handled  is  of  the  format   {error_report,   GL,   {Pid,   crash_report,
              CrashReport}},  where GL is the group leader pid of process Pid that sent the crash
              report.

       format(CrashReport, Encoding, Depth) -> string()

              Types:

                 CrashReport = [term()]
                 Encoding = latin1 | unicode | utf8
                 Depth = unlimited | integer() >= 1

          Note:
              This function is deprecated in the sense that the error_logger  is  no  longer  the
              preferred  interface  for  logging  in  Erlang/OTP.  A new logging API was added in
              Erlang/OTP 21.0, but legacy error_logger handlers can still  be  used.  New  Logger
              handlers  do  not  need  to  used  this  function,  since  the  formatting callback
              (report_cb) is included as metadata in the log event.

              This function can be used by a user-defined legacy error_logger  event  handler  to
              format a crash report. When Depth is specified as a positive integer, it is used in
              the  format  string  to  limit   the   output   as   follows:   io_lib:format("~P",
              [Term,Depth]).

       hibernate(Module, Function, Args) -> no_return()

              Types:

                 Module = module()
                 Function = atom()
                 Args = [term()]

              This  function  does  the  same as (and does call) the hibernate/3 BIF, but ensures
              that exception handling and logging continues to work as expected when the  process
              wakes up.

              Always  use  this  function instead of the BIF for processes started using proc_lib
              functions.

       init_ack(Ret) -> ok

       init_ack(Parent, Ret) -> ok

              Types:

                 Parent = pid()
                 Ret = term()

              This  function  must  be  used  by  a  process  that  has   been   started   by   a
              start[_link]/3,4,5  function.  It  tells  Parent  that  the process has initialized
              itself, has started, or has failed to initialize itself.

              Function init_ack/1 uses the parent value previously stored by the  start  function
              used.

              If  this  function  is  not called, the start function returns an error tuple (if a
              link and/or a time-out is used) or hang otherwise.

              The following example illustrates how this function and  proc_lib:start_link/3  are
              used:

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

              ...

       initial_call(Process) -> {Module, Function, Args} | false

              Types:

                 Process = dict_or_pid()
                 Module = module()
                 Function = atom()
                 Args = [atom()]

              Extracts  the  initial call of a process that was started using one of the spawn or
              start functions in this module. Process can either be a pid, an integer tuple (from
              which  a  pid  can be created), or the process information of a process Pid fetched
              through an erlang:process_info(Pid) function call.

          Note:
              The list Args no longer contains the arguments, but the same number of atoms as the
              number of arguments; the first atom is 'Argument__1', the second 'Argument__2', 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.

              If the process was spawned using a fun, initial_call/1 no longer returns  the  fun,
              but  the  module,  function  for  the  local function implementing the fun, and the
              arity, for  example,  {some_module,-work/3-fun-0-,0}  (meaning  that  the  fun  was
              created  in  function some_module:work/3). The reason is that keeping the fun would
              prevent code upgrade for the module, and that a significant amount of memory  could
              be wasted.

       spawn(Fun) -> pid()

       spawn(Node, Fun) -> pid()

       spawn(Module, Function, Args) -> pid()

       spawn(Node, Module, Function, Args) -> pid()

              Types:

                 Node = node()
                 Fun = function()
                 Module = module()
                 Function = atom()
                 Args = [term()]

              Spawns  a  new  process  and  initializes  it as described in the beginning of this
              manual page. The process is spawned using the spawn BIFs.

       spawn_link(Fun) -> pid()

       spawn_link(Node, Fun) -> pid()

       spawn_link(Module, Function, Args) -> pid()

       spawn_link(Node, Module, Function, Args) -> pid()

              Types:

                 Node = node()
                 Fun = function()
                 Module = module()
                 Function = atom()
                 Args = [term()]

              Spawns a new process and initializes it as  described  in  the  beginning  of  this
              manual page. The process is spawned using the spawn_link BIFs.

       spawn_opt(Fun, SpawnOpts) -> pid()

       spawn_opt(Node, Function, SpawnOpts) -> pid()

       spawn_opt(Module, Function, Args, SpawnOpts) -> pid()

       spawn_opt(Node, Module, Function, Args, SpawnOpts) -> pid()

              Types:

                 Node = node()
                 Fun = function()
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 SpawnOpts = [spawn_option()]

              Spawns  a  new  process  and  initializes  it as described in the beginning of this
              manual page. The process is spawned using the spawn_opt BIFs.

          Note:
              Using spawn option monitor is not allowed. It causes  the  function  to  fail  with
              reason badarg.

       start(Module, Function, Args) -> Ret

       start(Module, Function, Args, Time) -> Ret

       start(Module, Function, Args, Time, SpawnOpts) -> Ret

       start_link(Module, Function, Args) -> Ret

       start_link(Module, Function, Args, Time) -> Ret

       start_link(Module, Function, Args, Time, SpawnOpts) -> Ret

              Types:

                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Time = timeout()
                 SpawnOpts = [spawn_option()]
                 Ret = term() | {error, Reason :: term()}

              Starts  a  new process synchronously. Spawns the process and waits for it to start.
              When the process has started, it must call init_ack(Parent, Ret) or  init_ack(Ret),
              where  Parent  is  the  process  that evaluates this function. At this time, Ret is
              returned.

              If function start_link/3,4,5 is used and the process crashes before it  has  called
              init_ack/1,2, {error, Reason} is returned if the calling process traps exits.

              If  Time  is specified as an integer, this function waits for Time milliseconds for
              the new process to call init_ack, or {error, timeout} is returned, and the  process
              is killed.

              Argument   SpawnOpts,  if  specified,  is  passed  as  the  last  argument  to  the
              spawn_opt/2,3,4,5 BIF.

          Note:
              Using spawn option monitor is not allowed. It causes  the  function  to  fail  with
              reason badarg.

       stop(Process) -> ok

              Types:

                 Process = pid() | RegName | {RegName, node()}

              Equivalent to stop(Process, normal, infinity).

       stop(Process, Reason, Timeout) -> ok

              Types:

                 Process = pid() | RegName | {RegName, node()}
                 Reason = term()
                 Timeout = timeout()

              Orders the process to exit with the specified Reason and waits for it to terminate.

              Returns  ok  if  the  process  exits  with  the  specified  Reason  within  Timeout
              milliseconds.

              If the call times out, a timeout exception is raised.

              If the process does not exist, a noproc exception is raised.

              The implementation of this function is based on the terminate system  message,  and
              requires  that the process handles system messages correctly. For information about
              system messages, see  sys(3erl)  and  section   sys  and  proc_lib  in  OTP  Design
              Principles.

       translate_initial_call(Process) -> {Module, Function, Arity}

              Types:

                 Process = dict_or_pid()
                 Module = module()
                 Function = atom()
                 Arity = byte()

              This  function  is  used  by  functions  c:i/0  and  c:regs/0  to  present  process
              information.

              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. Process can either be a pid, an integer tuple (from which a pid can be
              created),  or  the  process  information  of  a  process  Pid  fetched  through  an
              erlang:process_info(Pid) function call.

              If the initial call is to one of the system-defined behaviors such as gen_server or
              gen_event, it is translated to more useful information. If a gen_server is spawned,
              the returned Module is the name of the callback module and Function  is  init  (the
              function that initiates the new server).

              A  supervisor  and  a  supervisor_bridge  are  also gen_server processes. To return
              information that this process is a supervisor and the name of the callback  module,
              Module  is  supervisor  and Function is the name of the supervisor callback module.
              Arity is 1, as the init/1 function is called initially in the callback module.

              By default, {proc_lib,init_p,5} 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 proc_lib module.

SEE ALSO

       error_logger(3erl)

       logger(3erl)