Move and update documentation

Document the functions that each module may provide in each module's
respective header file.

Signed-off-by: Benjamin Poirier <benjamin.poirier@polymtl.ca>

diff --git a/lttv/lttv/sync/README b/lttv/lttv/sync/README
index 9945c4d8a6a109424bf6a5cad7ab3705d89cd946..190a7c6abc64e3c6eda8177625c573f63378d511 100644 (file)
--- a/lttv/lttv/sync/README
+++ b/lttv/lttv/sync/README
@@ -279,6 +279,10 @@ This stage and its modules are specific to the algorithm that analyzes events
 to deduce synchronization factors.
 eg. convex hull, linear regression, broadcast Maximum Likelihood Estimator
 
+This module should return a set of synchronization factors for each trace
+pair. Some trace pairs may have no factors, their approxType should be set to
+ABSENT.
+
 Instead of having one analyzeEvents() function that can receive any sort of
 grouping of events, there are three prototypes: analyzeMessage(),
 analyzeExchange() and analyzeBroadcast(). A module implements only the
@@ -298,14 +302,10 @@ I chose this approach because:
 3) we'll see which one of the two approaches works best and we can adapt
    later.
 
-++ Data flow
-Data from traces flows "down" from processing to matching to analysis. Factors
-come back up.
-
 ++ Stage 4: Factor reduction
-This stage reduces the pair-wise synchronization factors to time correction
-factors for each trace. It is most useful when synchronizing more than two
-traces.
+This stage reduces the pair-wise synchronization factors obtained in step 3 to
+time correction factors for each trace. It is most useful when synchronizing
+more than two traces.
 
 ++ Evolution and adaptation
 It is possible to change/add another sync chain and to add other modules. It

diff --git a/lttv/lttv/sync/event_analysis.h b/lttv/lttv/sync/event_analysis.h
index 146b9b62a025c85c94ba382f1b4f6dbcdb6b3ecf..da26cf35715cdb5ab759c749a0aeb217f83c34bd 100644 (file)
--- a/lttv/lttv/sync/event_analysis.h
+++ b/lttv/lttv/sync/event_analysis.h
@@ -31,18 +31,51 @@ typedef struct
 {
        char* name;
 
+       /*
+        * This function is called at the beginning of a synchronization run for a set
+        * of traces. Allocate analysis specific data structures.
+        */
        void (*initAnalysis)(struct _SyncState* const syncState);
+
+       /*
+        * Free the analysis specific data structures.
+        */
        void (*destroyAnalysis)(struct _SyncState* const syncState);
 
+       /*
+        * Perform analysis on an event pair.
+        */
        void (*analyzeMessage)(struct _SyncState* const syncState, Message* const
                message);
+
+       /*
+        * Perform analysis on multiple messages.
+        */
        void (*analyzeExchange)(struct _SyncState* const syncState, Exchange* const
                exchange);
+
+       /*
+        * Perform analysis on muliple events.
+        */
        void (*analyzeBroadcast)(struct _SyncState* const syncState, Broadcast* const
                broadcast);
+
+       /*
+        * Finalize the factor calculations. Return synchronization factors
+        * between trace pairs.
+        */
        AllFactors* (*finalizeAnalysis)(struct _SyncState* const syncState);
 
+       /*
+        * Print statistics related to analysis. Is always called after
+        * finalizeAnalysis.
+        */
        void (*printAnalysisStats)(struct _SyncState* const syncState);
+
+       /*
+        * Write the analysis-specific options and graph commands in the gnuplot
+        * script. Is always called after finalizeAnalysis.
+        */
        GraphFunctions graphFunctions;
 } AnalysisModule;
 

diff --git a/lttv/lttv/sync/event_matching.h b/lttv/lttv/sync/event_matching.h
index e4c37732975ba542b6a486f4fad4bc4a90e8d0a2..4e8befc35520c85fae46a6f3d5519f1c43879f8f 100644 (file)
--- a/lttv/lttv/sync/event_matching.h
+++ b/lttv/lttv/sync/event_matching.h
@@ -30,14 +30,40 @@ typedef struct
        char* name;
        bool canMatch[TYPE_COUNT];
 
+       /*
+        * This function is called at the beginning of a synchronization run for a set
+        * of traces. Allocate the matching specific data structures.
+        */
        void (*initMatching)(struct _SyncState* const syncState);
+
+       /*
+        * Free the matching specific data structures.
+        */
        void (*destroyMatching)(struct _SyncState* const syncState);
 
+       /*
+        * Try to match one event from a trace with the corresponding event from
+        * another trace. If it is possible, create a new structure and call the
+        * analyse{message,exchange,broadcast} function of the analysis module.
+        */
        void (*matchEvent)(struct _SyncState* const syncState, Event* const
                event);
+
+       /*
+        * Obtain the factors from downstream.
+        */
        AllFactors* (*finalizeMatching)(struct _SyncState* const syncState);
 
+       /*
+     * Print statistics related to matching. Is always called after
+     * finalizeMatching.
+     */
        void (*printMatchingStats)(struct _SyncState* const syncState);
+
+       /*
+        * Write the matching-specific options and graph commands in the gnuplot
+        * script. Is always called after finalizeMatching.
+        */
        GraphFunctions graphFunctions;
 } MatchingModule;
 

diff --git a/lttv/lttv/sync/event_matching_tcp.c b/lttv/lttv/sync/event_matching_tcp.c
index 3662769a9d17d087de29054c734ae1215033f961..90d6c43cb3c6901bdaf9e69a1c9434496393e0a3 100644 (file)
--- a/lttv/lttv/sync/event_matching_tcp.c
+++ b/lttv/lttv/sync/event_matching_tcp.c
@@ -250,7 +250,7 @@ static void matchEventTCP(SyncState* const syncState, Event* const event)
 
 
 /*
- * Call the partial matching destroyer and Obtain the factors from downstream
+ * Call the partial matching destroyer and obtain the factors from downstream
  *
  * Args:
  *   syncState     container for synchronization data.

diff --git a/lttv/lttv/sync/event_processing.h b/lttv/lttv/sync/event_processing.h
index c3815bd70297418c28fd566bf86e9db91ec7c50c..1bc9ade3c1f0ebd8582820b29419c80972528879 100644 (file)
--- a/lttv/lttv/sync/event_processing.h
+++ b/lttv/lttv/sync/event_processing.h
@@ -31,10 +31,33 @@ typedef struct
 {
        char* name;
 
+       /*
+        * This function is called at the beginning of a synchronization run for a
+        * set of traces. Allocate and initialize data structures for
+        * synchronizing a traceset.
+        */
        void (*initProcessing)(struct _SyncState* const syncStateLttv, ...);
+
+       /*
+        * Obtain the factors from downstream.
+        */
        AllFactors* (*finalizeProcessing)(struct _SyncState* const syncState);
+
+       /*
+        * Print statistics related to processing. Is always called after
+        * finalizeProcessing.
+        */
        void (*printProcessingStats)(struct _SyncState* const syncState);
+
+       /*
+        * Deallocate processingData. No more functions may be called after this.
+        */
        void (*destroyProcessing)(struct _SyncState* const syncState);
+
+       /*
+        * Write the processing-specific options and graph commands in the gnuplot
+        * script. Is always called after finalizeProcessing.
+        */
        GraphFunctions graphFunctions;
 } ProcessingModule;
 

diff --git a/lttv/lttv/sync/event_processing_lttng_standard.c b/lttv/lttv/sync/event_processing_lttng_standard.c
index d37d357c659a4b4333aef66676cce36bafd085af..8cd4f83978ad65e3563361152dcd90ca2ba17c17 100644 (file)
--- a/lttv/lttv/sync/event_processing_lttng_standard.c
+++ b/lttv/lttv/sync/event_processing_lttng_standard.c
@@ -158,7 +158,7 @@ static void initProcessingLTTVStandard(SyncState* const syncState, ...)
 
 
 /*
- * Call the partial processing destroyer, obtain and adjust the factors from
+ * Call the partial processing destroyer, obtain and the factors from
  * downstream
  *
  * Args:
@@ -180,7 +180,7 @@ static AllFactors* finalizeProcessingLTTVStandard(SyncState* const syncState)
 
 
 /*
- * Print statistics related to processing Must be called after
+ * Print statistics related to processing. Must be called after
  * finalizeProcessing.
  *
  * Args:

diff --git a/lttv/lttv/sync/factor_reduction.h b/lttv/lttv/sync/factor_reduction.h
index 249b84acce8031c801f8ac26dfd52c81b8faaa91..561df6baccf245d4a7e6c1ac6e0c7fedd37a7217 100644 (file)
--- a/lttv/lttv/sync/factor_reduction.h
+++ b/lttv/lttv/sync/factor_reduction.h
@@ -28,13 +28,34 @@ typedef struct
 {
        char* name;
 
+       /*
+        * This function is called at the beginning of a synchronization run for a
+        * set of traces. Allocate some reduction specific data structures.
+        */
        void (*initReduction)(struct _SyncState* const syncState);
+
+       /*
+        * Free the reduction specific data structures
+        */
        void (*destroyReduction)(struct _SyncState* const syncState);
 
+       /*
+        * Convert trace pair synchronization factors to a resulting offset and
+        * drift for each trace.
+        */
        GArray* (*finalizeReduction)(struct _SyncState* const syncState,
                AllFactors* allFactors);
 
+       /*
+        * Print statistics related to reduction. Is always called after
+        * finalizeReduction.
+        */
        void (*printReductionStats)(struct _SyncState* const syncState);
+
+       /*
+        * Write the reduction-specific options and graph commands in the gnuplot
+        * script. Is always called after finalizeReduction.
+        */
        GraphFunctions graphFunctions;
 } ReductionModule;
 

diff --git a/lttv/lttv/sync/factor_reduction_accuracy.c b/lttv/lttv/sync/factor_reduction_accuracy.c
index 578dd7332ae8b18765ee81114d79ad9e3aa16b02..a63dae710c180b9c19e8fd42975d22576a857cb9 100644 (file)
--- a/lttv/lttv/sync/factor_reduction_accuracy.c
+++ b/lttv/lttv/sync/factor_reduction_accuracy.c
@@ -86,7 +86,7 @@ static void initReductionAccuracy(SyncState* const syncState)
 /*
  * Reduction destroy function
  *
- * Free the analysis specific data structures
+ * Free the reduction specific data structures
  *
  * Args:
  *   syncState     container for synchronization data.

diff --git a/lttv/lttv/sync/graph_functions.h b/lttv/lttv/sync/graph_functions.h
index 65981ddf11260c53c4a22d44eaefaa4d075430b6..63077aa3380a0dfeb3dbd1ec530a205959941b39 100644 (file)
--- a/lttv/lttv/sync/graph_functions.h
+++ b/lttv/lttv/sync/graph_functions.h
@@ -27,14 +27,32 @@ typedef void (GraphFunction)(struct _SyncState* const syncState, const
 
 typedef struct
 {
+       /*
+        * These functions are called at the beginning of the gnuplot script and
+        * may writes variables that can be reused in the plot or options lines
+        */
        GraphVariableFunction* writeVariables;
-       /* This is for graphs where the data on both axis is in the range of
-        * timestamps */
+
+       /*
+        * All "Back" functions are called, then all "Fore" functions. They add
+        * graphs to a gnuplot "plot" command. All "Options" functions are called.
+        * They can set options via the gnuplot "set" command. Finaly, a replot is
+        * performed. This is done so that options may be set using dynamic
+        * gnuplot variables like GPVAL_X_MIN
+        */
+       /*
+        * These next three functions ("writeTraceTrace...") are for graphs where
+        * both axes are in the scale of timestamps.
+        */
        GraphFunction* writeTraceTraceForePlots;
        GraphFunction* writeTraceTraceBackPlots;
        GraphFunction* writeTraceTraceOptions;
-       /* This is for graphs where the data on the abscissa is in the range of
-        * timestamps and the ordinates is in the range of timestamp deltas */
+
+       /*
+        * These next three functions ("writeTraceTime...") are for graphs where
+        * the abscissa are in the scale of timestamps and the ordinate in the
+        * scale of seconds.
+        */
        GraphFunction* writeTraceTimeForePlots;
        GraphFunction* writeTraceTimeBackPlots;
        GraphFunction* writeTraceTimeOptions;