aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/gen_fsm.xml
diff options
context:
space:
mode:
authorSteve Vinoski <[email protected]>2009-11-27 12:37:13 -0500
committerSteve Vinoski <[email protected]>2009-12-01 21:31:30 -0500
commit88b530ea24977081020feb2123124063e58dfc12 (patch)
tree3e1fa8301f22328d0b1cf70edc585bfca5fd8729 /lib/stdlib/doc/src/gen_fsm.xml
parent2a9b7a1c7816812dd637933a8fbf61bed6742785 (diff)
downloadotp-88b530ea24977081020feb2123124063e58dfc12.tar.gz
otp-88b530ea24977081020feb2123124063e58dfc12.tar.bz2
otp-88b530ea24977081020feb2123124063e58dfc12.zip
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.
Diffstat (limited to 'lib/stdlib/doc/src/gen_fsm.xml')
-rw-r--r--lib/stdlib/doc/src/gen_fsm.xml30
1 files changed, 30 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index f5d8b9bb48..739cd0bffd 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -729,6 +729,36 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
updated internal data.</p>
</desc>
</func>
+ <func>
+ <name>Module:format_status(normal, [PDict, StateData]) -> Status</name>
+ <fsummary>Optional function for providing a term describing the
+ current gen_fsm status.</fsummary>
+ <type>
+ <v>PDict = [{Key, Value}]</v>
+ <v>StateData = 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>
+ <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>
+ </desc>
+ </func>
</funcs>
<section>