From 5ec0ade4105d5d72f318b657bff1a628881cbf9d Mon Sep 17 00:00:00 2001
From: Steve Vinoski <vinoski@ieee.org>
Date: Sat, 27 Feb 2010 23:36:20 -0500
Subject: Extend format_status for gen_server/gen_fsm termination error logging

When a gen_server or gen_fsm process 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. Developers sometimes would like a way to trim out parts of the
state from the log if those parts don't contribute to documenting the
circumstances of the error, thereby helping to reduce the amount of
logged output.

Since the format_status callback can already format and specialize
gen_server and gen_fsm state for inclusion in the term returned from
sys:get_status, this patch extends format_status in a
backward-compatible way to also be able to specialize the state logged
for abnormal gen_server and gen_fsm termination, and includes new unit
tests to verify the new functionality.

This patch also eliminates the previous restriction that the status
returned by format_status must be a list. It can now be any term.

The documentation is extended to cover the new usage for
format_status, and it's been improved to recommend a form for the
normal case that allows the returned status to fit well with the rest
of the term returned by sys:get_status. The documentation is clear
that this form is only recommended, not required.
---
 lib/stdlib/doc/src/gen_fsm.xml | 58 +++++++++++++++++++++++++++++-------------
 1 file changed, 41 insertions(+), 17 deletions(-)

(limited to 'lib/stdlib/doc/src/gen_fsm.xml')

diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 739cd0bffd..a18d31da17 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -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>
-
-- 
cgit v1.2.3