table of contents
other versions
- jessie 1:17.3-dfsg-4+deb8u2
- jessie-backports 1:19.2.1+dfsg-2+deb9u1~bpo8+1
- stretch 1:19.2.1+dfsg-2+deb9u2
- testing 1:21.2.5+dfsg-1
- unstable 1:21.2.6+dfsg-1
- experimental 1:22.0~rc1+dfsg-1
proc_lib(3erl) | Erlang Module Definition | proc_lib(3erl) |
NAME¶
proc_lib - Functions for asynchronous and synchronous start of processesadhering 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, gen_fsm, 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 SASL event handler. That is, the crash report is normally only visible if the SASL application is started; see sasl(7) and section SASL Error Logging in the SASL User's Guide. 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() =link |monitor |{priority, priority_level()} |{max_heap_size, max_heap_size()} |{min_heap_size, integer() >= 0} |{min_bin_vheap_size, integer() >= 0} |{fullsweep_after, integer() >= 0} |{message_queue_data, off_heap | on_heap | mixed}
See erlang:spawn_opt/2,3,4,5.
priority_level() = high | low | max | normalmax_heap_size() =integer() >= 0 |#{size => integer() >= 0,kill => true,error_logger => true}
See erlang:process_flag(max_heap_size, MaxHeapSize).
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
This function can be used by a user-defined event handler to format a crash
report. The crash report is sent using
error_logger: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
process Pid that sent the crash report.
format(CrashReport, Encoding, Depth) -> string()
Types:
CrashReport = [term()]
Encoding = latin1 | unicode | utf8
Depth = unlimited | integer() >= 1
This function can be used by a user-defined 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()
spawn_opt(Node, Function, SpawnOpts) -> pid()
spawn_opt(Module, Function, Args, SpawnOpts) -> pid()
spawn_opt(Node, Module, Function, Args, SpawnOpts) -> pid()
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 spawn_opt BIFs.
Note:
Using spawn option monitor is not allowed. It causes 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 = module()
Function = atom()
Args = [term()]
Time = timeout()
SpawnOpts = [ 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 function start_link/3,4,5 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.
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)stdlib 3.2 | Ericsson AB |