proc_lib

MODULE

proc_lib

MODULE SUMMARY

Plug-in Replacements for spawn/1,2,3,4, spawn_link/1,2,3,4, and spawn_opt/2,3,4,5.

DESCRIPTION

The proc_lib module is used to initialize some useful information when a process starts. The registered names, or the process identities, of the parent process, and the parent ancestors, are stored together with information about the function initially called in the process.

A crash report is generated if the process terminates with a reason other than normal or shutdown. shutdown is used to terminate an abnormal process in a controlled manner. A 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.

The crash report is sent to the error_logger. An event handler has to be installed in the error_logger event manager in order to handle these reports. The crash report is tagged crash_report and the format/1 function should be called in order to format the report.

EXPORTS

spawn(Fun) -> Pid
spawn(Node,Fun) -> Pid
spawn(Module,Func,Args) -> Pid
spawn(Node,Module,Func,Args) -> Pid

Types:
Fun = fun() -> void()
Module = atom()
Func = atom()
Args = [Arg]
Arg = term()
Node = atom()
Pid = pid()

Spawns a new process and initializes it as described above. The process is spawned using the spawn BIFs. The process can be spawned on another Node.

spawn_link(Fun) -> Pid
spawn_link(Node,Fun) -> Pid
spawn_link(Module,Func,Args) -> Pid
spawn_link(Node,Module,Func,Args) -> Pid

Types:
Fun = fun() -> void()
Module = atom()
Func = atom()
Args = [Arg]
Arg = term()
Node = atom()
Pid = pid()

Spawns a new process and initializes it as described above. The process is spawned using the spawn_link BIFs. The process can be spawned on another Node.

spawn_opt(Fun,Opts) -> Pid
spawn_opt(Node,Fun,Opts) -> Pid
spawn_opt(Module,Func,Args,Opts) -> Pid
spawn_opt(Node,Module,Func,Args,Opts) -> Pid

Types:
Fun = fun() -> void()
Module = atom()
Func = atom()
Args = [Arg]
Arg = term()
Node = atom()
Opts = list()
Pid = pid()

Spawns a new process and initializes it as described above. The process is spawned using the spawn_opt BIFs. The process can be spawned on another Node.

start(Module,Func,Args) -> Ret
start(Module,Func,Args,Time) -> Ret
start(Module,Func,Args,Time,SpawnOpts) -> Ret
start_link(Module,Func,Args) -> Ret
start_link(Module,Func,Args,Time) -> Ret
start_link(Module,Func,Args,Time,SpawnOpts) -> Ret

Types:
Module = atom()
Func = atom()
Args = [Arg]
Arg = term()
Time = integer >= 0 | infinity
SpawnOpts = list()
Ret = term() | {error, Reason}

Starts a new process synchronously. Spawns the process using proc_lib:spawn/3 or proc_lib:spawn_link/3, and waits for the process to start. When the process has started, it must call proc_lib:init_ack(Parent, Ret) or proc_lib:init_ack(Ret), where Parent is the process that evaluates start. At this time, Ret is returned from start.

If the start_link function is used and the process crashes before proc_lib:init_ack is called, {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 process to start (proc_lib:init_ack). If it has not started within this time, {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/4 BIF. Refer to the erlang module for information about the spawn_opt options.

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

Types:
Parent = pid()
Ret = term()

This function is used by a process that has been started by a proc_lib:start 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 proc_lib:start function. If the init_ack function is not called (e.g. if the init function crashes) and proc_lib:start/3 is used, that function never returns and the parent hangs forever. This can be avoided by using a time out in the call to start, or by using start_link.

The following example illustrates how this function and proc_lib:start_link are used.

-module(my_proc).
-export([start_link/0]).
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().
loop() ->
    receive
        ....

format(CrashReport) -> string()

Types:
CrashReport = void()

Formats a previously generated crash report. The formatted report is returned as a string.

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

Types:
PidOrPinfo = pid() | {X,Y,Z} | ProcInfo
X = Y = Z = int()
ProcInfo = [void()]
Module = atom()
Fun = fun() -> void()
Function = atom()
Args = [term()]

Extracts the initial call of a process that was spawned using the spawn functions described above. PidOrPinfo can either be a Pid, an integer tuple (from which a pid can be created), or the process information of a process (fetched through an erlang:process_info/1 function call).

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

Types:
PidOrPinfo = pid() | {X,Y,Z} | ProcInfo
X = Y = Z = int()
ProcInfo = [void()]
Module = atom()
Fun = fun() -> void()
Function = atom()
Arity = int()

Extracts the initial call of a process which was spawned using the spawn functions described above. If the initial call is to one of the system defined behaviours 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.

PidOrPinfo can either be a Pid, an integer tuple (from which a pid can be created), or the process information of a process (fetched through an erlang:process_info/1 function call).

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

See Also

error_logger(3)

AUTHORS

Magnus Fröberg - support@erlang.ericsson.se