Merge branch 'sv/format_status_error_info' into dev

* sv/format_status_error_info:
  Add support for the format_status callback to gen_event
  Extend format_status for gen_server/gen_fsm termination error logging

OTP-8630 sv/format_status_error_info

When a gen_server, gen_fsm process, or gen_event terminates abnormally,
sometimes the text representation of the process state can occupy many
lines of the error log, depending on the definition of the state term. A
mechanism to trim out parts of the state from the log has been added (using
a format_status/2 callback). See the documentation.

3 files changed, 146 insertions, 43 deletions

diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml
index df09294de6..2234a62ac3 100644
--- a/lib/stdlib/doc/src/gen_event.xml
+++ b/lib/stdlib/doc/src/gen_event.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>gen_event</title>
@@ -630,12 +630,66 @@ gen_event:stop             ----->  Module:terminate/2
         <p>The function should return the updated internal state.</p>
       </desc>
     </func>
+    <func>
+      <name>Module:format_status(Opt, [PDict, State]) -> Status</name>
+      <fsummary>Optional function for providing a term describing the
+        current event handler state.</fsummary>
+      <type>
+        <v>Opt = normal | terminate</v>
+        <v>PDict = [{Key, Value}]</v>
+        <v>State = term()</v>
+        <v>Status = term()</v>
+      </type>
+      <desc>
+        <note>
+          <p>This callback is optional, so event handler modules need
+            not export it. If a handler does not export this function,
+            the gen_event module uses the handler state directly for
+            the purposes described below.</p>
+        </note>
+        <p>This function is called by a gen_event process when:</p>
+        <list typed="bulleted">
+          <item>One
+            of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
+            is invoked to get the gen_event status. <c>Opt</c> is set
+            to the atom <c>normal</c> for this case.</item>
+          <item>The event handler terminates abnormally and gen_event
+            logs an error. <c>Opt</c> is set to the
+            atom <c>terminate</c> for this case.</item>
+        </list>
+        <p>This function is useful for customising the form and
+          appearance of the event handler state for these cases. An
+          event handler callback module wishing to customise
+          the <c>sys:get_status/1,2</c> return value as well as how
+          its state appears in termination error logs exports an
+          instance of <c>format_status/2</c> that returns a term
+          describing the current state of the event handler.</p>
+        <p><c>PDict</c> is the current value of the gen_event's
+          process dictionary.</p>
+        <p><c>State</c> is the internal state of the event
+          handler.</p>
+        <p>The function should return <c>Status</c>, a term that
+          customises the details of the current state of the event
+          handler. Any term is allowed for <c>Status</c>. The
+          gen_event module uses <c>Status</c> as follows:</p>
+        <list typed="bulleted">
+          <item>When <c>sys:get_status/1,2</c> is called, gen_event
+            ensures that its return value contains <c>Status</c> in
+            place of the event handler's actual state term.</item>
+          <item>When an event handler terminates abnormally, gen_event
+            logs <c>Status</c> in place of the event handler's actual
+            state term.</item>
+        </list>
+        <p>One use for this function is to return compact alternative
+          state representations to avoid having large state terms
+          printed in logfiles.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>
     <title>SEE ALSO</title>
-    <p><seealso marker="supervisor">supervisor(3)</seealso>, 
+    <p><seealso marker="supervisor">supervisor(3)</seealso>,
       <seealso marker="sys">sys(3)</seealso></p>
   </section>
 </erlref>
-
diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 739cd0bffd..d15383c621 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>gen_fsm</title>
@@ -730,33 +730,58 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
       </desc>
     </func>
     <func>
-      <name>Module:format_status(normal, [PDict, StateData]) -> Status</name>
+      <name>Module:format_status(Opt, [PDict, StateData]) -> Status</name>
       <fsummary>Optional function for providing a term describing the
         current gen_fsm status.</fsummary>
       <type>
+        <v>Opt = normal | terminate</v>
         <v>PDict = [{Key, Value}]</v>
         <v>StateData = term()</v>
-        <v>Status = [term()]</v>
+        <v>Status = term()</v>
       </type>
       <desc>
-        <p><em>This callback is optional, so callback modules need not
-          export it. The gen_fsm module provides a default
-          implementation of this function that returns the callback
-          module state data.</em></p>
-        <p>This function is called by a gen_fsm process when one
-          of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
-          is invoked to get the gen_fsm status. A callback module
-          wishing to customise the <c>sys:get_status/1,2</c> return
-          value exports an instance of <c>format_status/2</c> that
-          returns a term describing the current status of the
-          gen_fsm.</p>
+        <note>
+          <p>This callback is optional, so callback modules need not
+            export it. The gen_fsm module provides a default
+            implementation of this function that returns the callback
+            module state data.</p>
+        </note>
+        <p>This function is called by a gen_fsm process when:</p>
+        <list typed="bulleted">
+          <item>One
+            of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
+            is invoked to get the gen_fsm status. <c>Opt</c> is set to
+            the atom <c>normal</c> for this case.</item>
+          <item>The gen_fsm terminates abnormally and logs an
+            error. <c>Opt</c> is set to the atom <c>terminate</c> for
+            this case.</item>
+        </list>
+        <p>This function is useful for customising the form and
+          appearance of the gen_fsm status for these cases. A callback
+          module wishing to customise the <c>sys:get_status/1,2</c>
+          return value as well as how its status appears in
+          termination error logs exports an instance
+          of <c>format_status/2</c> that returns a term describing the
+          current status of the gen_fsm.</p>
         <p><c>PDict</c> is the current value of the gen_fsm's
           process dictionary.</p>
         <p><c>StateData</c> is the internal state data of the
           gen_fsm.</p>
-        <p>The function should return <c>Status</c>, a list of one or
-          more terms that customise the details of the current state
-          and status of the gen_fsm.</p>
+        <p>The function should return <c>Status</c>, a term that
+          customises the details of the current state and status of
+          the gen_fsm. There are no restrictions on the
+          form <c>Status</c> can take, but for
+          the <c>sys:get_status/1,2</c> case (when <c>Opt</c>
+          is <c>normal</c>), the recommended form for
+          the <c>Status</c> value is <c>[{data, [{"StateData",
+          Term}]}]</c> where <c>Term</c> provides relevant details of
+          the gen_fsm state data. Following this recommendation isn't
+          required, but doing so will make the callback module status
+          consistent with the rest of the <c>sys:get_status/1,2</c>
+          return value.</p>
+        <p>One use for this function is to return compact alternative
+          state data representations to avoid having large state terms
+          printed in logfiles.</p>
       </desc>
     </func>
   </funcs>
@@ -770,4 +795,3 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
       <seealso marker="sys">sys(3)</seealso></p>
   </section>
 </erlref>
-
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 30c04d1d52..1045766e01 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>gen_server</title>
@@ -599,32 +599,57 @@ gen_server:abcast     -----> Module:handle_cast/2
       </desc>
     </func>
     <func>
-      <name>Module:format_status(normal, [PDict, State]) -> Status</name>
+      <name>Module:format_status(Opt, [PDict, State]) -> Status</name>
       <fsummary>Optional function for providing a term describing the
         current gen_server status.</fsummary>
       <type>
+        <v>Opt = normal | terminate</v>
         <v>PDict = [{Key, Value}]</v>
         <v>State = term()</v>
-        <v>Status = [term()]</v>
+        <v>Status = term()</v>
       </type>
       <desc>
-        <p><em>This callback is optional, so callback modules need not
-          export it. The gen_server module provides a default
-          implementation of this function that returns the callback
-          module state.</em></p>
-        <p>This function is called by a gen_server process when one
+        <note>
+          <p>This callback is optional, so callback modules need not
+            export it. The gen_server module provides a default
+            implementation of this function that returns the callback
+            module state.</p>
+        </note>
+        <p>This function is called by a gen_server process when:</p>
+        <list typed="bulleted">
+          <item>One
           of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
-          is invoked to get the gen_server status. A callback module
-          wishing to customise the <c>sys:get_status/1,2</c> return
-          value exports an instance of <c>format_status/2</c> that
-          returns a term describing the current status of the
-          gen_server.</p>
+          is invoked to get the gen_server status. <c>Opt</c> is set
+          to the atom <c>normal</c> for this case.</item>
+          <item>The gen_server terminates abnormally and logs an
+          error. <c>Opt</c> is set to the atom <c>terminate</c> for this
+          case.</item>
+        </list>
+        <p>This function is useful for customising the form and
+          appearance of the gen_server status for these cases. A
+          callback module wishing to customise
+          the <c>sys:get_status/1,2</c> return value as well as how
+          its status appears in termination error logs exports an
+          instance of <c>format_status/2</c> that returns a term
+          describing the current status of the gen_server.</p>
         <p><c>PDict</c> is the current value of the gen_server's
           process dictionary.</p>
         <p><c>State</c> is the internal state of the gen_server.</p>
-        <p>The function should return <c>Status</c>, a list of one or
-          more terms that customise the details of the current state
-          and status of the gen_server.</p>
+        <p>The function should return <c>Status</c>, a term that
+          customises the details of the current state and status of
+          the gen_server. There are no restrictions on the
+          form <c>Status</c> can take, but for
+          the <c>sys:get_status/1,2</c> case (when <c>Opt</c>
+          is <c>normal</c>), the recommended form for
+          the <c>Status</c> value is <c>[{data, [{"State",
+          Term}]}]</c> where <c>Term</c> provides relevant details of
+          the gen_server state. Following this recommendation isn't
+          required, but doing so will make the callback module status
+          consistent with the rest of the <c>sys:get_status/1,2</c>
+          return value.</p>
+        <p>One use for this function is to return compact alternative
+          state representations to avoid having large state terms
+          printed in logfiles.</p>
       </desc>
     </func>
   </funcs>