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
 
 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
 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.
 
 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
 ++ 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
 
 ++ 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;
 
 {
        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);
        void (*initAnalysis)(struct _SyncState* const syncState);

+
+       /*
+        * Free the analysis specific data structures.
+        */

        void (*destroyAnalysis)(struct _SyncState* const syncState);
 
        void (*destroyAnalysis)(struct _SyncState* const syncState);
 

+       /*
+        * Perform analysis on an event pair.
+        */

        void (*analyzeMessage)(struct _SyncState* const syncState, Message* const
                message);
        void (*analyzeMessage)(struct _SyncState* const syncState, Message* const
                message);

+
+       /*
+        * Perform analysis on multiple messages.
+        */

        void (*analyzeExchange)(struct _SyncState* const syncState, Exchange* const
                exchange);
        void (*analyzeExchange)(struct _SyncState* const syncState, Exchange* const
                exchange);

+
+       /*
+        * Perform analysis on muliple events.
+        */

        void (*analyzeBroadcast)(struct _SyncState* const syncState, Broadcast* const
                broadcast);
        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);
 
        AllFactors* (*finalizeAnalysis)(struct _SyncState* const syncState);
 

+       /*
+        * Print statistics related to analysis. Is always called after
+        * finalizeAnalysis.
+        */

        void (*printAnalysisStats)(struct _SyncState* const syncState);
        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;
 
        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];
 
        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);
        void (*initMatching)(struct _SyncState* const syncState);

+
+       /*
+        * Free the matching specific data structures.
+        */

        void (*destroyMatching)(struct _SyncState* const syncState);
 
        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);
        void (*matchEvent)(struct _SyncState* const syncState, Event* const
                event);

+
+       /*
+        * Obtain the factors from downstream.
+        */

        AllFactors* (*finalizeMatching)(struct _SyncState* const syncState);
 
        AllFactors* (*finalizeMatching)(struct _SyncState* const syncState);
 

+       /*
+     * Print statistics related to matching. Is always called after
+     * finalizeMatching.
+     */

        void (*printMatchingStats)(struct _SyncState* const syncState);
        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;
 
        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.
  *
  * 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;
 
 {
        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, ...);
        void (*initProcessing)(struct _SyncState* const syncStateLttv, ...);

+
+       /*
+        * Obtain the factors from downstream.
+        */

        AllFactors* (*finalizeProcessing)(struct _SyncState* const syncState);
        AllFactors* (*finalizeProcessing)(struct _SyncState* const syncState);

+
+       /*
+        * Print statistics related to processing. Is always called after
+        * finalizeProcessing.
+        */

        void (*printProcessingStats)(struct _SyncState* const syncState);
        void (*printProcessingStats)(struct _SyncState* const syncState);

+
+       /*
+        * Deallocate processingData. No more functions may be called after this.
+        */

        void (*destroyProcessing)(struct _SyncState* const syncState);
        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;
 
        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:
  * 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:
  * 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;
 
 {
        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);
        void (*initReduction)(struct _SyncState* const syncState);

+
+       /*
+        * Free the reduction specific data structures
+        */

        void (*destroyReduction)(struct _SyncState* const syncState);
 
        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);
 
        GArray* (*finalizeReduction)(struct _SyncState* const syncState,
                AllFactors* allFactors);
 

+       /*
+        * Print statistics related to reduction. Is always called after
+        * finalizeReduction.
+        */

        void (*printReductionStats)(struct _SyncState* const syncState);
        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;
 
        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
  *
 /*
  * Reduction destroy function
  *

- * Free the analysis specific data structures
+ * Free the reduction specific data structures

  *
  * Args:
  *   syncState     container for synchronization data.
  *
  * 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
 {
 
 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;
        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;
        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;
        GraphFunction* writeTraceTimeForePlots;
        GraphFunction* writeTraceTimeBackPlots;
        GraphFunction* writeTraceTimeOptions;