proc_lib - Functions for asynchronous and synchronous start of processes

Data Types

spawn_option() = erlang:spawn_opt_option()

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

       start_spawn_option() =
           link |
           {priority, erlang:priority_level()} |
           {max_heap_size, erlang:max_heap_size()} |
           {min_heap_size, integer() >= 0} |
           {min_bin_vheap_size, integer() >= 0} |
           {fullsweep_after, integer() >= 0} |
           {message_queue_data, erlang:message_queue_data()}

              A restricted set of spawn options. Most notably monitor is not part of these options.

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

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 specialprocesses, 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 crashreport 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 errorreports, 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.

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)->okinit_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()|{pid(),reference()}spawn_opt(Node,Function,SpawnOpts)->
                    pid() | {pid(), reference()}

       spawn_opt(Module,Function,Args,SpawnOpts)->
                    pid() | {pid(), reference()}

       spawn_opt(Node,Module,Function,Args,SpawnOpts)->
                    pid() | {pid(), reference()}

              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 erlang:spawn_opt BIFs.

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

              Types:

                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Time = timeout()
                 SpawnOpts = [start_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  Time is specified as an integer, this function waits for Time milliseconds for the new process
              to call init_ack, or Ret={error,timeout} will be 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.

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

              Types:

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

              Starts a new process synchronously. Spawns the process and waits  for  it  to  start.  A  link  is
              atomically  set  on  the  newly  spawned  process.  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  Time is specified as an integer, this function waits for Time milliseconds for the new process
              to call init_ack, or Ret={error,timeout} will be returned, and the process is killed.

              If the process crashes before it has called init_ack/1,2, Ret={error,Reason} will  be  returned
              if the calling process traps exits.

              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.

       start_monitor(Module,Function,Args)->{Ret,Mon}start_monitor(Module,Function,Args,Time)->{Ret,Mon}start_monitor(Module,Function,Args,Time,SpawnOpts)->
                        {Ret, Mon}

              Types:

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

              Starts  a  new  process  synchronously. Spawns the process and waits for it to start. A monitor is
              atomically set on the  newly  spawned  process.  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 Time is specified as an integer, this function waits for Time milliseconds for the new  process
              to call init_ack, or Ret={error,timeout} will be returned, and the process is killed.

              The  return  value  is  {Ret,Mon}  where  Ret  corresponds  to  the  Ret argument in the call to
              init_ack(), and Mon is the monitor reference of the monitor that has been set up.

              A 'DOWN' message will be delivered to the caller if this function returns, and the spawned process
              terminates. This is true also in the case when the operation times out.

              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.

Name

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