aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/sys.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/sys.xml')
-rw-r--r--lib/stdlib/doc/src/sys.xml85
1 files changed, 77 insertions, 8 deletions
diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index 073faf2df2..a177b80739 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -211,18 +211,87 @@
<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, and a <c>gen_fsm</c> process
- returns information such as its current state name. Callback
- modules for <c>gen_server</c> and <c>gen_fsm</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>
- and <seealso marker="gen_fsm#Module:format_status/2">gen_fsm:format_status/2</seealso>
+ the callback module's state, a <c>gen_fsm</c> process
+ returns information such as its current state name and state 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>, 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>, and
+ <seealso marker="gen_event#Module:format_status/2">gen_event:format_status/2</seealso>
for more details.</p>
</desc>
</func>
<func>
+ <name name="get_state" arity="1"/>
+ <name name="get_state" arity="2"/>
+ <fsummary>Get the state of 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
+ <c><seealso marker="get_status/1">get_status/1</seealso></c> or
+ <c><seealso marker="get_status/2">get_status/2</seealso></c> 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_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>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>
+ </desc>
+ </func>
+ <func>
+ <name name="replace_state" arity="2"/>
+ <name name="replace_state" arity="3"/>
+ <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>
+ </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.
+ 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> and <c>gen_fsm</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
+ handlers registered in the same <c>gen_event</c> process.</p>
+ </desc>
+ </func>
+ <func>
<name name="install" arity="2"/>
<name name="install" arity="3"/>
<fsummary>Install a debug function in the process</fsummary>