# proc_lib

### MODULE

proc_lib

### MODULE SUMMARY

Functions for asynchronous and synchronous start of processes adhering to the OTP design principles.

### DESCRIPTION

This module is used to start processes adhering to the OTP Design Principles. Specifically, the functions in this module are used by the OTP standard behaviors (`gen_server`, `gen_fsm`, ...) when starting new processes. The functions can also be used to start special processes, user defined processes which comply to the OTP design principles. See Sys and Proc_Lib in OTP Design Principles for an example.

Some useful information is initialized when a process starts. The registered names, or the process identifiers, of the parent process, and the parent ancestors, are stored together with information about the function initially called in the process.

While in "plain Erlang" a process is said to terminate normally only for the exit reason `normal`, a process started using `proc_lib` is also said to terminate normally if it exits with reason `shutdown`. This is the reason used when an application (supervision tree) is stopped.

When a process started using `proc_lib` terminates abnormally -- that is, with another exit reason than `normal` or `shutdown` -- a crash report is generated, which is written to terminal by the default SASL event handler. That is, the crash report is normally only visible if the SASL application is started. See sasl(6) and SASL User's Guide.

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

### EXPORTS

`spawn(Fun) -> pid()`
`spawn(Node, Fun) -> pid()`
`spawn(Module, Function, Args) -> pid()`
`spawn(Node, Module, Function, Args) -> pid()`

Types:

`Node = node()`
`Fun = fun() -> void()`
`Module = Function = atom()`
`Args = [term()]`

Spawns a new process and initializes it as described above. The process is spawned using the spawn BIFs.

`spawn_link(Fun) -> pid()`
`spawn_link(Node, Fun) -> pid()`
`spawn_link(Module, Function, Args) -> pid()`
`spawn_link(Node, Module, Function, Args) -> pid()`

Types:

`Node = node()`
`Fun = fun() -> void()`
`Module = Function = atom()`
`Args = [term()]`

Spawns a new process and initializes it as described above. The process is spawned using the spawn_link BIFs.

`spawn_opt(Fun, SpawnOpts) -> pid()`
`spawn_opt(Node, Fun, SpawnOpts) -> pid()`
`spawn_opt(Module, Function, Args, SpawnOpts) -> pid()`
`spawn_opt(Node, Module, Func, Args, SpawnOpts) -> pid()`

Types:

`Node = node()`
`Fun = fun() -> void()`
`Module = Function = atom()`
`Args = [term()]`
`SpawnOpts -- see erlang:spawn_opt/2,3,4,5`

Spawns a new process and initializes it as described above. The process is spawned using the spawn_opt BIFs.

| Using the spawn option `monitor` is currently not allowed, but will cause the function to fail with reason `badarg`.

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

Types:

`Module = Function = atom()`
`Args = [term()]`
`Time = int() >= 0 | infinity`
`SpawnOpts -- see erlang:spawn_opt/2,3,4,5`
`Ret = term() | {error, Reason}`

Starts a new process synchronously. Spawns the process and waits for it to start. When the process has started, it must call init_ack(Parent,Ret) or init_ack(Ret), where `Parent` is the process that evaluates this function. At this time, `Ret` is returned.

If the `start_link/3,4,5` function is used and the process crashes before it has called `init_ack/1,2`, `{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 new process to call `init_ack`, or `{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/2,3,4,5` BIF.

| Using the spawn option `monitor` is currently not allowed, but will cause the function to fail with reason `badarg`.

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

Types:

`Parent = pid()`
`Ret = term()`

This function must used by a process that has been started by a start[_link]/3,4,5 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 start function used.

If this function is not called, the start function will return an error tuple (if a link and/or a timeout is used) or hang otherwise.

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

    -module(my_proc).
    -export([start_link/0]).
    -export([init/1]).

    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().

    ...

`format(CrashReport) -> string()`

Types:

`CrashReport = term()`

This function can be used by a user defined event handler to format a crash report. The crash report is sent using `error_logger:error_report(crash_report, CrashReport)`. That is, the event to be handled is of the format `{error_report, GL, {Pid, crash_report, CrashReport}}` where `GL` is the group leader pid of the process `Pid` which sent the crash report.

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

Types:

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

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

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

Types:

`Process = pid() | {X,Y,Z} | ProcInfo`
`X = Y = Z = int()`
`ProcInfo = term()`
`Module = Function = atom()`
`Arity = int()`
`Fun = fun() -> void()`

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

Extracts the initial call of a process that was started using one of the spawn or start functions described above, and translates it to more useful information. `Process` can either be a pid, an integer tuple (from which a pid can be created), or the process information of a process `Pid` fetched through an `erlang:process_info(Pid)` function call.

If the initial call is to one of the system defined behaviors 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.

`hibernate(Module, Function, Args)`

Types:

`Module = Function = atom()`
`Args = [term()]`

This function does the same as (and does call) the BIF hibernate/3, but ensures that exception handling and logging continues to work as expected when the process wakes up. Always use this function instead of the BIF for processes started using `proc_lib` functions.

### SEE ALSO

error_logger(3)

### AUTHORS

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

stdlib 1.14.5
Copyright © 1991-2007 Ericsson AB