Merge branch 'sv/stdlib/sys-get-state/OTP-11013' into maint

* sv/stdlib/sys-get-state/OTP-11013:
  Removed ?line macro
  add sys:get_state/1,2 and sys:replace_state/2,3
  update sys:get_status/2,3 documentation for gen_event

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>