diff options
Diffstat (limited to 'lib/stdlib/doc/src/proc_lib.xml')
| -rw-r--r-- | lib/stdlib/doc/src/proc_lib.xml | 107 |
1 files changed, 65 insertions, 42 deletions
diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index cb152d1935..aeb9f48735 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2017</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>proc_lib</module> + <module since="">proc_lib</module> <modulesummary>Functions for asynchronous and synchronous start of processes adhering to the OTP design principles.</modulesummary> <description> @@ -59,18 +59,17 @@ <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 SASL - event handler. That is, the crash report is normally only visible - if the SASL application is started; see - <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso> and section + is generated, which is written to terminal by the default logger + handler setup by Kernel. For more information about how crash reports + were logged prior to Erlang/OTP 21.0, see <seealso marker="sasl:error_logging">SASL Error Logging</seealso> in the SASL User's Guide.</p> <p>Unlike in "plain Erlang", <c>proc_lib</c> processes will not generate <em>error reports</em>, which are written to the terminal by the - emulator and do not require SASL to be started. All exceptions are + emulator. All exceptions are converted to <em>exits</em> which are ignored by the default - <c>error_logger</c> handler.</p> + <c>logger</c> handler.</p> <p>The crash report contains the previously stored information, such as ancestors and initial function, the termination reason, and @@ -103,7 +102,7 @@ <funcs> <func> - <name name="format" arity="1"/> + <name name="format" arity="1" since=""/> <fsummary>Format a crash report.</fsummary> <desc> <p>Equivalent to <seealso marker="#format/2"> @@ -112,15 +111,25 @@ </func> <func> - <name name="format" arity="2"/> + <name name="format" arity="2" since="OTP R16B"/> <fsummary>Format a crash report.</fsummary> <desc> - <p>This function can be used by a user-defined event handler to + <note> + <p>This function is deprecated in the sense that + the <c>error_logger</c> is no longer the preferred + interface for logging in Erlang/OTP. A + new <seealso marker="kernel:logger_chapter">logging + API</seealso> was added in Erlang/OTP 21.0, but + legacy <c>error_logger</c> handlers can still be used. New + Logger handlers do not need to use this function, since + the formatting callback (<c>report_cb</c>) is included as + metadata in the log event.</p> + </note> + <p>This function can be used by a user-defined legacy + <c>error_logger</c> 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 + <seealso marker="kernel:logger"> + <c>logger(3)</c></seealso>, and 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 @@ -129,10 +138,22 @@ </func> <func> - <name name="format" arity="3"/> + <name name="format" arity="3" since="OTP 18.1"/> <fsummary>Format a crash report.</fsummary> <desc> - <p>This function can be used by a user-defined event handler to + <note> + <p>This function is deprecated in the sense that + the <c>error_logger</c> is no longer the preferred + interface for logging in Erlang/OTP. A + new <seealso marker="kernel:logger_chapter">logging + API</seealso> was added in Erlang/OTP 21.0, but + legacy <c>error_logger</c> handlers can still be used. New + Logger handlers do not need to used this function, since + the formatting callback (<c>report_cb</c>) is included as + metadata in the log event.</p> + </note> + <p>This function can be used by a user-defined legacy + <c>error_logger</c> 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", @@ -141,7 +162,7 @@ </func> <func> - <name name="hibernate" arity="3"/> + <name name="hibernate" arity="3" since=""/> <fsummary>Hibernate a process until a message is sent to it.</fsummary> <desc> <p>This function does the same as (and does call) the @@ -155,8 +176,8 @@ </func> <func> - <name name="init_ack" arity="1"/> - <name name="init_ack" arity="2"/> + <name name="init_ack" arity="1" since=""/> + <name name="init_ack" arity="2" since=""/> <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 @@ -193,7 +214,7 @@ init(Parent) -> </func> <func> - <name name="initial_call" arity="1"/> + <name name="initial_call" arity="1" since=""/> <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process. </fsummary> <desc> @@ -223,10 +244,10 @@ init(Parent) -> </func> <func> - <name name="spawn" arity="1"/> - <name name="spawn" arity="2"/> - <name name="spawn" arity="3"/> - <name name="spawn" arity="4"/> + <name name="spawn" arity="1" since=""/> + <name name="spawn" arity="2" since=""/> + <name name="spawn" arity="3" since=""/> + <name name="spawn" arity="4" since=""/> <fsummary>Spawn a new process.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> @@ -241,10 +262,10 @@ init(Parent) -> </func> <func> - <name name="spawn_link" arity="1"/> - <name name="spawn_link" arity="2"/> - <name name="spawn_link" arity="3"/> - <name name="spawn_link" arity="4"/> + <name name="spawn_link" arity="1" since=""/> + <name name="spawn_link" arity="2" since=""/> + <name name="spawn_link" arity="3" since=""/> + <name name="spawn_link" arity="4" since=""/> <fsummary>Spawn and link to a new process.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> @@ -260,10 +281,10 @@ init(Parent) -> </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"/> + <name name="spawn_opt" arity="2" since=""/> + <name name="spawn_opt" arity="3" since=""/> + <name name="spawn_opt" arity="4" since=""/> + <name name="spawn_opt" arity="5" since=""/> <fsummary>Spawn a new process with specified options.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> @@ -285,12 +306,12 @@ init(Parent) -> </func> <func> - <name name="start" arity="3"/> - <name name="start" arity="4"/> - <name name="start" arity="5"/> - <name name="start_link" arity="3"/> - <name name="start_link" arity="4"/> - <name name="start_link" arity="5"/> + <name name="start" arity="3" since=""/> + <name name="start" arity="4" since=""/> + <name name="start" arity="5" since=""/> + <name name="start_link" arity="3" since=""/> + <name name="start_link" arity="4" since=""/> + <name name="start_link" arity="5" since=""/> <fsummary>Start a new process synchronously.</fsummary> <desc> <p>Starts a new process synchronously. Spawns the process and @@ -320,7 +341,7 @@ init(Parent) -> </func> <func> - <name name="stop" arity="1"/> + <name name="stop" arity="1" since="OTP 18.0"/> <fsummary>Terminate a process synchronously.</fsummary> <type variable="Process"/> <desc> @@ -330,7 +351,7 @@ init(Parent) -> </func> <func> - <name name="stop" arity="3"/> + <name name="stop" arity="3" since="OTP 18.0"/> <fsummary>Terminate a process synchronously.</fsummary> <type variable="Process"/> <type variable="Reason"/> @@ -354,7 +375,7 @@ init(Parent) -> </func> <func> - <name name="translate_initial_call" arity="1"/> + <name name="translate_initial_call" arity="1" since=""/> <fsummary>Extract and translate the initial call of a <c>proc_lib</c>spawned process.</fsummary> <desc> @@ -395,6 +416,8 @@ init(Parent) -> <title>See Also</title> <p><seealso marker="kernel:error_logger"> <c>error_logger(3)</c></seealso></p> + <p><seealso marker="kernel:logger"> + <c>logger(3)</c></seealso></p> </section> </erlref> |