Provided by: erlang-manpages_24.3.4.1+dfsg-1_all 
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() = 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 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() | {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) -> 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
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) -> 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 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.
SEE ALSO
error_logger(3erl)
logger(3erl)