From cb119ebc0e923b6b85a8352ef71012eb431b54d5 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erix.ericsson.se>
Date: Wed, 2 Feb 2011 10:52:42 +0100
Subject: Update documentation to reflect performance enhancement changes of
 cover

---
 lib/tools/doc/src/cover.xml         | 29 +++++++++++++++++++++++++++++
 lib/tools/doc/src/cover_chapter.xml |  7 +++++++
 lib/tools/src/cover.erl             | 34 ++++++++++++++++++++++++----------
 3 files changed, 60 insertions(+), 10 deletions(-)

(limited to 'lib/tools')

diff --git a/lib/tools/doc/src/cover.xml b/lib/tools/doc/src/cover.xml
index 323bd0dda8..0a3302bda5 100644
--- a/lib/tools/doc/src/cover.xml
+++ b/lib/tools/doc/src/cover.xml
@@ -270,6 +270,8 @@
           defaults to <c>function</c>.</p>
         <p>If <c>Module</c> is not Cover compiled, the function returns
           <c>{error,{not_cover_compiled,Module}}</c>.</p>
+	<p>HINT: It is possible to issue multiple analyse_to_file commands at
+	  the same time. </p>
       </desc>
     </func>
     <func>
@@ -307,6 +309,33 @@
           <c>.beam</c> file, or in <c>../src</c> relative to that
           directory. If no source code is found, 
           <c>,{error,no_source_code_found}</c> is returned.</p>
+	<p>HINT: It is possible to issue multiple analyse_to_file commands at
+	  the same time. </p> 
+      </desc>
+    </func>
+    <func>
+      <name>async_analyse_to_file(Module) -> </name>
+      <name>async_analyse_to_file(Module,Options) -> </name>
+      <name>async_analyse_to_file(Module, OutFile) -> </name>
+      <name>async_analyse_to_file(Module, OutFile, Options) ->  pid()</name>
+      <fsummary>Asynchronous call to analyse_to_file.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+        <v>OutFile = string()</v>
+        <v>Options = [Option]</v>
+        <v>Option = html</v>
+        <v>Error = {not_cover_compiled,Module} | {file,File,Reason} | no_source_code_found | not_main_node</v>
+        <v>&nbsp;File = string()</v>
+        <v>&nbsp;Reason = term()</v>
+      </type>
+      <desc>
+	<p>This function works exactly the same way as 
+	<seealso marker="#analyse_to_file-1">analyse_to_file</seealso> except
+	that it is asynchronous instead of synchronous. The spawned process
+	will link with the caller when created. If an <c>Error</c> occurs
+	while doing the cover analysis the process will crash with the same
+	error reason as <seealso marker="#analyse_to_file-1">analyse_to_file</seealso> 
+	would return.</p>
       </desc>
     </func>
     <func>
diff --git a/lib/tools/doc/src/cover_chapter.xml b/lib/tools/doc/src/cover_chapter.xml
index b4f7919183..92a790c34e 100644
--- a/lib/tools/doc/src/cover_chapter.xml
+++ b/lib/tools/doc/src/cover_chapter.xml
@@ -403,6 +403,13 @@ ok
         database contains information about each executable line in each
         Cover compiled module, performance decreases proportionally to
         the size and number of the Cover compiled modules.</p>
+      <p>To improve performance when analysing cover results it is possible
+	to do multiple calls to <seealso marker="cover#analyse-1">analyse</seealso>
+	and <seealso marker="cover#analyse_to_file-1">analyse_to_file</seealso>
+	at once. You can also use the 
+	<seealso marker="cover#async_analyse_to_file-1">async_analyse_to_file</seealso> 
+	convenience function.
+      </p>
     </section>
 
     <section>
diff --git a/lib/tools/src/cover.erl b/lib/tools/src/cover.erl
index 50a812aa09..cc4f75f2e8 100644
--- a/lib/tools/src/cover.erl
+++ b/lib/tools/src/cover.erl
@@ -35,23 +35,37 @@
 %% remote_process_loop/1.
 %%
 %% TABLES
-%% Each nodes has an ets table named 'cover_internal_data_table'
-%% (?COVER_TABLE).  This table contains the coverage data and is
-%% continously updated when cover compiled code is executed.
+%% Each nodes has two tables: cover_internal_data_table (?COVER_TABLE) and.
+%% cover_internal_clause_table (?COVER_CLAUSE_TABLE). 
+%% ?COVER_TABLE contains the bump data i.e. the data about which lines
+%% have been executed how many times.
+%% ?COVER_CLAUSE_TABLE contains information about which clauses in which modules
+%% cover is currently collecting statistics.
 %% 
-%% The main node owns a table named
-%% 'cover_collected_remote_data_table' (?COLLECTION_TABLE). This table
-%% contains data which is collected from remote nodes (either when a
-%% remote node is stopped with cover:stop/1 or when analysing. When
-%% analysing, data is even moved from the ?COVER_TABLE on the main
-%% node to the ?COLLECTION_TABLE.
+%% The main node owns tables named
+%% 'cover_collected_remote_data_table' (?COLLECTION_TABLE) and
+%% 'cover_collected_remote_clause_table' (?COLLECTION_CLAUSE_TABLE). 
+%% These tables contain data which is collected from remote nodes (either when a
+%% remote node is stopped with cover:stop/1 or when analysing). When
+%% analysing, data is even moved from the COVER tables on the main
+%% node to the COLLECTION tables.
 %%
 %% The main node also has a table named 'cover_binary_code_table'
 %% (?BINARY_TABLE). This table contains the binary code for each cover
 %% compiled module. This is necessary so that the code can be loaded
 %% on remote nodes that are started after the compilation.
 %%
-
+%% PARELLALISM
+%% To take advantage of SMP when doing the cover analysis both the data 
+%% collection and analysis has been parallelized. One process is spawned for
+%% each node when collecting data, and on the remote node when collecting data
+%% one process is spawned per module. 
+%% 
+%% When analyzing data it is possible to issue multiple analyse(_to_file)/X 
+%% calls at once. They are however all calls (for backwardscompatability 
+%% reasons) so the user of cover will have to spawn several processes to to the
+%% calls ( or use async_analyse_to_file ). 
+%%
 
 %% External exports
 -export([start/0, start/1,
-- 
cgit v1.2.3