# 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.

`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`.

### See Also

error_logger(3)

### AUTHORS

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

stdlib 1.14
Copyright © 1991-2006 Ericsson AB