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)