Teach sys:get_status/1,2 to call Mod:format_status/2

Restore the ability for gen_server and gen_fsm callback
modules to format their own state for display under the
sys:get_status/1,2 calls.

This ability is extremely useful for new behavior modules
based on gen_server or gen_fsm, so that they can display
their status in a more meaningful way than just dumping
the state record. It is also generally useful for applications
wanting to display their gen_server or gen_fsm callback module
state in something other than the default manner.

Also document the previously undocumented the
gen_server:format_status/2 and gen_fsm:format_status/2 optional
callback functions that, if exported by the callback module, are
invoked when sys:get_status/1,2 are called.

Add unit tests to ensure that format_status/2 functions exported
from a gen_fsm callback module and a gen_server callback module
are called when sys:get_status/1,2 are called.

1 files changed, 29 insertions, 0 deletions

diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 8496802259..30c04d1d52 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -598,6 +598,35 @@ gen_server:abcast     -----> Module:handle_cast/2
         <p>The function should return the updated internal state.</p>
       </desc>
     </func>
+    <func>
+      <name>Module:format_status(normal, [PDict, State]) -> Status</name>
+      <fsummary>Optional function for providing a term describing the
+        current gen_server status.</fsummary>
+      <type>
+        <v>PDict = [{Key, Value}]</v>
+        <v>State = 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
+          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>
+        <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>
+      </desc>
+    </func>
   </funcs>
 
   <section>