Merge branch 'lukas/common_test/cth_prio/OTP-9445' into dev

* lukas/common_test/cth_prio/OTP-9445:
  Fix a couple of minor bugs with hook priority
  Update to reflect addition of CTH priority addition
  Update CTH priority default to be 0
  Update to reflect new cth callback api
  Update the return from init/2 to be {ok, NewState} or {ok,NewState,Priority} instead of NewState.
  Add priority functionality and tests for ct hooks
  Update internal hooks state to use a record instead of tuples

4 files changed, 24 insertions, 7 deletions

diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index c92566de37..57b032b3fd 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -144,7 +144,7 @@
 	<v> UserData = term()</v>
 	<v> Conns = [atom()]</v>
 	<v> CSSFile = string()</v>
-	<v> CTHs = [CTHModule | {CTHModule, CTHInitArgs}]</v>
+	<v> CTHs = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]</v>
 	<v> CTHModule = atom()</v>
 	<v> CTHInitArgs = term()</v>
 	</type>
diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml
index 7d5c9f4750..0ece3199bb 100644
--- a/lib/common_test/doc/src/ct_hooks.xml
+++ b/lib/common_test/doc/src/ct_hooks.xml
@@ -81,12 +81,14 @@
   
   <funcs>
     <func>
-      <name>Module:init(Id, Opts) -&gt; State</name>
+      <name>Module:init(Id, Opts) -&gt; {ok, State} | 
+      {ok, State, Priority}</name>
       <fsummary>Initiates the Common Test Hook</fsummary>
       <type>
 	<v>Id = reference() | term()</v>
 	<v>Opts = term()</v>
 	<v>State = term()</v>
+	<v>Priority = integer()</v>
       </type>
       
       <desc>	
@@ -103,6 +105,10 @@
 	  if <seealso marker="#Module:id-1">id/1</seealso> is not implemented.
 	</p>
 
+	<p><c>Priority</c> is the relative priority of this hook. Hooks with a
+	lower priority will be executed first. If no priority is given, 
+	it will be set to 0. </p>
+
 	<p>For details about when init is called see
 	  <seealso marker="ct_hooks_chapter#scope">scope</seealso>
 	  in the User's Guide.</p>
diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index fc5ab48e1b..dbb4310040 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -94,9 +94,11 @@
       <seealso marker="common_test#Module:init_per_group-2">
     init_per_group/2</seealso>. <c>CTH</c> in this case can be either
     only the module name of the CTH or a tuple with the module name and the
-    initial arguments to the CTH. Eg:
+    initial arguments and optionally the hook priority of the CTH. Eg:
     <c>{ct_hooks,[my_cth_module]}</c> or 
-    <c>{ct_hooks,[{my_cth_module,[{debug,true}]}]}</c></p>
+    <c>{ct_hooks,[{my_cth_module,[{debug,true}]}]}</c> or 
+    <c>{ct_hooks,[{my_cth_module,[{debug,true}],500}]}</c>
+    </p>
 
     <section>
       <title>Overriding CTHs</title>
@@ -109,7 +111,16 @@
 	<c>id</c> in both places, Common Test knows that this CTH
 	has already been installed and will not try to install it again.</p>
     </section>
-
+   
+    <section>
+      <title>CTH Priority</title>
+      <p>By default each CTH installed will be executed in the order which
+      they are installed. This is not always wanted so common_test allows 
+      the user to specify a priority for each hook. The priority can either
+      be specified in the CTH <seealso marker="ct_hooks#Module:init-2">init/2
+      </seealso> function or when installing the hook. The priority given at
+      installation will override the priority returned by the CTH. </p>
+    </section>
   </section>
 
   <marker id="scope"/>
@@ -331,7 +342,7 @@ id(Opts) ->
 %% any common state. 
 init(Id, Opts) ->
     {ok,D} = file:open(Id,[write]),
-    #state{ file_handle = D, total = 0, data = [] }.
+    {ok, #state{ file_handle = D, total = 0, data = [] }}.
 
 %% @doc Called before init_per_suite is called. 
 pre_init_per_suite(Suite,Config,State) ->
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index e6fb85634f..e668568795 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -488,7 +488,7 @@
       LogDir        = string()
       EventHandlers = atom() | [atom()]
       InitArgs      = [term()]
-      CTHModules    = [CTHModule | {CTHModule, CTHInitArgs}]
+      CTHModules    = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]
       CTHModule     = atom()
       CTHInitArgs   = term()
       DirRef        = DirAlias | Dir