Merge remote-tracking branch 'origin/peppe/common_test/public_event_mgr' into maint

* origin/peppe/common_test/public_event_mgr:
  Add documentation
  Add API functions for reading CT event manager references

OTP-12506

4 files changed, 43 insertions, 1 deletions

diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml
index 45f01c12ec..f39f391818 100644
--- a/lib/common_test/doc/src/event_handler_chapter.xml
+++ b/lib/common_test/doc/src/event_handler_chapter.xml
@@ -59,6 +59,15 @@
     Event handlers plugged into this manager will receive the events from 
     all the test nodes as well as information from the CT Master server
     itself.</p>
+
+    <p>User specific event handlers may be plugged into a Common Test event
+    manager, either by telling Common Test to install them before the test
+    run (see below), or by adding the handlers dynamically during the test
+    run by means of 
+    <c>gen_event:add_handler/3</c> or <c>gen_event:add_sup_handler/3</c>.
+    In the latter scenario, the reference of the Common Test event manager is
+    required. To get it, call <c>ct:get_event_mgr_ref/0</c> or (on the CT
+    Master node) <c>ct_master:get_event_mgr_ref/0</c>.</p>
   </section>
   <section>
     <marker id="usage"></marker>
diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index 85afdc7834..9d8fce2789 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -52,6 +52,7 @@
 -module(ct).
 
 -include("ct.hrl").
+-include("ct_util.hrl").
 
 %% Command line user interface for running tests
 -export([install/1, run/1, run/2, run/3,
@@ -77,6 +78,7 @@
 
 %% Other interface functions
 -export([get_status/0, abort_current_testcase/1,
+	 get_event_mgr_ref/0,
 	 encrypt_config_file/2, encrypt_config_file/3,
 	 decrypt_config_file/2, decrypt_config_file/3]).
 
@@ -1005,6 +1007,18 @@ abort_current_testcase(Reason) ->
     test_server_ctrl:abort_current_testcase(Reason).
 
 %%%-----------------------------------------------------------------
+%%% @spec get_event_mgr_ref() -> EvMgrRef
+%%%       EvMgrRef = atom()
+%%%
+%%% @doc <p>Call this function in order to get a reference to the
+%%%         CT event manager. The reference can be used to e.g. add
+%%%         a user specific event handler while tests are running.
+%%%         Example:
+%%%         <c>gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])</c></p>
+get_event_mgr_ref() ->
+    ?CT_EVMGR_REF.
+
+%%%-----------------------------------------------------------------
 %%% @spec encrypt_config_file(SrcFileName, EncryptFileName) -> 
 %%%                                                  ok | {error,Reason}
 %%%       SrcFileName = string()
diff --git a/lib/common_test/src/ct_master.erl b/lib/common_test/src/ct_master.erl
index b42ff73846..2cdb259899 100644
--- a/lib/common_test/src/ct_master.erl
+++ b/lib/common_test/src/ct_master.erl
@@ -25,6 +25,7 @@
 -export([run/1,run/3,run/4]).
 -export([run_on_node/2,run_on_node/3]).
 -export([run_test/1,run_test/2]).
+-export([get_event_mgr_ref/0]).
 -export([basic_html/1]).
 
 -export([abort/0,abort/1,progress/0]).
@@ -292,6 +293,18 @@ progress() ->
     call(progress).
 
 %%%-----------------------------------------------------------------
+%%% @spec get_event_mgr_ref() -> MasterEvMgrRef
+%%%       MasterEvMgrRef = atom()
+%%%
+%%% @doc <p>Call this function in order to get a reference to the
+%%%         CT master event manager. The reference can be used to e.g.
+%%%         add a user specific event handler while tests are running.
+%%%         Example:
+%%%         <c>gen_event:add_handler(ct_master:get_event_mgr_ref(), my_ev_h, [])</c></p>
+get_event_mgr_ref() ->
+    ?CT_MEVMGR_REF.
+
+%%%-----------------------------------------------------------------
 %%% @spec basic_html(Bool) -> ok
 %%%       Bool = true | false
 %%%
diff --git a/lib/common_test/test/ct_event_handler_SUITE.erl b/lib/common_test/test/ct_event_handler_SUITE.erl
index 30a5e650fe..750ccb8659 100644
--- a/lib/common_test/test/ct_event_handler_SUITE.erl
+++ b/lib/common_test/test/ct_event_handler_SUITE.erl
@@ -29,6 +29,7 @@
 -compile(export_all).
 
 -include_lib("common_test/include/ct.hrl").
+-include_lib("common_test/src/ct_util.hrl").
 
 %-include_lib("common_test/include/ct_event.hrl").
 
@@ -59,7 +60,7 @@ end_per_testcase(TestCase, Config) ->
 suite() -> [{ct_hooks,[ts_install_cth]}].
 
 all() -> 
-    [start_stop, results].
+    [start_stop, results, event_mgrs].
 
 groups() -> 
     [].
@@ -179,5 +180,10 @@ results(Config) when is_list(Config) ->
     ok = ct_test_support:verify_events(TestEvents++TestEvents, Events, Config).
 
 
+event_mgrs(_) ->
+    ?CT_EVMGR_REF = ct:get_event_mgr_ref(),
+    ?CT_MEVMGR_REF = ct_master:get_event_mgr_ref().
+
+
 %%%-----------------------------------------------------------------
 %%% HELP FUNCTIONS