proc_lib(3)

MODULE
proc_lib - Plug-in Replacements for spawn/3,4 and spawn_link/3,4.

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(Module,Func,Args) -> Pid
spawn(Node,Module,Func,Args) -> Pid

    Types
        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 BIF. The process can be spawned on another Node.

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

    Types
        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 BIF. The process can be spawned on another Node.

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

    Types
        Module = atom()
        Func = atom()
        Args = [Arg]
        Arg = term()
        Opts = list()
        Pid = pid()

    Spawns a new process and initializes it as described above. The process is spawned using the spawn_opt/4 BIF. The Opts argument is passed to spawn_opt/4.

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} | false

    Types
        PidOrPinfo = pid() | {X, Y, Z} | ProcInfo
        X = Y = Z = int()
        ProcInfo = [void()]
        Module = atom()
        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 a erlang:process_info/1 function call).

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

    Types
        PidOrPinfo = pid() | {X, Y, Z} | ProcInfo
        X = Y = Z = int()
        ProcInfo = [void()]
        Module = atom()
        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 a 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)

AUTHOR
Magnus Froberg - support@erlang.ericsson.se