From 88b530ea24977081020feb2123124063e58dfc12 Mon Sep 17 00:00:00 2001
From: Steve Vinoski <vinoski@ieee.org>
Date: Fri, 27 Nov 2009 12:37:13 -0500
Subject: 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.
---
 lib/stdlib/doc/src/sys.xml | 11 +++++++++++
 1 file changed, 11 insertions(+)

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

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index a395a8a415..51fd5ee8d4 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -237,6 +237,17 @@
       </type>
       <desc>
         <p>Gets the status of the process.</p>
+        <p>The value of <c>Misc</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>Misc</c> by exporting
+          a <c>format_status/2</c> function that contributes
+          module-specific information;
+          see <seealso marker="gen_server#format_status/2">gen_server:format_status/2</seealso>
+          and <seealso marker="gen_fsm#format_status/2">gen_fsm:format_status/2</seealso>
+          for more details.</p>
       </desc>
     </func>
     <func>
-- 
cgit v1.2.3