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

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 ( gen_server , gen_fsm , ...) when starting new processes. The functions can also be used to start special processes
       , user defined processes which comply to the OTP design principles. See Sys and Proc_Lib in OTP Design Principles for an example.

       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 the 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 (supervi-
       sion tree) is stopped.

       When a process 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 SASL event handler. That is, the crash report is
       normally only visible if the SASL application is started. See sasl(7) and SASL User's Guide .

       The crash report contains the previously stored information such as ancestors and initial function, the termination reason, and information
       regarding other processes which terminate as a result of this process terminating.

EXPORTS

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

	      Types  Node = node()
		     Fun = fun() -> void()
		     Module = Function = atom()
		     Args = [term()]

	      Spawns a new process and initializes it as described above. 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 = fun() -> void()
		     Module = Function = atom()
		     Args = [term()]

	      Spawns a new process and initializes it as described above. The process is spawned using the spawn_link BIFs.

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

	      Types  Node = node()
		     Fun = fun() -> void()
		     Module = Function = atom()
		     Args = [term()]
		     SpawnOpts -- see erlang:spawn_opt/2,3,4,5

	      Spawns a new process and initializes it as described above. The process is spawned using the spawn_opt BIFs.

   Note:
       Using the spawn option monitor is currently not allowed, but will cause 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 = Function = atom()
		     Args = [term()]
		     Time = int() >= 0 | infinity
		     SpawnOpts -- see erlang:spawn_opt/2,3,4,5
		     Ret = term() | {error, Reason}

	      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 the start_link/3,4,5 function 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.

	      The SpawnOpts argument, if given, will be passed as the last argument to the spawn_opt/2,3,4,5 BIF.

   Note:
       Using the spawn option monitor is currently not allowed, but will cause the function to fail with reason badarg .

       init_ack(Parent, Ret) -> void()
       init_ack(Ret) -> void()

	      Types  Parent = pid()
		     Ret = term()

	      This function must 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.

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

	      If  this	function  is not called, the start function will return an error tuple (if a link and/or a timeout 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().

       format(CrashReport) -> string()

	      Types  CrashReport = term()

	      This function can be used by a user defined event handler to format a crash report.  The	crash  report  is  sent  using	error_log-
	      ger:error_report(crash_report,  CrashReport)  .  That  is,  the  event  to  be  handled  is  of  the format {error_report, GL, {Pid,
	      crash_report, CrashReport}} where GL is the group leader pid of the process Pid which sent the crash report.

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

	      Types  Process = pid() | {X,Y,Z} | ProcInfo
		     X = Y = Z = int()
		     ProcInfo = term()
		     Module = Function = atom()
		     Args = [atom()]

	      Extracts the initial call of a process that was started using one of the spawn or  start	functions  described  above.  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 actual arguments, but the same number of atoms as the number of arguments; the first  atom	is  always
       '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 actual fun, but the module, function for  the  local  function
       implementing  the  fun,	and  the  arity,  for  instance  {some_module,-work/3-fun-0-,0}  (meaning that the fun was created in the 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.

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

	      Types  Process = pid() | {X,Y,Z} | ProcInfo
		     X = Y = Z = int()
		     ProcInfo = term()
		     Module = Function = atom()
		     Arity = int()
		     Fun = fun() -> void()

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

	      Extracts the initial call of a process that was started using one of the spawn or start functions described above, 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 informa-
	      tion 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. In order to return information that this process is a supervisor
	      and the name of the call-back module, Module is supervisor and Function is the name of the supervisor callback module.  Arity  is  1
	      since 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.

       hibernate(Module, Function, Args)

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

	      This function does the same as (and does call) the BIF hibernate/3 , 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 func-
	      tions.

SEE ALSO

       error_logger(3erl)

Ericsson AB							   stdlib 1.17.3						    proc_lib(3erl)