aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/sys.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-05-18 15:53:35 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:05:57 +0200
commit68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (patch)
tree4613f513b9465beb7febec6c74c8ef0502f861fe /lib/stdlib/doc/src/sys.xml
parent99b379365981e14e2c8dde7b1a337c8ff856bd4a (diff)
downloadotp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.tar.gz
otp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.tar.bz2
otp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.zip
Update STDLIB documentation
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder.
Diffstat (limited to 'lib/stdlib/doc/src/sys.xml')
-rw-r--r--lib/stdlib/doc/src/sys.xml831
1 files changed, 505 insertions, 326 deletions
diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index 2255395f46..1120b926d5 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2016</year>
+ <year>1996</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -30,62 +30,67 @@
<checked></checked>
<date>1996-06-06</date>
<rev></rev>
- <file>sys.sgml</file>
+ <file>sys.xml</file>
</header>
<module>sys</module>
- <modulesummary>A Functional Interface to System Messages</modulesummary>
+ <modulesummary>A functional interface to system messages.</modulesummary>
<description>
- <p>This module contains functions for sending system messages used by programs, and messages used for debugging purposes.
- </p>
- <p>Functions used for implementation of processes
- should also understand system messages such as debugging
- messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviours, such as <c>gen_server</c>.</p>
- <p>The default timeout is 5000 ms, unless otherwise specified. The
- <c>timeout</c> defines the time period to wait for the process to
+ <p>This module contains functions for sending system messages used by
+ programs, and messages used for debugging purposes.</p>
+ <p>Functions used for implementation of processes are also expected to
+ understand system messages, such as debug messages and code change. These
+ functions must be used to implement the use of system messages for a
+ process; either directly, or through standard behaviors, such as
+ <seealso marker="gen_server"><c>gen_server</c></seealso>.</p>
+ <p>The default time-out is 5000 ms, unless otherwise specified.
+ <c>timeout</c> defines the time to wait for the process to
respond to a request. If the process does not respond, the
function evaluates <c>exit({timeout, {M, F, A}})</c>.
</p>
- <p><marker id="dbg_opt"/>The functions make reference to a debug structure.
- The debug structure is a list of <c>dbg_opt()</c>.
- <c>dbg_opt()</c> is an internal data type used by the
- <c>handle_system_msg/6</c> function. No debugging is performed if it is an empty list.
- </p>
+ <marker id="dbg_opt"/>
+ <p>The functions make references to a debug structure.
+ The debug structure is a list of <c>dbg_opt()</c>, which is an internal
+ data type used by function <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso>. No debugging is performed if it is
+ an empty list.</p>
</description>
<section>
<title>System Messages</title>
- <p>Processes which are not implemented as one of the standard
- behaviours must still understand system
- messages. There are three different messages which must be
- understood:
- </p>
+ <p>Processes that are not implemented as one of the standard
+ behaviors must still understand system messages. The following
+ three messages must be understood:</p>
<list type="bulleted">
<item>
<p>Plain system messages. These are received as
<c>{system, From, Msg}</c>. The content and meaning of
this message are not interpreted by the
- receiving process module. When a system message has been
- received, the function <c>sys:handle_system_msg/6</c>
- is called in order to handle the request.
- </p>
+ receiving process module. When a system message is received, function
+ <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso>
+ is called to handle the request.</p>
</item>
<item>
<p>Shutdown messages. If the process traps exits, it must
- be able to handle an shut-down request from its parent, the
+ be able to handle a shutdown request from its parent, the
supervisor. The message <c>{'EXIT', Parent, Reason}</c>
- from the parent is an order to terminate. The process must terminate when this message is received, normally with the
+ from the parent is an order to terminate. The process must
+ terminate when this message is received, normally with the
same <c>Reason</c> as <c>Parent</c>.
</p>
</item>
<item>
- <p>There is one more message which the process must understand if the modules used to implement the process change dynamically during runtime. An example of such a process is the <c>gen_event</c> processes. This message is <c>{get_modules, From}</c>. The reply to this message is <c>From ! {modules, Modules}</c>,
- where <c>Modules</c> is a list of the currently active modules in the process.
- </p>
+ <p>If the modules used to implement the process change dynamically
+ during runtime, the process must understand one more message. An
+ example is the <seealso marker="gen_event"><c>gen_event</c></seealso>
+ processes. The message is <c>{get_modules, From}</c>.
+ The reply to this message is <c>From ! {modules, Modules}</c>, where
+ <c>Modules</c> is a list of the currently active modules in the
+ process.</p>
<p>This message is used by the release handler to find which
- processes execute a certain module. The process may at a
- later time be suspended and ordered to perform a code change
- for one of its modules.
- </p>
+ processes that execute a certain module. The process can later be
+ suspended and ordered to perform a code change for one of its
+ modules.</p>
</item>
</list>
</section>
@@ -93,15 +98,16 @@
<section>
<title>System Events</title>
<p>When debugging a process with the functions of this
- module, the process generates <em>system_events</em> which are
+ module, the process generates <em>system_events</em>, which are
then treated in the debug function. For example, <c>trace</c>
- formats the system events to the tty.
+ formats the system events to the terminal.
</p>
- <p>There are three predefined system events which are used when a
+ <p>Three predefined system events are used when a
process receives or sends a message. The process can also define its
own system events. It is always up to the process itself
to format these events.</p>
</section>
+
<datatypes>
<datatype>
<name name="name"/>
@@ -111,7 +117,7 @@
</datatype>
<datatype>
<name name="dbg_opt"/>
- <desc><p>See <seealso marker="#dbg_opt">above</seealso>.</p></desc>
+ <desc><p>See the introduction of this manual page.</p></desc>
</datatype>
<datatype>
<name name="dbg_fun"/>
@@ -120,421 +126,594 @@
<name name="format_fun"/>
</datatype>
</datatypes>
+
<funcs>
<func>
- <name name="log" arity="2"/>
- <name name="log" arity="3"/>
- <fsummary>Log system events in memory</fsummary>
- <desc>
- <p>Turns the logging of system events On or Off. If On, a
- maximum of <c><anno>N</anno></c> events are kept in the
- debug structure (the default is 10). If <c><anno>Flag</anno></c> is <c>get</c>, a list of all
- logged events is returned. If <c><anno>Flag</anno></c> is <c>print</c>, the
- logged events are printed to <c>standard_io</c>. The events are
- formatted with a function that is defined by the process that
- generated the event (with a call to
- <c>sys:handle_debug/4</c>).</p>
- </desc>
- </func>
- <func>
- <name name="log_to_file" arity="2"/>
- <name name="log_to_file" arity="3"/>
- <fsummary>Log system events to the specified file</fsummary>
- <desc>
- <p>Enables or disables the logging of all system events in textual
- format to the file. The events are formatted with a function that is
- defined by the process that generated the event (with a call
- to <c>sys:handle_debug/4</c>).</p>
- </desc>
- </func>
- <func>
- <name name="statistics" arity="2"/>
- <name name="statistics" arity="3"/>
- <fsummary>Enable or disable the collections of statistics</fsummary>
+ <name name="change_code" arity="4"/>
+ <name name="change_code" arity="5"/>
+ <fsummary>Send the code change system message to the process.</fsummary>
<desc>
- <p>Enables or disables the collection of statistics. If <c><anno>Flag</anno></c> is
- <c>get</c>, the statistical collection is returned.</p>
+ <p>Tells the process to change code. The process must be
+ suspended to handle this message. Argument <c><anno>Extra</anno></c>
+ is reserved for each process to use as its own. Function
+ <c><anno>Module</anno>:system_code_change/4</c> is called.
+ <c><anno>OldVsn</anno></c> is the old version of the
+ <c><anno>Module</anno></c>.</p>
</desc>
</func>
+
<func>
- <name name="trace" arity="2"/>
- <name name="trace" arity="3"/>
- <fsummary>Print all system events on <c>standard_io</c></fsummary>
+ <name name="get_state" arity="1"/>
+ <name name="get_state" arity="2"/>
+ <fsummary>Get the state of the process.</fsummary>
<desc>
- <p>Prints all system events on <c>standard_io</c>. The events are
- formatted with a function that is defined by the process that
- generated the event (with a call to
- <c>sys:handle_debug/4</c>).</p>
+ <p>Gets the state of the process.</p>
+ <note>
+ <p>These functions are intended only to help with debugging. They are
+ provided for convenience, allowing developers to avoid having to
+ create their own state extraction functions and also avoid having
+ to interactively extract the state from the return values of
+ <seealso marker="#get_status-1"><c>get_status/1</c></seealso> or
+ <seealso marker="#get_status-2"><c>get_status/2</c></seealso>
+ while debugging.</p>
+ </note>
+ <p>The value of <c><anno>State</anno></c> varies for different types of
+ processes, as follows:</p>
+ <list type="bulleted">
+ <item>
+ <p>For a
+ <seealso marker="gen_server"><c>gen_server</c></seealso>
+ process, the returned <c><anno>State</anno></c>
+ is the state of the callback module.</p>
+ </item>
+ <item>
+ <p>For a
+ <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
+ process, <c><anno>State</anno></c> is the tuple
+ <c>{CurrentStateName, CurrentStateData}</c>.</p>
+ </item>
+ <item>
+ <p>For a
+ <seealso marker="gen_statem"><c>gen_statem</c></seealso>
+ process, <c><anno>State</anno></c> is the tuple
+ <c>{CurrentState,CurrentData}</c>.</p>
+ </item>
+ <item>
+ <p>For a
+ <seealso marker="gen_event"><c>gen_event</c></seealso>
+ process, <c><anno>State</anno></c> is a list of tuples,
+ where each tuple corresponds to an event handler registered
+ in the process and contains <c>{Module, Id, HandlerState}</c>,
+ as follows:</p>
+ <taglist>
+ <tag><c>Module</c></tag>
+ <item>
+ <p>The module name of the event handler.</p>
+ </item>
+ <tag><c>Id</c></tag>
+ <item>
+ <p>The ID of the handler (which is <c>false</c> if it was
+ registered without an ID).</p>
+ </item>
+ <tag><c>HandlerState</c></tag>
+ <item>
+ <p>The state of the handler.</p>
+ </item>
+ </taglist>
+ </item>
+ </list>
+ <p>If the callback module exports a function <c>system_get_state/1</c>,
+ it is called in the target process to get its state. Its argument is
+ the same as the <c>Misc</c> value returned by
+ <seealso marker="#get_status-1"><c>get_status/1,2</c></seealso>, and
+ function <seealso marker="#Module:system_get_state/1">
+ <c>Module:system_get_state/1</c></seealso> is expected to extract the
+ state of the callback module from it. Function
+ <c>system_get_state/1</c> must return <c>{ok, State}</c>, where
+ <c>State</c> is the state of the callback module.</p>
+ <p>If the callback module does not export a <c>system_get_state/1</c>
+ function, <c>get_state/1,2</c> assumes that the <c>Misc</c> value is
+ the state of the callback module and returns it directly instead.</p>
+ <p>If the callback module's <c>system_get_state/1</c> function crashes
+ or throws an exception, the caller exits with error
+ <c>{callback_failed, {Module, system_get_state}, {Class, Reason}}</c>,
+ where <c>Module</c> is the name of the callback module and
+ <c>Class</c> and <c>Reason</c> indicate details of the exception.</p>
+ <p>Function <c>system_get_state/1</c> is primarily useful for
+ user-defined behaviors and modules that implement OTP
+ <seealso marker="#special_process">special processes</seealso>.
+ The <c>gen_server</c>, <c>gen_fsm</c>,
+ <c>gen_statem</c>, and <c>gen_event</c> OTP
+ behavior modules export this function, so callback modules for those
+ behaviors need not to supply their own.</p>
+ <p>For more information about a process, including its state, see
+ <seealso marker="#get_status-1"><c>get_status/1</c></seealso> and
+ <seealso marker="#get_status-2"><c>get_status/2</c></seealso>.</p>
</desc>
</func>
+
<func>
- <name name="no_debug" arity="1"/>
- <name name="no_debug" arity="2"/>
- <fsummary>Turn off debugging</fsummary>
+ <name name="get_status" arity="1"/>
+ <name name="get_status" arity="2"/>
+ <fsummary>Get the status of the process.</fsummary>
<desc>
- <p>Turns off all debugging for the process. This includes
- functions that have been installed explicitly with the
- <c>install</c> function, for example triggers.</p>
+ <p>Gets the status of the process.</p>
+ <p>The value of <c><anno>Misc</anno></c> varies for different types of
+ processes, for example:</p>
+ <list type="bulleted">
+ <item>
+ <p>A <seealso marker="gen_server"><c>gen_server</c></seealso>
+ process returns the state of the callback module.</p>
+ </item>
+ <item>
+ <p>A <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
+ process returns information, such as its current
+ state name and state data.</p>
+ </item>
+ <item>
+ <p>A <seealso marker="gen_statem"><c>gen_statem</c></seealso>
+ process returns information, such as its current
+ state name and state data.</p>
+ </item>
+ <item>
+ <p>A <seealso marker="gen_event"><c>gen_event</c></seealso>
+ process returns information about each of its
+ registered handlers.</p>
+ </item>
+ </list>
+ <p>Callback modules for <c>gen_server</c>,
+ <c>gen_fsm</c>, <c>gen_statem</c>, and <c>gen_event</c>
+ can also change the value of <c><anno>Misc</anno></c>
+ by exporting a function <c>format_status/2</c>, which contributes
+ module-specific information. For details, see
+ <seealso marker="gen_server#Module:format_status/2">
+ <c>gen_server:format_status/2</c></seealso>,
+ <seealso marker="gen_fsm#Module:format_status/2">
+ <c>gen_fsm:format_status/2</c></seealso>,
+ <seealso marker="gen_statem#Module:format_status/2">
+ <c>gen_statem:format_status/2</c></seealso>, and
+ <seealso marker="gen_event#Module:format_status/2">
+ <c>gen_event:format_status/2</c></seealso>.</p>
</desc>
</func>
+
<func>
- <name name="suspend" arity="1"/>
- <name name="suspend" arity="2"/>
- <fsummary>Suspend the process</fsummary>
+ <name name="install" arity="2"/>
+ <name name="install" arity="3"/>
+ <fsummary>Install a debug function in the process.</fsummary>
<desc>
- <p>Suspends the process. When the process is suspended, it
- will only respond to other system messages, but not other
- messages.</p>
+ <p>Enables installation of alternative debug functions. An example of
+ such a function is a trigger, a function that waits for some
+ special event and performs some action when the event is
+ generated. For example, turning on low-level tracing.</p>
+ <p><c><anno>Func</anno></c> is called whenever a system event is
+ generated. This function is to return <c>done</c>, or a new
+ <c>Func</c> state. In the first case, the function is removed. It is
+ also removed if the function fails.</p>
</desc>
</func>
+
<func>
- <name name="resume" arity="1"/>
- <name name="resume" arity="2"/>
- <fsummary>Resume a suspended process</fsummary>
+ <name name="log" arity="2"/>
+ <name name="log" arity="3"/>
+ <fsummary>Log system events in memory.</fsummary>
<desc>
- <p>Resumes a suspended process.</p>
+ <p>Turns the logging of system events on or off. If on, a
+ maximum of <c><anno>N</anno></c> events are kept in the
+ debug structure (default is 10).</p>
+ <p>If <c><anno>Flag</anno></c> is <c>get</c>, a list of all logged
+ events is returned.</p>
+ <p>If <c><anno>Flag</anno></c> is <c>print</c>, the logged events
+ are printed to <c>standard_io</c>.</p>
+ <p>The events are formatted with a function that is defined by the
+ process that generated the event (with a call to
+ <seealso marker="#handle_debug/4">
+ <c>handle_debug/4</c>)</seealso>.</p>
</desc>
</func>
+
<func>
- <name name="change_code" arity="4"/>
- <name name="change_code" arity="5"/>
- <fsummary>Send the code change system message to the process</fsummary>
+ <name name="log_to_file" arity="2"/>
+ <name name="log_to_file" arity="3"/>
+ <fsummary>Log system events to the specified file.</fsummary>
<desc>
- <p>Tells the process to change code. The process must be
- suspended to handle this message. The <c><anno>Extra</anno></c> argument is
- reserved for each process to use as its own. The function
- <c><anno>Module</anno>:system_code_change/4</c> is called. <c><anno>OldVsn</anno></c> is
- the old version of the <c><anno>Module</anno></c>.</p>
+ <p>Enables or disables the logging of all system events in text
+ format to the file. The events are formatted with a function that is
+ defined by the process that generated the event (with a call to
+ <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>).
+ </p>
</desc>
</func>
+
<func>
- <name name="get_status" arity="1"/>
- <name name="get_status" arity="2"/>
- <fsummary>Get the status of the process</fsummary>
+ <name name="no_debug" arity="1"/>
+ <name name="no_debug" arity="2"/>
+ <fsummary>Turn off debugging.</fsummary>
<desc>
- <p>Gets the status of the process.</p>
- <p>The value of <c><anno>Misc</anno></c> varies for different types of
- processes. For example, a <c>gen_server</c> process returns
- the callback module's state, a <c>gen_fsm</c> process
- returns information such as its current state name and state data,
- a <c>gen_statem</c> process returns information about
- its current state and data, and a <c>gen_event</c> process
- returns information about each of its
- registered handlers. Callback modules for <c>gen_server</c>,
- <c>gen_fsm</c>, <c>gen_statem</c> and <c>gen_event</c>
- can also customise the value
- of <c><anno>Misc</anno></c> by exporting a <c>format_status/2</c>
- function that contributes module-specific information;
- see <seealso marker="gen_server#Module:format_status/2">gen_server format_status/2</seealso>,
- <seealso marker="gen_fsm#Module:format_status/2">gen_fsm format_status/2</seealso>,
- <seealso marker="gen_statem#Module:format_status/2">gen_statem format_status/2</seealso>, and
- <seealso marker="gen_event#Module:format_status/2">gen_event format_status/2</seealso>
- for more details.</p>
+ <p>Turns off all debugging for the process. This includes
+ functions that are installed explicitly with function
+ <seealso marker="#install/2"><c>install/2,3</c></seealso>,
+ for example, triggers.</p>
</desc>
</func>
+
<func>
- <name name="get_state" arity="1"/>
- <name name="get_state" arity="2"/>
- <fsummary>Get the state of the process</fsummary>
+ <name name="remove" arity="2"/>
+ <name name="remove" arity="3"/>
+ <fsummary>Remove a debug function from the process.</fsummary>
<desc>
- <p>Gets the state of the process.</p>
- <note>
- <p>These functions are intended only to help with debugging. They are provided for
- convenience, allowing developers to avoid having to create their own state extraction
- functions and also avoid having to interactively extract state from the return values of
- <seealso marker="#get_status-1"><c>get_status/1</c></seealso> or
- <seealso marker="#get_status-2"><c>get_status/2</c></seealso> while debugging.</p>
- </note>
- <p>The value of <c><anno>State</anno></c> varies for different types of
- processes. For a <c>gen_server</c> process, the returned <c><anno>State</anno></c>
- is simply the callback module's state. For a <c>gen_fsm</c> process,
- <c><anno>State</anno></c> is the tuple <c>{CurrentStateName, CurrentStateData}</c>.
- For a <c>gen_statem</c> process <c><anno>State</anno></c> is
- the tuple <c>{CurrentState,CurrentData}.</c>
- For a <c>gen_event</c> process, <c><anno>State</anno></c> a list of tuples,
- where each tuple corresponds to an event handler registered in the process and contains
- <c>{Module, Id, HandlerState}</c>, where <c>Module</c> is the event handler's module name,
- <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without
- an ID), and <c>HandlerState</c> is the handler's state.</p>
- <p>If the callback module exports a <c>system_get_state/1</c> function, it will be called in the
- target process to get its state. Its argument is the same as the <c>Misc</c> value returned by
- <seealso marker="#get_status-1">get_status/1,2</seealso>, and the <c>system_get_state/1</c>
- function is expected to extract the callback module's state from it. The <c>system_get_state/1</c>
- function must return <c>{ok, State}</c> where <c>State</c> is the callback module's state.</p>
- <p>If the callback module does not export a <c>system_get_state/1</c> function, <c>get_state/1,2</c>
- assumes the <c>Misc</c> value is the callback module's state and returns it directly instead.</p>
- <p>If the callback module's <c>system_get_state/1</c> function crashes or throws an exception, the
- caller exits with error <c>{callback_failed, {Module, system_get_state}, {Class, Reason}}</c> where
- <c>Module</c> is the name of the callback module and <c>Class</c> and <c>Reason</c> indicate
- details of the exception.</p>
- <p>The <c>system_get_state/1</c> function is primarily useful for user-defined
- behaviours and modules that implement OTP <seealso marker="#special_process">special
- processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>,
- <c>gen_statem</c> and <c>gen_event</c> OTP
- behaviour modules export this function, so callback modules for those behaviours
- need not supply their own.</p>
- <p>To obtain more information about a process, including its state, see
- <seealso marker="#get_status-1">get_status/1</seealso> and
- <seealso marker="#get_status-2">get_status/2</seealso>.</p>
+ <p>Removes an installed debug function from the
+ process. <c><anno>Func</anno></c> must be the same as previously
+ installed.</p>
</desc>
</func>
+
<func>
<name name="replace_state" arity="2"/>
<name name="replace_state" arity="3"/>
- <fsummary>Replace the state of the process</fsummary>
+ <fsummary>Replace the state of the process.</fsummary>
<desc>
<p>Replaces the state of the process, and returns the new state.</p>
<note>
- <p>These functions are intended only to help with debugging, and they should not be
- be called from normal code. They are provided for convenience, allowing developers
- to avoid having to create their own custom state replacement functions.</p>
+ <p>These functions are intended only to help with debugging, and are
+ not to be called from normal code. They are provided for
+ convenience, allowing developers to avoid having to create their own
+ custom state replacement functions.</p>
</note>
- <p>The <c><anno>StateFun</anno></c> function provides a new state for the process.
- The <c><anno>State</anno></c> argument and <c><anno>NewState</anno></c> return value
- of <c><anno>StateFun</anno></c> vary for different types of processes. For a
- <c>gen_server</c> process, <c><anno>State</anno></c> is simply the callback module's
- state, and <c><anno>NewState</anno></c> is a new instance of that state. For a
- <c>gen_fsm</c> process, <c><anno>State</anno></c> is the tuple
- <c>{CurrentStateName, CurrentStateData}</c>, and <c><anno>NewState</anno></c>
- is a similar tuple that may contain a new state name, new state data, or both.
- The same applies for a <c>gen_statem</c> process but
- it names the tuple fields <c>{CurrentState,CurrentData}</c>.
- For a <c>gen_event</c> process, <c><anno>State</anno></c> is the tuple
- <c>{Module, Id, HandlerState}</c> where <c>Module</c> is the event handler's module name,
- <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without
- an ID), and <c>HandlerState</c> is the handler's state. <c><anno>NewState</anno></c> is a
- similar tuple where <c>Module</c> and <c>Id</c> shall have the same values as in
- <c><anno>State</anno></c> but the value of <c>HandlerState</c> may be different. Returning
- a <c><anno>NewState</anno></c> whose <c>Module</c> or <c>Id</c> values differ from those of
- <c><anno>State</anno></c> will result in the event handler's state remaining unchanged. For a
- <c>gen_event</c> process, <c><anno>StateFun</anno></c> is called once for each event handler
- registered in the <c>gen_event</c> process.</p>
- <p>If a <c><anno>StateFun</anno></c> function decides not to effect any change in process
- state, then regardless of process type, it may simply return its <c><anno>State</anno></c>
- argument.</p>
- <p>If a <c><anno>StateFun</anno></c> function crashes or throws an exception, then
- for <c>gen_server</c>, <c>gen_fsm</c> or <c>gen_statem</c> processes,
- the original state of the process is
- unchanged. For <c>gen_event</c> processes, a crashing or failing <c><anno>StateFun</anno></c>
- function means that only the state of the particular event handler it was working on when it
- failed or crashed is unchanged; it can still succeed in changing the states of other event
+ <p>Function <c><anno>StateFun</anno></c> provides a new state for the
+ process. Argument <c><anno>State</anno></c> and the
+ <c><anno>NewState</anno></c> return value of
+ <c><anno>StateFun</anno></c> vary for different types of
+ processes as follows:</p>
+ <list type="bulleted">
+ <item>
+ <p>For a <seealso marker="gen_server"><c>gen_server</c></seealso>
+ process, <c><anno>State</anno></c> is the state of the callback
+ module and <c><anno>NewState</anno></c>
+ is a new instance of that state.</p>
+ </item>
+ <item>
+ <p>For a <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> process,
+ <c><anno>State</anno></c> is the tuple <c>{CurrentStateName,
+ CurrentStateData}</c>, and <c><anno>NewState</anno></c> is a
+ similar tuple, which can contain
+ a new state name, new state data, or both.</p>
+ </item>
+ <item>
+ <p>For a <seealso marker="gen_statem"><c>gen_statem</c></seealso>
+ process, <c><anno>State</anno></c> is the
+ tuple <c>{CurrentState,CurrentData}</c>,
+ and <c><anno>NewState</anno></c> is a
+ similar tuple, which can contain
+ a new current state, new state data, or both.</p>
+ </item>
+ <item>
+ <p>For a <seealso marker="gen_event"><c>gen_event</c></seealso>
+ process, <c><anno>State</anno></c> is the
+ tuple <c>{Module, Id, HandlerState}</c> as follows:</p>
+ <taglist>
+ <tag><c>Module</c></tag>
+ <item>
+ <p>The module name of the event handler.</p>
+ </item>
+ <tag><c>Id</c></tag>
+ <item>
+ <p>The ID of the handler (which is <c>false</c> if it was
+ registered without an ID).</p>
+ </item>
+ <tag><c>HandlerState</c></tag>
+ <item>
+ <p>The state of the handler.</p>
+ </item>
+ </taglist>
+ <p><c><anno>NewState</anno></c> is a similar tuple where
+ <c>Module</c> and <c>Id</c> are to have the same values as in
+ <c><anno>State</anno></c>, but the value of <c>HandlerState</c>
+ can be different. Returning a <c><anno>NewState</anno></c>, whose
+ <c>Module</c> or <c>Id</c> values differ from those of
+ <c><anno>State</anno></c>, leaves the state of the event handler
+ unchanged. For a <c>gen_event</c> process,
+ <c><anno>StateFun</anno></c> is called once for each event handler
+ registered in the <c>gen_event</c> process.</p>
+ </item>
+ </list>
+ <p>If a <c><anno>StateFun</anno></c> function decides not to effect any
+ change in process state, then regardless of process type, it can
+ return its <c><anno>State</anno></c> argument.</p>
+ <p>If a <c><anno>StateFun</anno></c> function crashes or throws an
+ exception, the original state of the process is unchanged for
+ <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_statem</c> processes.
+ For <c>gen_event</c> processes, a crashing or
+ failing <c><anno>StateFun</anno></c> function
+ means that only the state of the particular event handler it was
+ working on when it failed or crashed is unchanged; it can still
+ succeed in changing the states of other event
handlers registered in the same <c>gen_event</c> process.</p>
- <p>If the callback module exports a <c>system_replace_state/2</c> function, it will be called in the
- target process to replace its state using <c>StateFun</c>. Its two arguments are <c>StateFun</c>
- and <c>Misc</c>, where <c>Misc</c> is the same as the <c>Misc</c> value returned by
- <seealso marker="#get_status-1">get_status/1,2</seealso>. A <c>system_replace_state/2</c> function
- is expected to return <c>{ok, NewState, NewMisc}</c> where <c>NewState</c> is the callback module's
- new state obtained by calling <c>StateFun</c>, and <c>NewMisc</c> is a possibly new value used to
- replace the original <c>Misc</c> (required since <c>Misc</c> often contains the callback
- module's state within it).</p>
- <p>If the callback module does not export a <c>system_replace_state/2</c> function,
- <c>replace_state/2,3</c> assumes the <c>Misc</c> value is the callback module's state, passes it
- to <c>StateFun</c> and uses the return value as both the new state and as the new value of
- <c>Misc</c>.</p>
- <p>If the callback module's <c>system_replace_state/2</c> function crashes or throws an exception,
- the caller exits with error <c>{callback_failed, {Module, system_replace_state}, {Class, Reason}}</c>
- where <c>Module</c> is the name of the callback module and <c>Class</c> and <c>Reason</c> indicate details
- of the exception. If the callback module does not provide a <c>system_replace_state/2</c> function and
- <c>StateFun</c> crashes or throws an exception, the caller exits with error
+ <p>If the callback module exports a
+ <seealso marker="#Module:system_replace_state/2">
+ <c>system_replace_state/2</c></seealso> function, it is called in the
+ target process to replace its state using <c>StateFun</c>. Its two
+ arguments are <c>StateFun</c> and <c>Misc</c>, where
+ <c>Misc</c> is the same as the <c>Misc</c> value returned by
+ <seealso marker="#get_status-1"><c>get_status/1,2</c></seealso>.
+ A <c>system_replace_state/2</c> function is expected to return
+ <c>{ok, NewState, NewMisc}</c>, where <c>NewState</c> is the new state
+ of the callback module, obtained by calling <c>StateFun</c>, and
+ <c>NewMisc</c> is
+ a possibly new value used to replace the original <c>Misc</c>
+ (required as <c>Misc</c> often contains the state of the callback
+ module within it).</p>
+ <p>If the callback module does not export a
+ <c>system_replace_state/2</c> function,
+ <seealso marker="#replace_state/2"><c>replace_state/2,3</c></seealso>
+ assumes that <c>Misc</c> is the state of the callback module,
+ passes it to <c>StateFun</c> and uses the return value as
+ both the new state and as the new value of <c>Misc</c>.</p>
+ <p>If the callback module's function <c>system_replace_state/2</c>
+ crashes or throws an exception, the caller exits with error
+ <c>{callback_failed, {Module, system_replace_state}, {Class,
+ Reason}}</c>, where <c>Module</c> is the name of the callback module
+ and <c>Class</c> and <c>Reason</c> indicate details of the exception.
+ If the callback module does not provide a
+ <c>system_replace_state/2</c> function and <c>StateFun</c> crashes or
+ throws an exception, the caller exits with error
<c>{callback_failed, StateFun, {Class, Reason}}</c>.</p>
- <p>The <c>system_replace_state/2</c> function is primarily useful for user-defined behaviours and
- modules that implement OTP <seealso marker="#special_process">special processes</seealso>. The
- <c>gen_server</c>, <c>gen_fsm</c>, <c>gen_statem</c> and
- <c>gen_event</c> OTP behaviour modules export this function,
- and so callback modules for those behaviours need not supply their own.</p>
+ <p>Function <c>system_replace_state/2</c> is primarily useful for
+ user-defined behaviors and modules that implement OTP
+ <seealso marker="#special_process">special processes</seealso>. The
+ OTP behavior modules <c>gen_server</c>,
+ <c>gen_fsm</c>, <c>gen_statem</c>, and <c>gen_event</c>
+ export this function, so callback modules for those
+ behaviors need not to supply their own.</p>
</desc>
</func>
+
<func>
- <name name="install" arity="2"/>
- <name name="install" arity="3"/>
- <fsummary>Install a debug function in the process</fsummary>
+ <name name="resume" arity="1"/>
+ <name name="resume" arity="2"/>
+ <fsummary>Resume a suspended process.</fsummary>
<desc>
- <p>This function makes it possible to install other debug
- functions than the ones defined above. An example of such a
- function is a trigger, a function that waits for some
- special event and performs some action when the event is
- generated. This could, for example, be turning on low level tracing.
- </p>
- <p><c><anno>Func</anno></c> is called whenever a system event is
- generated. This function should return <c>done</c>, or a new
- func state. In the first case, the function is removed. It is removed
- if the function fails.</p>
+ <p>Resumes a suspended process.</p>
</desc>
</func>
+
<func>
- <name name="remove" arity="2"/>
- <name name="remove" arity="3"/>
- <fsummary>Remove a debug function from the process</fsummary>
+ <name name="statistics" arity="2"/>
+ <name name="statistics" arity="3"/>
+ <fsummary>Enable or disable the collections of statistics.</fsummary>
<desc>
- <p>Removes a previously installed debug function from the
- process. <c><anno>Func</anno></c> must be the same as previously
- installed.</p>
+ <p>Enables or disables the collection of statistics. If
+ <c><anno>Flag</anno></c> is <c>get</c>,
+ the statistical collection is returned.</p>
</desc>
</func>
+
+ <func>
+ <name name="suspend" arity="1"/>
+ <name name="suspend" arity="2"/>
+ <fsummary>Suspend the process.</fsummary>
+ <desc>
+ <p>Suspends the process. When the process is suspended, it
+ only responds to other system messages, but not other
+ messages.</p>
+ </desc>
+ </func>
+
<func>
<name name="terminate" arity="2"/>
<name name="terminate" arity="3"/>
- <fsummary>Terminate the process</fsummary>
+ <fsummary>Terminate the process.</fsummary>
<desc>
- <p>This function orders the process to terminate with the
- given <c><anno>Reason</anno></c>. The termination is done
- asynchronously, so there is no guarantee that the process is
- actually terminated when the function returns.</p>
+ <p>Orders the process to terminate with the
+ specified <c><anno>Reason</anno></c>. The termination is done
+ asynchronously, so it is not guaranteed that the process is
+ terminated when the function returns.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="trace" arity="2"/>
+ <name name="trace" arity="3"/>
+ <fsummary>Print all system events on <c>standard_io</c>.</fsummary>
+ <desc>
+ <p>Prints all system events on <c>standard_io</c>. The events are
+ formatted with a function that is defined by the process that
+ generated the event (with a call to
+ <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>).
+ </p>
</desc>
</func>
</funcs>
<section>
<title>Process Implementation Functions</title>
- <p><marker id="special_process"/>The following functions are used when implementing a
- special process. This is an ordinary process which does not use a
- standard behaviour, but a process which understands the standard system messages.</p>
+ <marker id="special_process"/>
+ <p>The following functions are used when implementing a
+ special process. This is an ordinary process, which does not use a
+ standard behavior, but a process that understands the standard system
+ messages.</p>
</section>
+
<funcs>
<func>
<name name="debug_options" arity="1"/>
- <fsummary>Convert a list of options to a debug structure</fsummary>
+ <fsummary>Convert a list of options to a debug structure.</fsummary>
<desc>
- <p>This function can be used by a process that initiates a debug
- structure from a list of options. The values of the
- <c><anno>Opt</anno></c> argument are the same as the corresponding
+ <p>Can be used by a process that initiates a debug
+ structure from a list of options. The values of argument
+ <c><anno>Opt</anno></c> are the same as for the corresponding
functions.</p>
</desc>
</func>
+
<func>
<name name="get_debug" arity="3"/>
- <fsummary>Get the data associated with a debug option</fsummary>
+ <fsummary>Get the data associated with a debug option.</fsummary>
<desc>
- <p>This function gets the data associated with a debug option. <c><anno>Default</anno></c> is returned if the
- <c><anno>Item</anno></c> is not found. Can be
- used by the process to retrieve debug data for printing
- before it terminates.</p>
+ <p>Gets the data associated with a debug option.
+ <c><anno>Default</anno></c>
+ is returned if <c><anno>Item</anno></c> is not found. Can be
+ used by the process to retrieve debug data for printing before it
+ terminates.</p>
</desc>
</func>
+
<func>
<name name="handle_debug" arity="4"/>
- <fsummary>Generate a system event</fsummary>
+ <fsummary>Generate a system event.</fsummary>
<desc>
<p>This function is called by a process when it generates a
- system event. <c><anno>FormFunc</anno></c> is a formatting
- function which is called as <c><anno>FormFunc</anno>(Device,
- <anno>Event</anno>, <anno>Extra</anno>)</c> in order to print
- the events, which is necessary if tracing is activated.
- <c><anno>Extra</anno></c> is any extra information which the
- process needs in the format function, for example the name
- of the process.</p>
+ system event. <c><anno>FormFunc</anno></c> is a formatting
+ function, called as <c><anno>FormFunc</anno>(Device,
+ <anno>Event</anno>, <anno>Extra</anno>)</c> to print the events,
+ which is necessary if tracing is activated.
+ <c><anno>Extra</anno></c> is any extra information that the
+ process needs in the format function, for example, the process
+ name.</p>
</desc>
</func>
+
<func>
<name name="handle_system_msg" arity="6"/>
- <fsummary>Take care of system messages</fsummary>
+ <fsummary>Take care of system messages.</fsummary>
<desc>
- <p>This function is used by a process module that wishes to take care of system
- messages. The process receives a <c>{system, <anno>From</anno>, <anno>Msg</anno>}</c>
- message and passes the <c><anno>Msg</anno></c> and <c><anno>From</anno></c> to this
- function.
- </p>
- <p>This function <em>never</em> returns. It calls the function
- <c><anno>Module</anno>:system_continue(<anno>Parent</anno>, NDebug, <anno>Misc</anno>)</c> where the
- process continues the execution, or
- <c><anno>Module</anno>:system_terminate(Reason, <anno>Parent</anno>, <anno>Debug</anno>, <anno>Misc</anno>)</c> if
- the process should terminate. The <c><anno>Module</anno></c> must export
- <c>system_continue/3</c>, <c>system_terminate/4</c>,
- <c>system_code_change/4</c>, <c>system_get_state/1</c> and
- <c>system_replace_state/2</c> (see below).
- </p>
- <p>The <c><anno>Misc</anno></c> argument can be used to save internal data
- in a process, for example its state. It is sent to
+ <p>This function is used by a process module to take care of system
+ messages. The process receives a
+ <c>{system, <anno>From</anno>, <anno>Msg</anno>}</c> message and
+ passes <c><anno>Msg</anno></c> and <c><anno>From</anno></c> to this
+ function.</p>
+ <p>This function <em>never</em> returns. It calls either of the
+ following functions:</p>
+ <list type="bulleted">
+ <item>
+ <p><c><anno>Module</anno>:system_continue(<anno>Parent</anno>,
+ NDebug, <anno>Misc</anno>)</c>,
+ where the process continues the execution.</p>
+ </item>
+ <item>
+ <p><c><anno>Module</anno>:system_terminate(Reason,
+ <anno>Parent</anno>, <anno>Debug</anno>, <anno>Misc</anno>)</c>,
+ if the process is to terminate.</p>
+ </item>
+ </list>
+ <p><c><anno>Module</anno></c> must export the following:</p>
+ <list type="bulleted">
+ <item><c>system_continue/3</c></item>
+ <item><c>system_terminate/4</c></item>
+ <item><c>system_code_change/4</c></item>
+ <item><c>system_get_state/1</c></item>
+ <item><c>system_replace_state/2</c></item>
+ </list>
+ <p>Argument <c><anno>Misc</anno></c> can be used to save internal data
+ in a process, for example, its state. It is sent to
<c><anno>Module</anno>:system_continue/3</c> or
- <c><anno>Module</anno>:system_terminate/4</c></p>
+ <c><anno>Module</anno>:system_terminate/4</c>.</p>
</desc>
</func>
+
<func>
<name name="print_log" arity="1"/>
- <fsummary>Print the logged events in the debug structure</fsummary>
+ <fsummary>Print the logged events in the debug structure.</fsummary>
<desc>
- <p>Prints the logged system events in the debug structure
+ <p>Prints the logged system events in the debug structure,
using <c>FormFunc</c> as defined when the event was
- generated by a call to <c>handle_debug/4</c>.</p>
+ generated by a call to
+ <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>.</p>
</desc>
</func>
+
<func>
- <name>Mod:system_continue(Parent, Debug, Misc) -> none()</name>
- <fsummary>Called when the process should continue its execution</fsummary>
+ <name>Module:system_code_change(Misc, Module, OldVsn, Extra) ->
+ {ok, NMisc}</name>
+ <fsummary>Called when the process is to perform a code change.</fsummary>
<type>
- <v>Parent = pid()</v>
- <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
<v>Misc = term()</v>
+ <v>OldVsn = undefined | term()</v>
+ <v>Module = atom()</v>
+ <v>Extra = term()</v>
+ <v>NMisc = term()</v>
</type>
<desc>
- <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
- should continue its execution (for example after it has been
- suspended). This function never returns.</p>
+ <p>Called from <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso> when the process is to perform a
+ code change. The code change is used when the
+ internal data structure has changed. This function
+ converts argument <c>Misc</c> to the new data
+ structure. <c>OldVsn</c> is attribute <em>vsn</em> of the
+ old version of the <c>Module</c>. If no such attribute is
+ defined, the atom <c>undefined</c> is sent.</p>
</desc>
</func>
+
<func>
- <name>Mod:system_terminate(Reason, Parent, Debug, Misc) -> none()</name>
- <fsummary>Called when the process should terminate</fsummary>
+ <name>Module:system_continue(Parent, Debug, Misc) -> none()</name>
+ <fsummary>Called when the process is to continue its execution.</fsummary>
<type>
- <v>Reason = term()</v>
<v>Parent = pid()</v>
<v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
<v>Misc = term()</v>
</type>
<desc>
- <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
- should terminate. For example, this function is called when
- the process is suspended and its parent orders shut-down.
- It gives the process a chance to do a clean-up. This function never
- returns.</p>
+ <p>Called from <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso> when the process is to continue
+ its execution (for example, after it has been
+ suspended). This function never returns.</p>
</desc>
</func>
+
<func>
- <name>Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name>
- <fsummary>Called when the process should perform a code change</fsummary>
+ <name>Module:system_get_state(Misc) -> {ok, State}</name>
+ <fsummary>Called when the process is to return its current state.
+ </fsummary>
<type>
<v>Misc = term()</v>
- <v>OldVsn = undefined | term()</v>
- <v>Module = atom()</v>
- <v>Extra = term()</v>
- <v>NMisc = term()</v>
+ <v>State = term()</v>
</type>
<desc>
- <p>Called from <c>sys:handle_system_msg/6</c> when the process
- should perform a code change. The code change is used when the
- internal data structure has changed. This function
- converts the <c>Misc</c> argument to the new data
- structure. <c>OldVsn</c> is the <em>vsn</em> attribute of the
- old version of the <c>Module</c>. If no such attribute was
- defined, the atom <c>undefined</c> is sent.</p>
+ <p>Called from <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso>
+ when the process is to return a term that reflects its current state.
+ <c>State</c> is the value returned by
+ <seealso marker="#get_state/2"><c>get_state/2</c></seealso>.</p>
</desc>
</func>
+
<func>
- <name>Mod:system_get_state(Misc) -> {ok, State}</name>
- <fsummary>Called when the process should return its current state</fsummary>
+ <name>Module:system_replace_state(StateFun, Misc) ->
+ {ok, NState, NMisc}</name>
+ <fsummary>Called when the process is to replace its current state.
+ </fsummary>
<type>
+ <v>StateFun = fun((State :: term()) -> NState)</v>
<v>Misc = term()</v>
- <v>State = term()</v>
- </type>
+ <v>NState = term()</v>
+ <v>NMisc = term()</v>
+ </type>
<desc>
- <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
- should return a term that reflects its current state. <c>State</c> is the
- value returned by <c>sys:get_state/2</c>.</p>
+ <p>Called from <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso> when the process is to replace
+ its current state. <c>NState</c> is the value returned by
+ <seealso marker="#replace_state/3"><c>replace_state/3</c></seealso>.
+ </p>
</desc>
</func>
+
<func>
- <name>Mod:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}</name>
- <fsummary>Called when the process should replace its current state</fsummary>
+ <name>Module:system_terminate(Reason, Parent, Debug, Misc) -> none()</name>
+ <fsummary>Called when the process is to terminate.</fsummary>
<type>
- <v>StateFun = fun((State :: term()) -> NState)</v>
+ <v>Reason = term()</v>
+ <v>Parent = pid()</v>
+ <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
<v>Misc = term()</v>
- <v>NState = term()</v>
- <v>NMisc = term()</v>
- </type>
+ </type>
<desc>
- <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
- should replace its current state. <c>NState</c> is the value returned by
- <c>sys:replace_state/3</c>.</p>
+ <p>Called from <seealso marker="#handle_system_msg/6">
+ <c>handle_system_msg/6</c></seealso> when the process is to terminate.
+ For example, this function is called when
+ the process is suspended and its parent orders shutdown.
+ It gives the process a chance to do a cleanup. This function never
+ returns.</p>
</desc>
</func>
</funcs>