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

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.

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.

hibernate(Module, Function, Arguments)

Types

Module = atom()

Function = atom()

Arguments = [term()]

hibernate/3 gives a way to put a process started using one of the functions in the proc_lib module into a wait state where its memory allocation has been reduced as much as possible, which is useful if the process does not expect to receive any messages in the near future.

The process will be awaken when a message is sent to it, and control will resume in Module:Function with the arguments given by ArgumentList.

If the process has any message in its message queue, the process will be awaken immediately in the same way as described above.

Note: The actual work is done by the erlang:hibernate/3 BIF. To ensure that exception handling and logging continues to work in a process started by proc_lib, always use proc_lib:hibernate rather than erlang:hibernate/3.

error_logger(3)

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