1 /*******************************************************************************
2 * Copyright (c) 2009, 2013 Ericsson
4 * All rights reserved. This program and the accompanying materials are
5 * made available under the terms of the Eclipse Public License v1.0 which
6 * accompanies this distribution, and is available at
7 * http://www.eclipse.org/legal/epl-v10.html
10 * Francois Chouinard - Initial API and implementation
11 * Francois Chouinard - Updated as per TMF Trace Model 1.0
12 * Patrick Tasse - Updated for removal of context clone
13 *******************************************************************************/
15 package org
.eclipse
.linuxtools
.tmf
.core
.trace
;
18 import java
.util
.Collections
;
19 import java
.util
.LinkedHashMap
;
22 import org
.eclipse
.core
.resources
.IResource
;
23 import org
.eclipse
.core
.runtime
.CoreException
;
24 import org
.eclipse
.core
.runtime
.IPath
;
25 import org
.eclipse
.linuxtools
.tmf
.core
.component
.TmfEventProvider
;
26 import org
.eclipse
.linuxtools
.tmf
.core
.event
.ITmfEvent
;
27 import org
.eclipse
.linuxtools
.tmf
.core
.exceptions
.TmfTraceException
;
28 import org
.eclipse
.linuxtools
.tmf
.core
.request
.ITmfDataRequest
;
29 import org
.eclipse
.linuxtools
.tmf
.core
.request
.ITmfEventRequest
;
30 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfRangeSynchSignal
;
31 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfSignalHandler
;
32 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfTimeSynchSignal
;
33 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfTraceOpenedSignal
;
34 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfTraceRangeUpdatedSignal
;
35 import org
.eclipse
.linuxtools
.tmf
.core
.statesystem
.ITmfStateSystem
;
36 import org
.eclipse
.linuxtools
.tmf
.core
.statistics
.ITmfStatistics
;
37 import org
.eclipse
.linuxtools
.tmf
.core
.statistics
.TmfStateStatistics
;
38 import org
.eclipse
.linuxtools
.tmf
.core
.timestamp
.ITmfTimestamp
;
39 import org
.eclipse
.linuxtools
.tmf
.core
.timestamp
.TmfTimeRange
;
40 import org
.eclipse
.linuxtools
.tmf
.core
.timestamp
.TmfTimestamp
;
43 * Abstract implementation of ITmfTrace.
45 * Since the concept of 'location' is trace specific, the concrete classes have
46 * to provide the related methods, namely:
48 * <li> public ITmfLocation<?> getCurrentLocation()
49 * <li> public double getLocationRatio(ITmfLocation<?> location)
50 * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
51 * <li> public ITmfContext seekEvent(double ratio)
52 * <li> public boolean validate(IProject project, String path)
54 * A concrete trace must provide its corresponding parser. A common way to
55 * accomplish this is by making the concrete class extend TmfTrace and
56 * implement ITmfEventParser.
58 * The concrete class can either specify its own indexer or use the provided
59 * TmfCheckpointIndexer (default). In this case, the trace cache size will be
60 * used as checkpoint interval.
63 * @author Francois Chouinard
66 * @see ITmfTraceIndexer
67 * @see ITmfEventParser
69 public abstract class TmfTrace
extends TmfEventProvider
implements ITmfTrace
{
71 // ------------------------------------------------------------------------
73 // ------------------------------------------------------------------------
75 // The resource used for persistent properties for this trace
76 private IResource fResource
;
81 // The trace cache page size
82 private int fCacheSize
= ITmfTrace
.DEFAULT_TRACE_CACHE_SIZE
;
84 // The number of events collected (so far)
85 private long fNbEvents
= 0;
87 // The time span of the event stream
88 private ITmfTimestamp fStartTime
= TmfTimestamp
.BIG_BANG
;
89 private ITmfTimestamp fEndTime
= TmfTimestamp
.BIG_BANG
;
91 // The trace streaming interval (0 = no streaming)
92 private long fStreamingInterval
= 0;
95 private ITmfTraceIndexer fIndexer
;
98 private ITmfEventParser fParser
;
100 // The trace's statistics
101 private ITmfStatistics fStatistics
;
103 // The current selected time
104 private ITmfTimestamp fCurrentTime
= TmfTimestamp
.ZERO
;
106 // The current selected range
107 private TmfTimeRange fCurrentRange
= TmfTimeRange
.NULL_RANGE
;
110 * The collection of state systems that are registered with this trace. Each
111 * sub-class can decide to add its (one or many) state system to this map
112 * during their {@link #buildStateSystem()}.
116 protected final Map
<String
, ITmfStateSystem
> fStateSystems
=
117 new LinkedHashMap
<String
, ITmfStateSystem
>();
119 // ------------------------------------------------------------------------
121 // ------------------------------------------------------------------------
124 * The default, parameterless, constructor
131 * The standard constructor (non-live trace). Applicable when the trace
132 * implements its own parser and if at checkpoint-based index is OK.
134 * @param resource the resource associated to the trace
135 * @param type the trace event type
136 * @param path the trace path
137 * @param cacheSize the trace cache size
138 * @throws TmfTraceException If something failed during the opening
140 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
) throws TmfTraceException
{
141 this(resource
, type
, path
, cacheSize
, 0);
145 * The standard constructor (live trace). Applicable when the trace
146 * implements its own parser and if at checkpoint-based index is OK.
148 * @param resource the resource associated to the trace
149 * @param type the trace event type
150 * @param path the trace path
151 * @param cacheSize the trace cache size
152 * @param interval the trace streaming interval
153 * @throws TmfTraceException If something failed during the opening
155 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
, final long interval
) throws TmfTraceException
{
156 this(resource
, type
, path
, cacheSize
, interval
, null);
160 * The 'non-default indexer' constructor. Allows to provide a trace
163 * @param resource the resource associated to the trace
164 * @param type the trace event type
165 * @param path the trace path
166 * @param cacheSize the trace cache size
167 * @param interval the trace streaming interval
168 * @param indexer the trace indexer
169 * @throws TmfTraceException If something failed during the opening
171 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
,
172 final long interval
, final ITmfTraceIndexer indexer
) throws TmfTraceException
{
173 this(resource
, type
, path
, cacheSize
, interval
, indexer
, null);
177 * The full constructor where trace specific indexer/parser are provided.
179 * @param resource the resource associated to the trace
180 * @param type the trace event type
181 * @param path the trace path
182 * @param cacheSize the trace cache size
183 * @param interval the trace streaming interval
184 * @param indexer the trace indexer
185 * @param parser the trace event parser
186 * @throws TmfTraceException If something failed during the opening
188 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
,
189 final long interval
, final ITmfTraceIndexer indexer
, final ITmfEventParser parser
) throws TmfTraceException
{
191 fCacheSize
= (cacheSize
> 0) ? cacheSize
: ITmfTrace
.DEFAULT_TRACE_CACHE_SIZE
;
192 fStreamingInterval
= interval
;
193 fIndexer
= (indexer
!= null) ? indexer
: new TmfCheckpointIndexer(this, fCacheSize
);
195 initialize(resource
, path
, type
);
201 * @param trace the original trace
202 * @throws TmfTraceException Should not happen usually
204 public TmfTrace(final TmfTrace trace
) throws TmfTraceException
{
207 throw new IllegalArgumentException();
209 fCacheSize
= trace
.getCacheSize();
210 fStreamingInterval
= trace
.getStreamingInterval();
211 fIndexer
= new TmfCheckpointIndexer(this);
212 fParser
= trace
.fParser
;
213 initialize(trace
.getResource(), trace
.getPath(), trace
.getEventType());
216 // ------------------------------------------------------------------------
217 // ITmfTrace - Initializers
218 // ------------------------------------------------------------------------
221 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
224 public void initTrace(final IResource resource
, final String path
, final Class
<?
extends ITmfEvent
> type
) throws TmfTraceException
{
225 fIndexer
= new TmfCheckpointIndexer(this, fCacheSize
);
226 initialize(resource
, path
, type
);
230 * Initialize the trace common attributes and the base component.
232 * @param resource the Eclipse resource (trace)
233 * @param path the trace path
234 * @param type the trace event type
236 * @throws TmfTraceException If something failed during the initialization
238 protected void initialize(final IResource resource
, final String path
, final Class
<?
extends ITmfEvent
> type
) throws TmfTraceException
{
240 throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
243 fResource
= resource
;
244 String traceName
= (resource
!= null) ? resource
.getName() : null;
245 // If no resource was provided, extract the display name the trace path
246 if (traceName
== null) {
247 final int sep
= path
.lastIndexOf(IPath
.SEPARATOR
);
248 traceName
= (sep
>= 0) ? path
.substring(sep
+ 1) : path
;
250 if (fParser
== null) {
251 if (this instanceof ITmfEventParser
) {
252 fParser
= (ITmfEventParser
) this;
254 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
257 super.init(traceName
, type
);
261 * Indicates if the path points to an existing file/directory
263 * @param path the path to test
264 * @return true if the file/directory exists
266 protected boolean fileExists(final String path
) {
267 final File file
= new File(path
);
268 return file
.exists();
274 * @param waitForCompletion index synchronously (true) or not (false)
276 protected void indexTrace(boolean waitForCompletion
) {
277 getIndexer().buildIndex(0, TmfTimeRange
.ETERNITY
, waitForCompletion
);
281 * The default implementation of TmfTrace uses a TmfStatistics back-end.
282 * Override this if you want to specify another type (or none at all).
284 * @throws TmfTraceException
285 * If there was a problem setting up the statistics
288 protected void buildStatistics() throws TmfTraceException
{
290 * Initialize the statistics provider, but only if a Resource has been
291 * set (so we don't build it for experiments, for unit tests, etc.)
293 fStatistics
= (fResource
== null ?
null : new TmfStateStatistics(this) );
297 * Build the state system(s) associated with this trace type.
299 * Suppressing the warning, because the 'throws' will usually happen in
302 * @throws TmfTraceException
303 * If there is a problem during the build
306 @SuppressWarnings("unused")
307 protected void buildStateSystem() throws TmfTraceException
{
309 * Nothing is done in the base implementation, please specify
310 * how/if to register a new state system in derived classes.
319 public synchronized void dispose() {
320 /* Clean up the index if applicable */
321 if (getIndexer() != null) {
322 getIndexer().dispose();
325 /* Clean up the statistics */
326 if (fStatistics
!= null) {
327 fStatistics
.dispose();
330 /* Clean up the state systems */
331 for (ITmfStateSystem ss
: fStateSystems
.values()) {
338 // ------------------------------------------------------------------------
339 // ITmfTrace - Basic getters
340 // ------------------------------------------------------------------------
346 public ITmfTrace
[] getTraces() {
347 return new ITmfTrace
[] { this };
351 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
354 public Class
<ITmfEvent
> getEventType() {
355 return (Class
<ITmfEvent
>) super.getType();
359 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
362 public IResource
getResource() {
367 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
370 public String
getPath() {
375 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
378 public int getCacheSize() {
383 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
386 public long getStreamingInterval() {
387 return fStreamingInterval
;
391 * @return the trace indexer
393 protected ITmfTraceIndexer
getIndexer() {
398 * @return the trace parser
400 protected ITmfEventParser
getParser() {
408 public ITmfStatistics
getStatistics() {
416 public final Map
<String
, ITmfStateSystem
> getStateSystems() {
417 return Collections
.unmodifiableMap(fStateSystems
);
424 public final void registerStateSystem(String id
, ITmfStateSystem ss
) {
425 fStateSystems
.put(id
, ss
);
428 // ------------------------------------------------------------------------
429 // ITmfTrace - Trace characteristics getters
430 // ------------------------------------------------------------------------
433 public synchronized long getNbEvents() {
441 public TmfTimeRange
getTimeRange() {
442 return new TmfTimeRange(fStartTime
, fEndTime
);
449 public ITmfTimestamp
getStartTime() {
457 public ITmfTimestamp
getEndTime() {
465 public ITmfTimestamp
getCurrentTime() {
473 public TmfTimeRange
getCurrentRange() {
474 return fCurrentRange
;
481 public ITmfTimestamp
getInitialRangeOffset() {
482 final long DEFAULT_INITIAL_OFFSET_VALUE
= (1L * 100 * 1000 * 1000); // .1sec
483 return new TmfTimestamp(DEFAULT_INITIAL_OFFSET_VALUE
, ITmfTimestamp
.NANOSECOND_SCALE
);
486 // ------------------------------------------------------------------------
487 // Convenience setters
488 // ------------------------------------------------------------------------
491 * Set the trace cache size. Must be done at initialization time.
493 * @param cacheSize The trace cache size
495 protected void setCacheSize(final int cacheSize
) {
496 fCacheSize
= cacheSize
;
500 * Set the trace known number of events. This can be quite dynamic
501 * during indexing or for live traces.
503 * @param nbEvents The number of events
505 protected synchronized void setNbEvents(final long nbEvents
) {
506 fNbEvents
= (nbEvents
> 0) ? nbEvents
: 0;
510 * Update the trace events time range
512 * @param range the new time range
515 protected void setTimeRange(final TmfTimeRange range
) {
516 fStartTime
= range
.getStartTime();
517 fEndTime
= range
.getEndTime();
521 * Update the trace chronologically first event timestamp
523 * @param startTime the new first event timestamp
526 protected void setStartTime(final ITmfTimestamp startTime
) {
527 fStartTime
= startTime
;
531 * Update the trace chronologically last event timestamp
533 * @param endTime the new last event timestamp
536 protected void setEndTime(final ITmfTimestamp endTime
) {
541 * Set the polling interval for live traces (default = 0 = no streaming).
543 * @param interval the new trace streaming interval
545 protected void setStreamingInterval(final long interval
) {
546 fStreamingInterval
= (interval
> 0) ? interval
: 0;
550 * Set the trace indexer. Must be done at initialization time.
552 * @param indexer the trace indexer
554 protected void setIndexer(final ITmfTraceIndexer indexer
) {
559 * Set the trace parser. Must be done at initialization time.
561 * @param parser the new trace parser
563 protected void setParser(final ITmfEventParser parser
) {
567 // ------------------------------------------------------------------------
568 // ITmfTrace - SeekEvent operations (returning a trace context)
569 // ------------------------------------------------------------------------
572 public synchronized ITmfContext
seekEvent(final long rank
) {
574 // A rank <= 0 indicates to seek the first event
576 ITmfContext context
= seekEvent((ITmfLocation
) null);
581 // Position the trace at the checkpoint
582 final ITmfContext context
= fIndexer
.seekIndex(rank
);
584 // And locate the requested event context
585 long pos
= context
.getRank();
587 ITmfEvent event
= getNext(context
);
588 while ((event
!= null) && (++pos
< rank
)) {
589 event
= getNext(context
);
599 public synchronized ITmfContext
seekEvent(final ITmfTimestamp timestamp
) {
601 // A null timestamp indicates to seek the first event
602 if (timestamp
== null) {
603 ITmfContext context
= seekEvent((ITmfLocation
) null);
608 // Position the trace at the checkpoint
609 ITmfContext context
= fIndexer
.seekIndex(timestamp
);
611 // And locate the requested event context
612 ITmfLocation previousLocation
= context
.getLocation();
613 long previousRank
= context
.getRank();
614 ITmfEvent event
= getNext(context
);
615 while (event
!= null && event
.getTimestamp().compareTo(timestamp
, false) < 0) {
616 previousLocation
= context
.getLocation();
617 previousRank
= context
.getRank();
618 event
= getNext(context
);
621 context
.setLocation(null);
622 context
.setRank(ITmfContext
.UNKNOWN_RANK
);
625 context
= seekEvent(previousLocation
);
626 context
.setRank(previousRank
);
631 // ------------------------------------------------------------------------
632 // ITmfTrace - Read operations (returning an actual event)
633 // ------------------------------------------------------------------------
636 public synchronized ITmfEvent
getNext(final ITmfContext context
) {
637 // parseEvent() does not update the context
638 final ITmfEvent event
= fParser
.parseEvent(context
);
640 updateAttributes(context
, event
.getTimestamp());
641 context
.setLocation(getCurrentLocation());
642 context
.increaseRank();
649 * Hook for special event processing by the concrete class
650 * (called by TmfTrace.getEvent())
652 * @param event the event
654 protected void processEvent(final ITmfEvent event
) {
659 * Update the trace attributes
661 * @param context the current trace context
662 * @param timestamp the corresponding timestamp
665 protected synchronized void updateAttributes(final ITmfContext context
, final ITmfTimestamp timestamp
) {
666 if (fStartTime
.equals(TmfTimestamp
.BIG_BANG
) || (fStartTime
.compareTo(timestamp
, false) > 0)) {
667 fStartTime
= timestamp
;
669 if (fEndTime
.equals(TmfTimestamp
.BIG_CRUNCH
) || (fEndTime
.compareTo(timestamp
, false) < 0)) {
670 fEndTime
= timestamp
;
672 if (fCurrentRange
== TmfTimeRange
.NULL_RANGE
) {
673 fCurrentTime
= timestamp
;
674 ITmfTimestamp initialOffset
= getInitialRangeOffset();
675 long endValue
= timestamp
.getValue() + initialOffset
.normalize(0, timestamp
.getScale()).getValue();
676 ITmfTimestamp endTimestamp
= new TmfTimestamp(endValue
, timestamp
.getScale());
677 fCurrentRange
= new TmfTimeRange(timestamp
, endTimestamp
);
679 if (context
.hasValidRank()) {
680 long rank
= context
.getRank();
681 if (fNbEvents
<= rank
) {
682 fNbEvents
= rank
+ 1;
684 if (fIndexer
!= null) {
685 fIndexer
.updateIndex(context
, timestamp
);
690 // ------------------------------------------------------------------------
692 // ------------------------------------------------------------------------
698 public synchronized ITmfContext
armRequest(final ITmfDataRequest request
) {
699 if (executorIsShutdown()) {
702 if ((request
instanceof ITmfEventRequest
)
703 && !TmfTimestamp
.BIG_BANG
.equals(((ITmfEventRequest
) request
).getRange().getStartTime())
704 && (request
.getIndex() == 0))
706 final ITmfContext context
= seekEvent(((ITmfEventRequest
) request
).getRange().getStartTime());
707 ((ITmfEventRequest
) request
).setStartIndex((int) context
.getRank());
711 return seekEvent(request
.getIndex());
714 // ------------------------------------------------------------------------
716 // ------------------------------------------------------------------------
719 * Handler for the Trace Opened signal
722 * The incoming signal
726 public void traceOpened(TmfTraceOpenedSignal signal
) {
727 ITmfTrace trace
= null;
728 for (ITmfTrace expTrace
: signal
.getTrace().getTraces()) {
729 if (expTrace
== this) {
736 /* This signal is not for us */
741 * The signal is for this trace, or for an experiment containing
747 } catch (TmfTraceException e
) {
751 /* Refresh the project, so it can pick up new files that got created. */
753 if (fResource
!= null) {
754 fResource
.getProject().refreshLocal(IResource
.DEPTH_INFINITE
, null);
756 } catch (CoreException e
) {
760 if (signal
.getTrace() == this) {
761 /* Additionally, the signal is directly for this trace or experiment. */
762 if (getNbEvents() == 0) {
766 final TmfTimeRange timeRange
= new TmfTimeRange(getStartTime(), TmfTimestamp
.BIG_CRUNCH
);
767 final TmfTraceRangeUpdatedSignal rangeUpdatedsignal
= new TmfTraceRangeUpdatedSignal(this, this, timeRange
);
769 // Broadcast in separate thread to prevent deadlock
773 broadcast(rangeUpdatedsignal
);
781 * Signal handler for the TmfTraceRangeUpdatedSignal signal
783 * @param signal The incoming signal
787 public void traceRangeUpdated(final TmfTraceRangeUpdatedSignal signal
) {
788 if (signal
.getTrace() == this) {
789 getIndexer().buildIndex(getNbEvents(), signal
.getRange(), false);
794 * Signal handler for the TmfTimeSynchSignal signal
796 * @param signal The incoming signal
800 public void synchToTime(final TmfTimeSynchSignal signal
) {
801 if (signal
.getCurrentTime().compareTo(fStartTime
) >= 0 && signal
.getCurrentTime().compareTo(fEndTime
) <= 0) {
802 fCurrentTime
= signal
.getCurrentTime();
807 * Signal handler for the TmfRangeSynchSignal signal
809 * @param signal The incoming signal
813 public void synchToRange(final TmfRangeSynchSignal signal
) {
814 if (signal
.getCurrentTime().compareTo(fStartTime
) >= 0 && signal
.getCurrentTime().compareTo(fEndTime
) <= 0) {
815 fCurrentTime
= signal
.getCurrentTime();
817 if (signal
.getCurrentRange().getIntersection(getTimeRange()) != null) {
818 fCurrentRange
= signal
.getCurrentRange().getIntersection(getTimeRange());
822 // ------------------------------------------------------------------------
824 // ------------------------------------------------------------------------
827 @SuppressWarnings("nls")
828 public synchronized String
toString() {
829 return "TmfTrace [fPath=" + fPath
+ ", fCacheSize=" + fCacheSize
830 + ", fNbEvents=" + fNbEvents
+ ", fStartTime=" + fStartTime
831 + ", fEndTime=" + fEndTime
+ ", fStreamingInterval=" + fStreamingInterval
+ "]";