From eb8e0e6fa27e4cfe25138d8275ee6f686ee2b32d Mon Sep 17 00:00:00 2001 From: Benjamin Poirier Date: Wed, 7 Apr 2010 12:01:03 -0400 Subject: [PATCH] Move and update documentation Document the functions that each module may provide in each module's respective header file. Signed-off-by: Benjamin Poirier --- lttv/lttv/sync/README | 14 ++++---- lttv/lttv/sync/event_analysis.h | 33 +++++++++++++++++++ lttv/lttv/sync/event_matching.h | 26 +++++++++++++++ lttv/lttv/sync/event_matching_tcp.c | 2 +- lttv/lttv/sync/event_processing.h | 23 +++++++++++++ .../sync/event_processing_lttng_standard.c | 4 +-- lttv/lttv/sync/factor_reduction.h | 21 ++++++++++++ lttv/lttv/sync/factor_reduction_accuracy.c | 2 +- lttv/lttv/sync/graph_functions.h | 26 ++++++++++++--- 9 files changed, 136 insertions(+), 15 deletions(-) diff --git a/lttv/lttv/sync/README b/lttv/lttv/sync/README index 9945c4d8..190a7c6a 100644 --- 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 146b9b62..da26cf35 100644 --- 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 e4c37732..4e8befc3 100644 --- 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 3662769a..90d6c43c 100644 --- 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 c3815bd7..1bc9ade3 100644 --- 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 d37d357c..8cd4f839 100644 --- 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 249b84ac..561df6ba 100644 --- 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 578dd733..a63dae71 100644 --- 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 65981ddf..63077aa3 100644 --- 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; -- 2.34.1