From 5ec0ade4105d5d72f318b657bff1a628881cbf9d Mon Sep 17 00:00:00 2001 From: Steve Vinoski 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 +++++++++++++++++++++++++++------------ lib/stdlib/doc/src/gen_server.xml | 55 +++++++++++++++++++++++++++---------- 2 files changed, 81 insertions(+), 32 deletions(-) (limited to 'lib/stdlib/doc') 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 - Module:format_status(normal, [PDict, StateData]) -> Status + Module:format_status(Opt, [PDict, StateData]) -> Status Optional function for providing a term describing the current gen_fsm status. + Opt = normal | terminate PDict = [{Key, Value}] StateData = term() - Status = [term()] + Status = term() -

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.

-

This function is called by a gen_fsm process when one - of sys:get_status/1,2 - is invoked to get the gen_fsm status. A callback module - wishing to customise the sys:get_status/1,2 return - value exports an instance of format_status/2 that - returns a term describing the current status of the - gen_fsm.

+ +

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.

+ +

This function is called by a gen_fsm process when:

+ + One + of sys:get_status/1,2 + is invoked to get the gen_fsm status. Opt is set to + the atom normal for this case. + The gen_fsm terminates abnormally and logs an + error. Opt is set to the atom terminate for + this case. + +

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 sys:get_status/1,2 + return value as well as how its status appears in + termination error logs exports an instance + of format_status/2 that returns a term describing the + current status of the gen_fsm.

PDict is the current value of the gen_fsm's process dictionary.

StateData is the internal state data of the gen_fsm.

-

The function should return Status, a list of one or - more terms that customise the details of the current state - and status of the gen_fsm.

+

The function should return Status, a term that + customises the details of the current state and status of + the gen_fsm. There are no restrictions on the + form Status can take, but for + the sys:get_status/1,2 case (when Opt + is normal), the recommended form for + the Status value is [{data, [{"StateData", + Term}]}] where Term 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 sys:get_status/1,2 + return value.

+

One use for this function is to return compact alternative + state data representations to avoid having large state terms + printed in logfiles.

 @@ -770,4 +795,3 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 sys(3)

- diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 30c04d1d52..7a4aff4b11 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -599,32 +599,57 @@ gen_server:abcast -----> Module:handle_cast/2 - Module:format_status(normal, [PDict, State]) -> Status + Module:format_status(Opt, [PDict, State]) -> Status Optional function for providing a term describing the current gen_server status. + Opt = normal | terminate PDict = [{Key, Value}] State = term() - Status = [term()] + Status = term() -

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.

-

This function is called by a gen_server process when one + +

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.

+ +

This function is called by a gen_server process when:

+ + One of sys:get_status/1,2 - is invoked to get the gen_server status. A callback module - wishing to customise the sys:get_status/1,2 return - value exports an instance of format_status/2 that - returns a term describing the current status of the - gen_server.

+ is invoked to get the gen_server status. Opt is set + to the atom normal for this case. + The gen_server terminates abnormally and logs an + error. Opt is set to the atom terminate for this + case. + +

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 sys:get_status/1,2 return value as well as how + its status appears in termination error logs exports an + instance of format_status/2 that returns a term + describing the current status of the gen_server.

PDict is the current value of the gen_server's process dictionary.

State is the internal state of the gen_server.

-

The function should return Status, a list of one or - more terms that customise the details of the current state - and status of the gen_server.

+

The function should return Status, a term that + customises the details of the current state and status of + the gen_server. There are no restrictions on the + form Status can take, but for + the sys:get_status/1,2 case (when Opt + is normal), the recommended form for + the Status value is [{data, [{"State", + Term}]}] where Term 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 sys:get_status/1,2 + return value.

+

One use for this function is to return compact alternative + state representations to avoid having large state terms + printed in logfiles.

 -- cgit v1.2.3 From 6281020ef3ac85afbfbe811de662ae5e1f19901d Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Sun, 28 Feb 2010 00:13:10 -0500 Subject: Add support for the format_status callback to gen_event The gen_server and gen_fsm behaviors support the format_status callback to allow developers to specialize how callback module state appears within the return value of sys:get_status and within logged output resulting from abnormal process termination. This patch adds similar support to gen_event. Event handlers that export a format_status/2 function, which is an optional callback, and are registered with an event manager will now have their format_status callbacks invoked when sys:get_status is called on the event manager. The term returned from format_status for this case replaces the default handler state in the sys:get_status return value. This patch also extends gen_event to call an event handler's format_status function (if it exports one) should the handler terminate abnormally. The term returned from format_status is logged in place of the handler's state. This is intended to allow developers to control how much output is logged in the case of abnormal termination. The documentation is appropriately extended and new unit tests are added to cover the new gen_event format_status functionality. --- lib/stdlib/doc/src/gen_event.xml | 58 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index df09294de6..4f4931eed0 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -630,12 +630,66 @@ gen_event:stop -----> Module:terminate/2

The function should return the updated internal state.

+ + Module:format_status(Opt, [PDict, State]) -> Status + Optional function for providing a term describing the + current event handler state. + + Opt = normal | terminate + PDict = [{Key, Value}] + State = term() + Status = term() + + + +

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.

+ +

This function is called by a gen_event process when:

+ + One + of sys:get_status/1,2 + is invoked to get the gen_event status. Opt is set + to the atom normal for this case. + The event handler terminates abnormally and gen_event + logs an error. Opt is set to the + atom terminate for this case. + +

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 sys:get_status/1,2 return value as well as how + its state appears in termination error logs exports an + instance of format_status/2 that returns a term + describing the current state of the event handler.

+

PDict is the current value of the gen_event's + process dictionary.

+

State is the internal state of the event + handler.

+

The function should return Status, a term that + customises the details of the current state of the event + handler. Any term is allowed for Status. The + gen_event module uses Status as follows:

+ + When sys:get_status/1,2 is called, gen_event + ensures that its return value contains Status in + place of the event handler's actual state term. + When an event handler terminates abnormally, gen_event + logs Status in place of the event handler's actual + state term. + +

One use for this function is to return compact alternative + state representations to avoid having large state terms + printed in logfiles.

+ +
SEE ALSO -

supervisor(3), +

supervisor(3), sys(3)

- -- cgit v1.2.3