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.

4 files changed, 141 insertions, 10 deletions

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
         <p>The function should return the updated internal state.</p>
       </desc>
     </func>
+    <func>
+      <name>Module:format_status(Opt, [PDict, State]) -> Status</name>
+      <fsummary>Optional function for providing a term describing the
+        current event handler state.</fsummary>
+      <type>
+        <v>Opt = normal | terminate</v>
+        <v>PDict = [{Key, Value}]</v>
+        <v>State = term()</v>
+        <v>Status = term()</v>
+      </type>
+      <desc>
+        <note>
+          <p>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.</p>
+        </note>
+        <p>This function is called by a gen_event 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_event status. <c>Opt</c> is set
+            to the atom <c>normal</c> for this case.</item>
+          <item>The event handler terminates abnormally and gen_event
+            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 event handler state for these cases. An
+          event handler callback module wishing to customise
+          the <c>sys:get_status/1,2</c> return value as well as how
+          its state appears in termination error logs exports an
+          instance of <c>format_status/2</c> that returns a term
+          describing the current state of the event handler.</p>
+        <p><c>PDict</c> is the current value of the gen_event's
+          process dictionary.</p>
+        <p><c>State</c> is the internal state of the event
+          handler.</p>
+        <p>The function should return <c>Status</c>, a term that
+          customises the details of the current state of the event
+          handler. Any term is allowed for <c>Status</c>. The
+          gen_event module uses <c>Status</c> as follows:</p>
+        <list typed="bulleted">
+          <item>When <c>sys:get_status/1,2</c> is called, gen_event
+            ensures that its return value contains <c>Status</c> in
+            place of the event handler's actual state term.</item>
+          <item>When an event handler terminates abnormally, gen_event
+            logs <c>Status</c> in place of the event handler's actual
+            state term.</item>
+        </list>
+        <p>One use for this function is to return compact alternative
+          state representations to avoid having large state terms
+          printed in logfiles.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>
     <title>SEE ALSO</title>
-    <p><seealso marker="supervisor">supervisor(3)</seealso>, 
+    <p><seealso marker="supervisor">supervisor(3)</seealso>,
       <seealso marker="sys">sys(3)</seealso></p>
   </section>
 </erlref>
-
diff --git a/lib/stdlib/src/gen_event.erl b/lib/stdlib/src/gen_event.erl
index 27ff9441e6..b1e9e3a02f 100644
--- a/lib/stdlib/src/gen_event.erl
+++ b/lib/stdlib/src/gen_event.erl
@@ -677,12 +677,23 @@ report_error(Handler, Reason, State, LastIn, SName) ->
 	    _ ->
 		Reason
 	end,
+    Mod = Handler#handler.module,
+    FmtState = case erlang:function_exported(Mod, format_status, 2) of
+		   true ->
+		       Args = [get(), State],
+		       case catch Mod:format_status(terminate, Args) of
+			   {'EXIT', _} -> State;
+			   Else -> Else
+		       end;
+		   _ ->
+		       State
+	       end,
     error_msg("** gen_event handler ~p crashed.~n"
 	      "** Was installed in ~p~n"
 	      "** Last event was: ~p~n"
 	      "** When handler state == ~p~n"
 	      "** Reason == ~p~n",
-	      [handler(Handler),SName,LastIn,State,Reason1]).
+	      [handler(Handler),SName,LastIn,FmtState,Reason1]).
 
 handler(Handler) when not Handler#handler.id ->
     Handler#handler.module;
@@ -711,10 +722,20 @@ get_modules(MSL) ->
 %%-----------------------------------------------------------------
 %% Status information
 %%-----------------------------------------------------------------
-format_status(_Opt, StatusData) ->
-    [_PDict, SysState, Parent, _Debug, [ServerName, MSL, _Hib]] = StatusData,
+format_status(Opt, StatusData) ->
+    [PDict, SysState, Parent, _Debug, [ServerName, MSL, _Hib]] = StatusData,
     Header = lists:concat(["Status for event handler ", ServerName]),
+    FmtMSL = [case erlang:function_exported(Mod, format_status, 2) of
+		  true ->
+		      Args = [PDict, State],
+		      case catch Mod:format_status(Opt, Args) of
+			  {'EXIT', _} -> MSL;
+			  Else -> MS#handler{state = Else}
+		      end;
+		  _ ->
+		      MS
+	      end || #handler{module = Mod, state = State} = MS <- MSL],
     [{header, Header},
      {data, [{"Status", SysState},
 	     {"Parent", Parent}]},
-     {items, {"Installed handlers", MSL}}].
+     {items, {"Installed handlers", FmtMSL}}].
diff --git a/lib/stdlib/test/dummy1_h.erl b/lib/stdlib/test/dummy1_h.erl
index 4377d774a3..8bbe729646 100644
--- a/lib/stdlib/test/dummy1_h.erl
+++ b/lib/stdlib/test/dummy1_h.erl
@@ -21,7 +21,7 @@
 %% Test event handler for gen_event_SUITE.erl
 
 -export([init/1, handle_event/2, handle_call/2, handle_info/2,
-	 terminate/2]).
+	 terminate/2, format_status/2]).
 
 init(make_error) ->
     {error, my_error};
@@ -67,4 +67,5 @@ terminate(remove_handler, Parent) ->
 terminate(_Reason, _State) ->
     ok.
 
-
+format_status(_Opt, [_PDict, _State]) ->
+    "dummy1_h handler state".
diff --git a/lib/stdlib/test/gen_event_SUITE.erl b/lib/stdlib/test/gen_event_SUITE.erl
index 8cbffaca56..4f7de451e3 100644
--- a/lib/stdlib/test/gen_event_SUITE.erl
+++ b/lib/stdlib/test/gen_event_SUITE.erl
@@ -23,9 +23,11 @@
 -export([all/1]).
 -export([start/1, test_all/1, add_handler/1, add_sup_handler/1,
 	 delete_handler/1, swap_handler/1, swap_sup_handler/1,
-	 notify/1, sync_notify/1, call/1, info/1, hibernate/1]).
+	 notify/1, sync_notify/1, call/1, info/1, hibernate/1,
+	 call_format_status/1, error_format_status/1]).
 
-all(suite) -> {req, [stdlib], [start, test_all, hibernate]}.
+all(suite) -> {req, [stdlib], [start, test_all, hibernate,
+			       call_format_status, error_format_status]}.
 
 %% --------------------------------------
 %% Start an event manager.
@@ -844,3 +846,56 @@ info(Config) when is_list(Config) ->
 
     ?line ok = gen_event:stop(my_dummy_handler),
     ok.
+
+call_format_status(suite) ->
+    [];
+call_format_status(doc) ->
+    ["Test that sys:get_status/1,2 calls format_status/2"];
+call_format_status(Config) when is_list(Config) ->
+    ?line {ok, Pid} = gen_event:start({local, my_dummy_handler}),
+    %% State here intentionally differs from what we expect from format_status
+    State = self(),
+    FmtState = "dummy1_h handler state",
+    ?line ok = gen_event:add_handler(my_dummy_handler, dummy1_h, [State]),
+    ?line Status1 = sys:get_status(Pid),
+    ?line Status2 = sys:get_status(Pid, 5000),
+    ?line ok = gen_event:stop(Pid),
+    ?line {status, Pid, _, [_, _, Pid, [], Data1]} = Status1,
+    ?line HandlerInfo1 = proplists:get_value(items, Data1),
+    ?line {"Installed handlers", [{_,dummy1_h,_,FmtState,_}]} = HandlerInfo1,
+    ?line {status, Pid, _, [_, _, Pid, [], Data2]} = Status2,
+    ?line HandlerInfo2 = proplists:get_value(items, Data2),
+    ?line {"Installed handlers", [{_,dummy1_h,_,FmtState,_}]} = HandlerInfo2,
+    ok.
+
+error_format_status(suite) ->
+    [];
+error_format_status(doc) ->
+    ["Test that a handler error calls format_status/2"];
+error_format_status(Config) when is_list(Config) ->
+    ?line error_logger_forwarder:register(),
+    OldFl = process_flag(trap_exit, true),
+    State = self(),
+    ?line {ok, Pid} = gen_event:start({local, my_dummy_handler}),
+    ?line ok = gen_event:add_sup_handler(my_dummy_handler, dummy1_h, [State]),
+    ?line ok = gen_event:notify(my_dummy_handler, do_crash),
+    ?line receive
+	      {gen_event_EXIT,dummy1_h,{'EXIT',_}} -> ok
+	  after 5000 ->
+		  ?t:fail(exit_gen_event)
+	  end,
+    FmtState = "dummy1_h handler state",
+    receive
+	{error,_GroupLeader, {Pid,
+			      "** gen_event handler"++_,
+			      [dummy1_h,my_dummy_handler,do_crash,
+			       FmtState, _]}} ->
+	    ok;
+	Other ->
+	    ?line io:format("Unexpected: ~p", [Other]),
+	    ?line ?t:fail()
+    end,
+    ?t:messages_get(),
+    ?line ok = gen_event:stop(Pid),
+    process_flag(trap_exit, OldFl),
+    ok.