diff options
Diffstat (limited to 'lib/stdlib/doc/src/proc_lib.xml')
| -rw-r--r-- | lib/stdlib/doc/src/proc_lib.xml | 415 |
1 files changed, 224 insertions, 191 deletions
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 @@ <rev></rev> </header> <module>proc_lib</module> - <modulesummary>Functions for asynchronous and synchronous start of processes adhering to the OTP design principles.</modulesummary> + <modulesummary>Functions for asynchronous and synchronous start of processes + adhering to the OTP design principles.</modulesummary> <description> <p>This module is used to start processes adhering to - the <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso>. Specifically, the functions in this - module are used by the OTP standard behaviors (<c>gen_server</c>, - <c>gen_fsm</c>, <c>gen_statem</c>, ...) when starting new processes. - The functions can also be used to start <em>special processes</em>, - user defined processes which comply to the OTP design principles. See - <seealso marker="doc/design_principles:spec_proc">Sys and Proc_Lib</seealso> in OTP Design Principles for an example.</p> + the <seealso marker="doc/design_principles:des_princ"> + OTP Design Principles</seealso>. Specifically, the functions in this + module are used by the OTP standard behaviors (for example, + <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_statem</c>) + when starting new processes. The functions + can also be used to start <em>special processes</em>, user-defined + processes that comply to the OTP design principles. For an example, + see section <seealso marker="doc/design_principles:spec_proc"> + sys and proc_lib</seealso> in OTP Design Principles.</p> + + <p>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.</p> - <p>While in "plain Erlang" a process is said to terminate normally - only for the exit reason <c>normal</c>, a process started + + <p>While in "plain Erlang", a process is said to terminate normally + only for exit reason <c>normal</c>, a process started using <c>proc_lib</c> is also said to terminate normally if it exits with reason <c>shutdown</c> or <c>{shutdown,Term}</c>. <c>shutdown</c> is the reason used when an application (supervision tree) is stopped.</p> - <p>When a process started using <c>proc_lib</c> terminates - abnormally -- that is, with another exit reason than <c>normal</c>, - <c>shutdown</c>, or <c>{shutdown,Term}</c> -- a <em>crash report</em> - is generated, which is written to terminal by the default SASL + + <p>When a process that is started using <c>proc_lib</c> terminates + abnormally (that is, with another exit reason than <c>normal</c>, + <c>shutdown</c>, or <c>{shutdown,Term}</c>), a <em>crash report</em> + is generated, which is written to terminal by the default <c>SASL</c> event handler. That is, the crash report is normally only visible - if the SASL application is started. See - <seealso marker="sasl:sasl_app">sasl(6)</seealso> and - <seealso marker="sasl:error_logging">SASL User's Guide</seealso>.</p> - <p>The crash report contains the previously stored information such + if the <c>SASL</c> application is started; see + <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso> and section + <seealso marker="sasl:error_logging">SASL Error Logging</seealso> + in the SASL User's Guide.</p> + + <p>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.</p> </description> + <datatypes> <datatype> <name name="spawn_option"/> <desc> <p>See <seealso marker="erts:erlang#spawn_opt/4"> - erlang:spawn_opt/2,3,4,5</seealso>.</p> + <c>erlang:spawn_opt/2,3,4,5</c></seealso>.</p> </desc> </datatype> <datatype> @@ -83,8 +94,129 @@ <name name="dict_or_pid"/> </datatype> </datatypes> + <funcs> <func> + <name name="format" arity="1"/> + <fsummary>Format a crash report.</fsummary> + <desc> + <p>Equivalent to <seealso marker="#format/2"> + <c>format(<anno>CrashReport</anno>, latin1)</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="format" arity="2"/> + <fsummary>Format a crash report.</fsummary> + <desc> + <p>This function can be used by a user-defined event handler to + format a crash report. The crash report is sent using + <seealso marker="kernel:error_logger#error_report/2"> + <c>error_logger:error_report(crash_report, + <anno>CrashReport</anno>)</c></seealso>. + That is, the event to be handled is of the format + <c>{error_report, GL, {Pid, crash_report, + <anno>CrashReport</anno>}}</c>, + where <c>GL</c> is the group leader pid of process + <c>Pid</c> that sent the crash report.</p> + </desc> + </func> + + <func> + <name name="format" arity="3"/> + <fsummary>Format a crash report.</fsummary> + <desc> + <p>This function can be used by a user-defined event handler to + format a crash report. When <anno>Depth</anno> is specified as a + positive integer, it is used in the format string to + limit the output as follows: <c>io_lib:format("~P", + [Term,<anno>Depth</anno>])</c>.</p> + </desc> + </func> + + <func> + <name name="hibernate" arity="3"/> + <fsummary>Hibernate a process until a message is sent to it.</fsummary> + <desc> + <p>This function does the same as (and does call) the + <seealso marker="erts:erlang#erlang:hibernate/3"> + <c>hibernate/3</c></seealso> BIF, + but ensures that exception handling and logging continues to + work as expected when the process wakes up.</p> + <p>Always use this function instead of the BIF for processes started + using <c>proc_lib</c> functions.</p> + </desc> + </func> + + <func> + <name name="init_ack" arity="1"/> + <name name="init_ack" arity="2"/> + <fsummary>Used by a process when it has started.</fsummary> + <desc> + <p>This function must be used by a process that has been started by + a <seealso marker="#start/3"><c>start[_link]/3,4,5</c></seealso> + function. It tells <c><anno>Parent</anno></c> that the process has + initialized itself, has started, or has failed to initialize + itself.</p> + <p>Function <c>init_ack/1</c> uses the parent value + previously stored by the start function used.</p> + <p>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.</p> + <p>The following example illustrates how this function and + <c>proc_lib:start_link/3</c> are used:</p> + <code type="none"> +-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(). + +...</code> + </desc> + </func> + + <func> + <name name="initial_call" arity="1"/> + <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process. + </fsummary> + <desc> + <p>Extracts the initial call of a process that was started + using one of the spawn or start functions in this module. + <c><anno>Process</anno></c> can either be a pid, an integer tuple + (from which a pid can be created), or the process information of a + process <c>Pid</c> fetched through an + <c>erlang:process_info(Pid)</c> function call.</p> + <note> + <p>The list <c><anno>Args</anno></c> no longer contains the + arguments, but the same number of atoms as the number of arguments; + the first atom is <c>'Argument__1'</c>, the second + <c>'Argument__2'</c>, 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.</p> + <p>If the process was spawned using a fun, <c>initial_call/1</c> no + longer returns the fun, but the module, function for the + local function implementing the fun, and the arity, for example, + <c>{some_module,-work/3-fun-0-,0}</c> (meaning that the fun was + created in function <c>some_module:work/3</c>). The reason is that + keeping the fun would prevent code upgrade for the module, and that + a significant amount of memory could be wasted.</p> + </note> + </desc> + </func> + + <func> <name name="spawn" arity="1"/> <name name="spawn" arity="2"/> <name name="spawn" arity="3"/> @@ -96,11 +228,12 @@ <type variable="Function"/> <type variable="Args"/> <desc> - <p>Spawns a new process and initializes it as described above. - The process is spawned using the - <seealso marker="erts:erlang#spawn/1">spawn</seealso> BIFs.</p> + <p>Spawns a new process and initializes it as described in the + beginning of this manual page. The process is spawned using the + <seealso marker="erts:erlang#spawn/1"><c>spawn</c></seealso> BIFs.</p> </desc> </func> + <func> <name name="spawn_link" arity="1"/> <name name="spawn_link" arity="2"/> @@ -113,18 +246,19 @@ <type variable="Function"/> <type variable="Args"/> <desc> - <p>Spawns a new process and initializes it as described above. - The process is spawned using the - <seealso marker="erts:erlang#spawn_link/1">spawn_link</seealso> + <p>Spawns a new process and initializes it as described in the + beginning of this manual page. The process is spawned using the + <seealso marker="erts:erlang#spawn_link/1"><c>spawn_link</c></seealso> BIFs.</p> </desc> </func> + <func> <name name="spawn_opt" arity="2"/> <name name="spawn_opt" arity="3"/> <name name="spawn_opt" arity="4"/> <name name="spawn_opt" arity="5"/> - <fsummary>Spawn a new process with given options.</fsummary> + <fsummary>Spawn a new process with specified options.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> <type variable="Module"/> @@ -132,17 +266,18 @@ <type variable="Args"/> <type variable="SpawnOpts"/> <desc> - <p>Spawns a new process and initializes it as described above. - The process is spawned using the - <seealso marker="erts:erlang#spawn_opt/2">spawn_opt</seealso> + <p>Spawns a new process and initializes it as described in the + beginning of this manual page. The process is spawned using the + <seealso marker="erts:erlang#spawn_opt/2"><c>spawn_opt</c></seealso> BIFs.</p> <note> - <p>Using the spawn option <c>monitor</c> is currently not - allowed, but will cause the function to fail with reason + <p>Using spawn option <c>monitor</c> is not + allowed. It causes the function to fail with reason <c>badarg</c>.</p> </note> </desc> </func> + <func> <name name="start" arity="3"/> <name name="start" arity="4"/> @@ -153,151 +288,94 @@ <fsummary>Start a new process synchronously.</fsummary> <desc> <p>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 <em>must</em> call - <seealso marker="#init_ack/2">init_ack(Parent,Ret)</seealso> - or <seealso marker="#init_ack/1">init_ack(Ret)</seealso>, + <seealso marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seealso> + or <seealso marker="#init_ack/1"><c>init_ack(Ret)</c></seealso>, where <c>Parent</c> is the process that evaluates this - function. At this time, <c>Ret</c> is returned.</p> - <p>If the <c>start_link/3,4,5</c> function is used and + function. At this time, <c>Ret</c> is returned.</p> + <p>If function <c>start_link/3,4,5</c> is used and the process crashes before it has called <c>init_ack/1,2</c>, - <c>{error, <anno>Reason</anno>}</c> is returned if the calling process - traps exits.</p> - <p>If <c><anno>Time</anno></c> is specified as an integer, this function - waits for <c><anno>Time</anno></c> milliseconds for the new process to call - <c>init_ack</c>, or <c>{error, timeout}</c> is returned, and - the process is killed.</p> - <p>The <c><anno>SpawnOpts</anno></c> argument, if given, will be passed - as the last argument to the <c>spawn_opt/2,3,4,5</c> BIF.</p> + <c>{error, <anno>Reason</anno>}</c> is returned if the calling + process traps exits.</p> + <p>If <c><anno>Time</anno></c> is specified as an integer, this + function waits for <c><anno>Time</anno></c> milliseconds for the + new process to call <c>init_ack</c>, or <c>{error, timeout}</c> is + returned, and the process is killed.</p> + <p>Argument <c><anno>SpawnOpts</anno></c>, if specified, is passed + as the last argument to the <seealso marker="erts:erlang#spawn_opt/2"> + <c>spawn_opt/2,3,4,5</c></seealso> BIF.</p> <note> - <p>Using the spawn option <c>monitor</c> is currently not - allowed, but will cause the function to fail with reason + <p>Using spawn option <c>monitor</c> is not + allowed. It causes the function to fail with reason <c>badarg</c>.</p> </note> </desc> </func> - <func> - <name name="init_ack" arity="1"/> - <name name="init_ack" arity="2"/> - <fsummary>Used by a process when it has started.</fsummary> - <desc> - <p>This function must be used by a process that has been started by - a <seealso marker="#start/3">start[_link]/3,4,5</seealso> - function. It tells <c><anno>Parent</anno></c> that the process has - initialized itself, has started, or has failed to initialize - itself.</p> - <p>The <c>init_ack/1</c> function uses the parent value - previously stored by the start function used.</p> - <p>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.</p> - <p>The following example illustrates how this function and - <c>proc_lib:start_link/3</c> are used.</p> - <code type="none"> --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(). - -...</code> - </desc> - </func> <func> - <name name="format" arity="1"/> - <fsummary>Format a crash report.</fsummary> - <desc> - <p>Equivalent to <c>format(<anno>CrashReport</anno>, latin1)</c>.</p> - </desc> - </func> - <func> - <name name="format" arity="2"/> - <fsummary>Format a crash report.</fsummary> + <name name="stop" arity="1"/> + <fsummary>Terminate a process synchronously.</fsummary> + <type variable="Process"/> <desc> - <p>This function can be used by a user defined event handler to - format a crash report. The crash report is sent using - <c>error_logger:error_report(crash_report, <anno>CrashReport</anno>)</c>. - That is, the event to be handled is of the format - <c>{error_report, GL, {Pid, crash_report, <anno>CrashReport</anno>}}</c> - where <c>GL</c> is the group leader pid of the process - <c>Pid</c> which sent the crash report.</p> + <p>Equivalent to <seealso marker="#stop/3"> + <c>stop(Process, normal, infinity)</c></seealso>.</p> </desc> </func> + <func> - <name name="format" arity="3"/> - <fsummary>Format a crash report.</fsummary> + <name name="stop" arity="3"/> + <fsummary>Terminate a process synchronously.</fsummary> + <type variable="Process"/> + <type variable="Reason"/> + <type variable="Timeout"/> <desc> - <p>This function can be used by a user defined event handler to - format a crash report. When <anno>Depth</anno> is given as an - positive integer, it will be used in the format string to - limit the output as follows: <c>io_lib:format("~P", - [Term,<anno>Depth</anno>])</c>.</p> + <p>Orders the process to exit with the specified <c>Reason</c> and + waits for it to terminate.</p> + <p>Returns <c>ok</c> if the process exits with + the specified <c>Reason</c> within <c>Timeout</c> milliseconds.</p> + <p>If the call times out, a <c>timeout</c> exception is raised.</p> + <p>If the process does not exist, a <c>noproc</c> + exception is raised.</p> + <p>The implementation of this function is based on the + <c>terminate</c> system message, and requires that the + process handles system messages correctly. + For information about system messages, see + <seealso marker="sys"><c>sys(3)</c></seealso> and section + <seealso marker="doc/design_principles:spec_proc"> + sys and proc_lib</seealso> in OTP Design Principles.</p> </desc> </func> - <func> - <name name="initial_call" arity="1"/> - <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process.</fsummary> - <desc> - <p>Extracts the initial call of a process that was started - using one of the spawn or start functions described above. - <c><anno>Process</anno></c> can either be a pid, an integer tuple (from - which a pid can be created), or the process information of a - process <c>Pid</c> fetched through an - <c>erlang:process_info(Pid)</c> function call.</p> - - <note><p>The list <c><anno>Args</anno></c> no longer contains the actual arguments, - but the same number of atoms as the number of arguments; the first atom - is always <c>'Argument__1'</c>, the second <c>'Argument__2'</c>, 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.</p> - <p>If the process was spawned using a fun, <c>initial_call/1</c> no - longer returns the actual fun, but the module, function for the local - function implementing the fun, and the arity, for instance - <c>{some_module,-work/3-fun-0-,0}</c> (meaning that the fun was - created in the function <c>some_module:work/3</c>). - The reason is that keeping the fun would prevent code upgrade for the - module, and that a significant amount of memory could be wasted.</p> - </note> - </desc> - </func> <func> <name name="translate_initial_call" arity="1"/> - <fsummary>Extract and translate the initial call of a <c>proc_lib</c>spawned process.</fsummary> + <fsummary>Extract and translate the initial call of a + <c>proc_lib</c>spawned process.</fsummary> <desc> - <p>This function is used by the <c>c:i/0</c> and - <c>c:regs/0</c> functions in order to present process - information.</p> - <p>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. <c><anno>Process</anno></c> + <p>This function is used by functions + <seealso marker="c#i/0"><c>c:i/0</c></seealso> and + <seealso marker="c#regs/0"><c>c:regs/0</c></seealso> + to present process information.</p> + <p>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. + <c><anno>Process</anno></c> can either be a pid, an integer tuple (from which a pid can be created), or the process information of a process <c>Pid</c> fetched through an <c>erlang:process_info(Pid)</c> function call.</p> - <p>If the initial call is to one of the system defined behaviors + <p>If the initial call is to one of the system-defined behaviors such as <c>gen_server</c> or <c>gen_event</c>, it is translated to more useful information. If a <c>gen_server</c> is spawned, the returned <c><anno>Module</anno></c> is the name of the callback module and <c><anno>Function</anno></c> is <c>init</c> (the function that initiates the new server).</p> <p>A <c>supervisor</c> and a <c>supervisor_bridge</c> are also - <c>gen_server</c> processes. In order to return information + <c>gen_server</c> processes. To return information that this process is a supervisor and the name of the - call-back module, <c><anno>Module</anno></c> is <c>supervisor</c> and + callback module, <c><anno>Module</anno></c> is <c>supervisor</c> and <c><anno>Function</anno></c> is the name of the supervisor callback - module. <c><anno>Arity</anno></c> is <c>1</c> since the <c>init/1</c> + module. <c><anno>Arity</anno></c> is <c>1</c>, as the <c>init/1</c> function is called initially in the callback module.</p> <p>By default, <c>{proc_lib,init_p,5}</c> is returned if no information about the initial call can be found. It is @@ -305,57 +383,12 @@ init(Parent) -> spawned with the <c>proc_lib</c> module.</p> </desc> </func> - <func> - <name name="hibernate" arity="3"/> - <fsummary>Hibernate a process until a message is sent to it</fsummary> - <desc> - <p>This function does the same as (and does call) the BIF - <seealso marker="erts:erlang#erlang:hibernate/3">hibernate/3</seealso>, - 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 - <c>proc_lib</c> functions.</p> - </desc> - </func> - <func> - <name name="stop" arity="1"/> - <fsummary>Terminate a process synchronously.</fsummary> - <type variable="Process"/> - <desc> - <p>Equivalent to <seealso marker="#stop/3">stop(Process, - normal, infinity)</seealso>.</p> - </desc> - </func> - <func> - <name name="stop" arity="3"/> - <fsummary>Terminate a process synchronously.</fsummary> - <type variable="Process"/> - <type variable="Reason"/> - <type variable="Timeout"/> - <desc> - <p>Orders the process to exit with the given <c>Reason</c> and - waits for it to terminate.</p> - <p>The function returns <c>ok</c> if the process exits with - the given <c>Reason</c> within <c>Timeout</c> - milliseconds.</p> - <p>If the call times out, a <c>timeout</c> exception is - raised.</p> - <p>If the process does not exist, a <c>noproc</c> - exception is raised.</p> - <p>The implementation of this function is based on the - <c>terminate</c> system message, and requires that the - process handles system messages correctly. - See <seealso marker="sys">sys(3)</seealso> - and <seealso marker="doc/design_principles:spec_proc">OTP - Design Principles</seealso> for information about system - messages.</p> - </desc> - </func> </funcs> <section> - <title>SEE ALSO</title> - <p><seealso marker="kernel:error_logger">error_logger(3)</seealso></p> + <title>See Also</title> + <p><seealso marker="kernel:error_logger"> + <c>error_logger(3)</c></seealso></p> </section> </erlref> |