From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/proc_lib.xml | 415 ++++++++++++++++++++++------------------ 1 file changed, 224 insertions(+), 191 deletions(-) (limited to 'lib/stdlib/doc/src/proc_lib.xml') diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index f02b1f0651..58ca5644cf 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -29,44 +29,55 @@ proc_lib - Functions for asynchronous and synchronous start of processes adhering to the OTP design principles. + Functions for asynchronous and synchronous start of processes + adhering to the OTP design principles.

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, gen_statem, ...) 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.

+ the + OTP Design Principles. Specifically, the functions in this + module are used by the OTP standard behaviors (for example, + gen_server, gen_fsm, and gen_statem) + when starting new processes. The functions + can also be used to start special processes, user-defined + processes that comply to the OTP design principles. For an example, + see section + sys and proc_lib in OTP Design Principles.

+ +

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 + +

While in "plain Erlang", a process is said to terminate normally + only for exit reason normal, a process started using proc_lib is also said to terminate normally if it exits with reason shutdown or {shutdown,Term}. shutdown 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, - shutdown, or {shutdown,Term} -- a crash report - is generated, which is written to terminal by the default SASL + +

When a process that is started using proc_lib terminates + abnormally (that is, with another exit reason than normal, + shutdown, or {shutdown,Term}), 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 + if the SASL application is started; see + sasl(6) and section + SASL Error Logging + in the 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 + information about other processes that terminate as a result of this process terminating.

 +

See - erlang:spawn_opt/2,3,4,5.

+ erlang:spawn_opt/2,3,4,5.

 @@ -83,7 +94,128 @@ + + + + Format a crash report. + +

Equivalent to + format(CrashReport, latin1).

+ + + + + + Format a crash report. + +

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 process + Pid that sent the crash report.

+ + + + + + Format a crash report. + +

This function can be used by a user-defined event handler to + format a crash report. When Depth is specified as a + positive integer, it is used in the format string to + limit the output as follows: io_lib:format("~P", + [Term,Depth]).

+ + + + + + Hibernate a process until a message is sent to it. + +

This function does the same as (and does call) the + + hibernate/3 BIF, + 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.

+ + + + + + + Used by a process when it has started. + +

This function must be 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.

+

Function init_ack/1 uses the parent value + previously stored by the start function used.

+

If this function is not called, the start function + returns an error tuple (if a link and/or a time-out 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(). + +... + + + + + + Extract the initial call of a proc_libspawned process. + + +

Extracts the initial call of a process that was started + using one of the spawn or start functions in this module. + 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.

+ +

The list Args no longer contains the + arguments, but the same number of atoms as the number of arguments; + the first atom is 'Argument__1', the second + 'Argument__2', and so on. The reason is that the argument + list could waste a significant amount of memory, and if the + argument list contained funs, it could be impossible to upgrade the + code for the module.

+

If the process was spawned using a fun, initial_call/1 no + longer returns the fun, but the module, function for the + local function implementing the fun, and the arity, for example, + {some_module,-work/3-fun-0-,0} (meaning that the fun was + created in function some_module:work/3). The reason is that + keeping the fun would prevent code upgrade for the module, and that + a significant amount of memory could be wasted.

+ + + + @@ -96,11 +228,12 @@ -

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

+

Spawns a new process and initializes it as described in the + beginning of this manual page. The process is spawned using the + spawn BIFs.

 + @@ -113,18 +246,19 @@ -

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

Spawns a new process and initializes it as described in the + beginning of this manual page. The process is spawned using the + spawn_link BIFs.

 + - Spawn a new process with given options. + Spawn a new process with specified options. @@ -132,17 +266,18 @@ -

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

Spawns a new process and initializes it as described in the + beginning of this manual page. 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 +

Using spawn option monitor is not + allowed. It causes the function to fail with reason badarg.

 + @@ -153,151 +288,94 @@ Start a new process synchronously.

Starts a new process synchronously. Spawns the process and - waits for it to start. When the process has started, it + waits for it to start. When the process has started, it must call - init_ack(Parent,Ret) - or init_ack(Ret), + 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 + function. At this time, Ret is returned.

+

If function start_link/3,4,5 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.

+ {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.

+

Argument SpawnOpts, if specified, is 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 +

Using spawn option monitor is not + allowed. It causes the function to fail with reason badarg.

 - - - - Used by a process when it has started. - -

This function must be 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 a crash report. - -

Equivalent to format(CrashReport, latin1).

- - - - - Format a crash report. + + Terminate a process synchronously. + -

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.

+

Equivalent to + stop(Process, normal, infinity).

 + - - Format a crash report. + + Terminate a process synchronously. + + + -

This function can be used by a user defined event handler to - format a crash report. When Depth is given as an - positive integer, it will be used in the format string to - limit the output as follows: io_lib:format("~P", - [Term,Depth]).

+

Orders the process to exit with the specified Reason and + waits for it to terminate.

+

Returns ok if the process exits with + the specified Reason within Timeout milliseconds.

+

If the call times out, a timeout exception is raised.

+

If the process does not exist, a noproc + exception is raised.

+

The implementation of this function is based on the + terminate system message, and requires that the + process handles system messages correctly. + For information about system messages, see + sys(3) and section + + sys and proc_lib in OTP Design Principles.

 - - - Extract the initial call of a proc_libspawned process. - -

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.

- -

The list Args no longer contains the actual arguments, - but the same number of atoms as the number of arguments; the first atom - is always 'Argument__1', the second 'Argument__2', and - so on. The reason is that the argument list could waste a significant - amount of memory, and if the argument list contained funs, it could - be impossible to upgrade the code for the module.

-

If the process was spawned using a fun, initial_call/1 no - longer returns the actual fun, but the module, function for the local - function implementing the fun, and the arity, for instance - {some_module,-work/3-fun-0-,0} (meaning that the fun was - created in the function some_module:work/3). - The reason is that keeping the fun would prevent code upgrade for the - module, and that a significant amount of memory could be wasted.

- - - - Extract and translate the initial call of a proc_libspawned process. + Extract and translate the initial call of a + proc_libspawned process. -

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 +

This function is used by functions + c:i/0 and + c:regs/0 + to present process information.

+

This function extracts the initial call of a process that was + started using one of the spawn or start functions in this module, + 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 +

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 + gen_server processes. To return information that this process is a supervisor and the name of the - call-back module, Module is supervisor and + callback module, Module is supervisor and Function is the name of the supervisor callback - module. Arity is 1 since the init/1 + module. Arity is 1, as 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 @@ -305,57 +383,12 @@ init(Parent) -> spawned with the proc_lib module.

 - - - Hibernate a process until a message is sent to it - -

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.

- - - - - Terminate a process synchronously. - - -

Equivalent to stop(Process, - normal, infinity).

- - - - - Terminate a process synchronously. - - - - -

Orders the process to exit with the given Reason and - waits for it to terminate.

-

The function returns ok if the process exits with - the given Reason within Timeout - milliseconds.

-

If the call times out, a timeout exception is - raised.

-

If the process does not exist, a noproc - exception is raised.

-

The implementation of this function is based on the - terminate system message, and requires that the - process handles system messages correctly. - See sys(3) - and OTP - Design Principles for information about system - messages.

- -
- SEE ALSO -

error_logger(3)

+ See Also +

+ error_logger(3)

-- cgit v1.2.3