# proc_lib

### MODULE

proc_lib

### MODULE SUMMARY

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)

### AUTHORS

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

stdlib 1.10.1
Copyright © 1991-2002 Ericsson Utvecklings AB