proc_lib(3)



proc_lib(3erl)             Erlang Module Definition             proc_lib(3erl)

NAME
       proc_lib  -  Functions  for  asynchronous and synchronous start of pro-
       cesses
           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 princi-
       ples. For an example, see section  sys and proc_lib in OTP Design Prin-
       ciples.

       Some useful information is initialized when a process starts. The  reg-
       istered  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 {shut-
       down,Term}. shutdown is the reason used when an  application  (supervi-
       sion tree) is stopped.

       When  a  process  that  is started using proc_lib terminates abnormally
       (that is, with another exit reason than  normal,  shutdown,  or  {shut-
       down,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 excep-
       tions 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 termi-
       nating.

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

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 er-
              ror_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  re-
              port.

       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 er-
              ror_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 other-
              wise.

              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 cre-
              ated), 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 im-
              possible 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_mod-
              ule,-work/3-fun-0-,0} (meaning that the fun was created in func-
              tion some_module:work/3). The reason is  that  keeping  the  fun
              would  prevent  code upgrade for the module, and that a signifi-
              cant 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  be-
              ginning  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  be-
              ginning  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  be-
              ginning  of  this  manual page. The process is spawned using the
              erlang:spawn_opt BIFs.

       start(Module, Function, Args) -> Ret

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

       start(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 re-
              turned.

              If Time is specified as an integer, this function waits for Time
              milliseconds for the new process to call init_ack, or Ret = {er-
              ror, 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 func-
              tion to fail with reason badarg.

       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 = [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  re-
              turned.

              If Time is specified as an integer, this function waits for Time
              milliseconds for the new process to call init_ack, or Ret = {er-
              ror, 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  func-
              tion 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 re-
              turned.

              If Time is specified as an integer, this function waits for Time
              milliseconds for the new process to call init_ack, or Ret = {er-
              ror, 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 ref-
              erence of the monitor that has been set up.

              A 'DOWN' message will be delivered to the caller if  this  func-
              tion  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 func-
              tion 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 Princi-
              ples.

       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  mod-
              ule,  and  translates it to more useful information. Process can
              either be a pid, an integer tuple (from which a pid can be  cre-
              ated),  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 func-
              tion that initiates the new server).

              A supervisor and a supervisor_bridge are  also  gen_server  pro-
              cesses.  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)

Ericsson AB                       stdlib 3.13                   proc_lib(3erl)

Man(1) output converted with man2html
list of all man pages