** ''org.eclipse.tracecompass.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageComposite.java''
+== Timing Analysis Views and Viewers ==
+
+Trace Compass provides base implementations for timing views and viewers for generating Latency Tables, Scatter Charts, Density Graphs and Statistics Tables. They are well integrated with various Trace Compass features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the Analysis Timing plug-in ''org.eclipse.tracecompass.analysis.timing.ui''. See below for a list of relevant java packages:
+
+* Latency Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.table'': Base classes for Latency Tables
+* Scatter Chart
+** ''org.eclipse.tracecompass.tmf.ui.views.tmfChartView.java'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.scatter'': Base classes for Scatter Charts
+* Density Graph
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.density'': Base classes for Density Graphs
+* Statistics Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.statistics'': Base classes for Statistics Tables
+
+Several features in Trace Compass are using this framework and can be used as example for further development:
+
+* Latency Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternLatencyTableView.java''
+* Scatter Chart
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyScatterView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternScatterGraphView.java''
+* Density Graph
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyDensityView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternDensityView.java''
+
+* Statistics Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.statistics.SystemCallLatencyStatisticsView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternStatisticsView.java''
+
= Component Interaction =
TMF provides a mechanism for different components to interact with each other using signals. The signals can carry information that is specific to each signal.
Received by views that analyze packet streams.
+=== TmfStartAnalysisSignal ===
+
+''Purpose''
+
+This signal is used to indicate that an analysis has started.
+
+''Senders''
+
+Sent by an analysis module when it starts to execute the analyis.
+
+''Receivers''
+
+Received by components that need to be notified of the start of an analysis
+or that need to receive the analysis module.
+
+=== TmfCpuSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a CPU core.
+
+''Senders''
+
+Sent by any component that allows the user to select a CPU.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected CPU.
+
+=== TmfThreadSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a thread.
+
+''Senders''
+
+Sent by any component that allows the user to select a thread.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected thread.
+
+=== TmfTraceSynchronizedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that trace synchronization has been completed.
+
+''Senders''
+
+Sent by the experiment after trace synchronization.
+
+''Receivers''
+
+Received by any component that needs to be notified of trace synchronization.
+
== Debugging ==
TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.tracecompass.tmf.core''', and check the '''signal''' item.
they will have been written by the same person. In other cases, it's possible to
use getSubAttributes() to explore the organization of the attribute tree first.
+===== optQuarkAbsolute()/optQuarkRelative() =====
+
+These two methods are similar to their counterparts getQuarkAbsolute() and
+getQuarkRelative(). The only difference is that if the referenced attribute does
+not exist, the value ITmfStateSystem#INVALID_ATTRIBUTE (-2) is returned instead
+of throwing an exception.
+
+These methods should be used when the presence of the referenced attribute is
+known to be optional, to avoid the performance cost of generating exceptions.
+
+===== getQuarks() =====
+
+This method (with or without a starting node quark) takes an attribute path
+array which may contain wildcard "*" or parent ".." elements, and returns the
+list of matching attribute quarks. If no matching attribute is found, an empty
+list is returned.
+
===== waitUntilBuilt() =====
This is a simple method used to block the caller until the construction phase of
==== AttributeNotFoundException ====
-This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not byt the
+This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not by the
-AndAdd versions!) when passing an attribute path that is not present in the
state system. This is to ensure that no new attribute is created when using
these versions of the methods.
=== Requirement values ===
-When creating a requirement, the developer needs to specify a type to which all
-the values added to the requirement will be linked. In the earlier example,
-there would be an ''"event"'' or ''"eventName"'' type. The type is represented
-by a string, like all values added to the requirement object. With an 'event'
-type requirement, a trace generator like the LTTng Control could automatically
-enable the required events. Another point we have to take into consideration
-is the priority level when creating a requirement object.
+Each concrete analysis requirement class will define how a requirement is verified on a given trace.
+When creating a requirement, the developer will specify a set of values for that class.
+With an 'event' type requirement, a trace generator like the LTTng Control could automatically
+enable the required events.
+Another point we have to take into consideration is the priority level when creating a requirement object.
The enum '''TmfAbstractAnalysisRequirement#PriorityLevel''' gives the choice
between '''PriorityLevel#OPTIONAL''', '''PriorityLevel#ALL_OR_NOTHING''',
'''PriorityLevel#AT_LEAST_ONE''' or '''PriorityLevel#MANDATORY'''. That way, we
can tell if an analysis can run without a value or not.
-To create an requirement one has the choice to extend the abstract class
-'''TmfAbstractAnalysisRequirement''' or use the exiting implementation
-'''TmfAnalysisEventRequirement''', '''TmfAnalysisEventFieldRequirement''' or
-'''TmfCompositeAnalysisRequirement'''.
+To create a requirement one has the choice to extend the abstract class
+'''TmfAbstractAnalysisRequirement''' or use the existing implementations:
+'''TmfAnalysisEventRequirement''' (will verify the presence of events identified by name),
+'''TmfAnalysisEventFieldRequirement''' (will verify the presence of fields for some or all events) or
+'''TmfCompositeAnalysisRequirement''' (join requirements together with one of the priority levels).
Moreover, information can be added to requirements. That way, the developer can explicitly give help details at the requirement level instead of at the analysis level (which would just be a general help text). To add information to a requirement, the method '''TmfAnalysisRequirement#addInformation()''' must be called. Adding information is not mandatory.
/* Requirement on event fields */
Set<@NonNull String> requiredEventFields = ImmutableSet.of("context._procname", "context._ip");
- TmfAbstractAnalysisRequirement eventFiledRequirement = new TmfAnalysisEventFieldRequirement(
+ TmfAbstractAnalysisRequirement eventFieldRequirement = new TmfAnalysisEventFieldRequirement(
"event name",
requiredEventFields,
PriorityLevel.MANDATORY);
- Set<TmfAbstractAnalysisRequirement> requirements = ImmutableSet.of(eventsReq1, eventsReq2, eventFiledRequirement);
+ Set<TmfAbstractAnalysisRequirement> requirements = ImmutableSet.of(eventsReq1, eventsReq2, eventFieldRequirement);
return requirements;
}
</pre>
projects / deliverable / tracecompass.git / blobdiff