org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfTrace.java

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2013 Ericsson
   3  *
   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
   8  *
   9  * Contributors:
  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  *******************************************************************************/
  14
  15 package org.eclipse.linuxtools.tmf.core.trace;
  16
  17 import java.io.File;
  18 import java.util.Collections;
  19 import java.util.LinkedHashMap;
  20 import java.util.Map;
  21
  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.TmfSignalHandler;
  31 import org.eclipse.linuxtools.tmf.core.signal.TmfSignalManager;
  32 import org.eclipse.linuxtools.tmf.core.signal.TmfTraceOpenedSignal;
  33 import org.eclipse.linuxtools.tmf.core.signal.TmfTraceRangeUpdatedSignal;
  34 import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
  35 import org.eclipse.linuxtools.tmf.core.statistics.ITmfStatistics;
  36 import org.eclipse.linuxtools.tmf.core.statistics.TmfStateStatistics;
  37 import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
  38 import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimeRange;
  39 import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestamp;
  40
  41 /**
  42  * Abstract implementation of ITmfTrace.
  43  * <p>
  44  * Since the concept of 'location' is trace specific, the concrete classes have
  45  * to provide the related methods, namely:
  46  * <ul>
  47  * <li> public ITmfLocation<?> getCurrentLocation()
  48  * <li> public double getLocationRatio(ITmfLocation<?> location)
  49  * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
  50  * <li> public ITmfContext seekEvent(double ratio)
  51  * <li> public IStatus validate(IProject project, String path)
  52  * </ul>
  53  * A concrete trace must provide its corresponding parser. A common way to
  54  * accomplish this is by making the concrete class extend TmfTrace and
  55  * implement ITmfEventParser.
  56  * <p>
  57  * The concrete class can either specify its own indexer or use the provided
  58  * TmfCheckpointIndexer (default). In this case, the trace cache size will be
  59  * used as checkpoint interval.
  60  *
  61  * @version 1.0
  62  * @author Francois Chouinard
  63  *
  64  * @see ITmfEvent
  65  * @see ITmfTraceIndexer
  66  * @see ITmfEventParser
  67  */
  68 public abstract class TmfTrace extends TmfEventProvider implements ITmfTrace {
  69
  70     // ------------------------------------------------------------------------
  71     // Attributes
  72     // ------------------------------------------------------------------------
  73
  74     // The resource used for persistent properties for this trace
  75     private IResource fResource;
  76
  77     // The trace path
  78     private String fPath;
  79
  80     // The trace cache page size
  81     private int fCacheSize = ITmfTrace.DEFAULT_TRACE_CACHE_SIZE;
  82
  83     // The number of events collected (so far)
  84     private long fNbEvents = 0;
  85
  86     // The time span of the event stream
  87     private ITmfTimestamp fStartTime = TmfTimestamp.BIG_BANG;
  88     private ITmfTimestamp fEndTime = TmfTimestamp.BIG_BANG;
  89
  90     // The trace streaming interval (0 = no streaming)
  91     private long fStreamingInterval = 0;
  92
  93     // The trace indexer
  94     private ITmfTraceIndexer fIndexer;
  95
  96     // The trace parser
  97     private ITmfEventParser fParser;
  98
  99     // The trace's statistics
 100     private ITmfStatistics fStatistics;
 101
 102     /**
 103      * The collection of state systems that are registered with this trace. Each
 104      * sub-class can decide to add its (one or many) state system to this map
 105      * during their {@link #buildStateSystem()}.
 106      *
 107      * @since 2.0
 108      */
 109     protected final Map<String, ITmfStateSystem> fStateSystems =
 110             new LinkedHashMap<String, ITmfStateSystem>();
 111
 112     // ------------------------------------------------------------------------
 113     // Construction
 114     // ------------------------------------------------------------------------
 115
 116     /**
 117      * The default, parameterless, constructor
 118      */
 119     public TmfTrace() {
 120         super();
 121     }
 122
 123     /**
 124      * Full constructor.
 125      *
 126      * @param resource
 127      *            The resource associated to the trace
 128      * @param type
 129      *            The type of events that will be read from this trace
 130      * @param path
 131      *            The path to the trace on the filesystem
 132      * @param cacheSize
 133      *            The trace cache size. Pass '-1' to use the default specified
 134      *            in {@link ITmfTrace#DEFAULT_TRACE_CACHE_SIZE}
 135      * @param interval
 136      *            The trace streaming interval. You can use '0' for post-mortem
 137      *            traces.
 138      * @param indexer
 139      *            The trace indexer. You can pass 'null' to use a default
 140      *            checkpoint indexer.
 141      * @param parser
 142      *            The trace event parser. Use 'null' if (and only if) the trace
 143      *            object itself is also the ITmfEventParser to be used.
 144      * @throws TmfTraceException
 145      *             If something failed during the opening
 146      */
 147     protected TmfTrace(final IResource resource,
 148             final Class<? extends ITmfEvent> type,
 149             final String path,
 150             final int cacheSize,
 151             final long interval,
 152             final ITmfTraceIndexer indexer,
 153             final ITmfEventParser parser)
 154                     throws TmfTraceException {
 155         super();
 156         fCacheSize = (cacheSize > 0) ? cacheSize : ITmfTrace.DEFAULT_TRACE_CACHE_SIZE;
 157         fStreamingInterval = interval;
 158         fIndexer = (indexer != null) ? indexer : new TmfCheckpointIndexer(this, fCacheSize);
 159         fParser = parser;
 160         initialize(resource, path, type);
 161     }
 162
 163     /**
 164      * Copy constructor
 165      *
 166      * @param trace the original trace
 167      * @throws TmfTraceException Should not happen usually
 168      */
 169     public TmfTrace(final TmfTrace trace) throws TmfTraceException {
 170         super();
 171         if (trace == null) {
 172             throw new IllegalArgumentException();
 173         }
 174         fCacheSize = trace.getCacheSize();
 175         fStreamingInterval = trace.getStreamingInterval();
 176         fIndexer = new TmfCheckpointIndexer(this);
 177         fParser = trace.fParser;
 178         initialize(trace.getResource(), trace.getPath(), trace.getEventType());
 179     }
 180
 181     // ------------------------------------------------------------------------
 182     // ITmfTrace - Initializers
 183     // ------------------------------------------------------------------------
 184
 185     @Override
 186     public void initTrace(final IResource resource, final String path, final Class<? extends ITmfEvent> type) throws TmfTraceException {
 187         fIndexer = new TmfCheckpointIndexer(this, fCacheSize);
 188         initialize(resource, path, type);
 189     }
 190
 191     /**
 192      * Initialize the trace common attributes and the base component.
 193      *
 194      * @param resource the Eclipse resource (trace)
 195      * @param path the trace path
 196      * @param type the trace event type
 197      *
 198      * @throws TmfTraceException If something failed during the initialization
 199      */
 200     protected void initialize(final IResource resource,
 201             final String path,
 202             final Class<? extends ITmfEvent> type)
 203                     throws TmfTraceException {
 204         if (path == null) {
 205             throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
 206         }
 207         fPath = path;
 208         fResource = resource;
 209         String traceName = (resource != null) ? resource.getName() : null;
 210         // If no resource was provided, extract the display name the trace path
 211         if (traceName == null) {
 212             final int sep = path.lastIndexOf(IPath.SEPARATOR);
 213             traceName = (sep >= 0) ? path.substring(sep + 1) : path;
 214         }
 215         if (fParser == null) {
 216             if (this instanceof ITmfEventParser) {
 217                 fParser = (ITmfEventParser) this;
 218             } else {
 219                 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
 220             }
 221         }
 222         super.init(traceName, type);
 223         // register as VIP after super.init() because TmfComponent registers to signal manager there
 224         TmfSignalManager.registerVIP(this);
 225     }
 226
 227     /**
 228      * Indicates if the path points to an existing file/directory
 229      *
 230      * @param path the path to test
 231      * @return true if the file/directory exists
 232      */
 233     protected boolean fileExists(final String path) {
 234         final File file = new File(path);
 235         return file.exists();
 236     }
 237
 238     /**
 239      * @since 2.0
 240      */
 241     @Override
 242     public void indexTrace(boolean waitForCompletion) {
 243         getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, waitForCompletion);
 244     }
 245
 246     /**
 247      * The default implementation of TmfTrace uses a TmfStatistics back-end.
 248      * Override this if you want to specify another type (or none at all).
 249      *
 250      * @throws TmfTraceException
 251      *             If there was a problem setting up the statistics
 252      * @since 2.0
 253      */
 254     protected void buildStatistics() throws TmfTraceException {
 255         /*
 256          * Initialize the statistics provider, but only if a Resource has been
 257          * set (so we don't build it for experiments, for unit tests, etc.)
 258          */
 259         fStatistics = (fResource == null ? null : new TmfStateStatistics(this) );
 260     }
 261
 262     /**
 263      * Build the state system(s) associated with this trace type.
 264      *
 265      * Suppressing the warning, because the 'throws' will usually happen in
 266      * sub-classes.
 267      *
 268      * @throws TmfTraceException
 269      *             If there is a problem during the build
 270      * @since 2.0
 271      */
 272     @SuppressWarnings("unused")
 273     protected void buildStateSystem() throws TmfTraceException {
 274         /*
 275          * Nothing is done in the base implementation, please specify
 276          * how/if to register a new state system in derived classes.
 277          */
 278         return;
 279     }
 280
 281     /**
 282      * Clears the trace
 283      */
 284     @Override
 285     public synchronized void dispose() {
 286         /* Clean up the index if applicable */
 287         if (getIndexer() != null) {
 288             getIndexer().dispose();
 289         }
 290
 291         /* Clean up the statistics */
 292         if (fStatistics != null) {
 293             fStatistics.dispose();
 294         }
 295
 296         /* Clean up the state systems */
 297         for (ITmfStateSystem ss : fStateSystems.values()) {
 298             ss.dispose();
 299         }
 300
 301         super.dispose();
 302     }
 303
 304     // ------------------------------------------------------------------------
 305     // ITmfTrace - Basic getters
 306     // ------------------------------------------------------------------------
 307
 308     @Override
 309     public Class<ITmfEvent> getEventType() {
 310         return (Class<ITmfEvent>) super.getType();
 311     }
 312
 313     @Override
 314     public IResource getResource() {
 315         return fResource;
 316     }
 317
 318     @Override
 319     public String getPath() {
 320         return fPath;
 321     }
 322
 323     @Override
 324     public int getCacheSize() {
 325         return fCacheSize;
 326     }
 327
 328     @Override
 329     public long getStreamingInterval() {
 330         return fStreamingInterval;
 331     }
 332
 333     /**
 334      * @return the trace indexer
 335      */
 336     protected ITmfTraceIndexer getIndexer() {
 337         return fIndexer;
 338     }
 339
 340     /**
 341      * @return the trace parser
 342      */
 343     protected ITmfEventParser getParser() {
 344         return fParser;
 345     }
 346
 347     /**
 348      * @since 2.0
 349      */
 350     @Override
 351     public ITmfStatistics getStatistics() {
 352         return fStatistics;
 353     }
 354
 355     /**
 356      * @since 2.0
 357      */
 358     @Override
 359     public final Map<String, ITmfStateSystem> getStateSystems() {
 360         return Collections.unmodifiableMap(fStateSystems);
 361     }
 362
 363     /**
 364      * @since 2.0
 365      */
 366     @Override
 367     public final void registerStateSystem(String id, ITmfStateSystem ss) {
 368         fStateSystems.put(id, ss);
 369     }
 370
 371     // ------------------------------------------------------------------------
 372     // ITmfTrace - Trace characteristics getters
 373     // ------------------------------------------------------------------------
 374
 375     @Override
 376     public synchronized long getNbEvents() {
 377         return fNbEvents;
 378     }
 379
 380     /**
 381      * @since 2.0
 382      */
 383     @Override
 384     public TmfTimeRange getTimeRange() {
 385         return new TmfTimeRange(fStartTime, fEndTime);
 386     }
 387
 388     /**
 389      * @since 2.0
 390      */
 391     @Override
 392     public ITmfTimestamp getStartTime() {
 393         return fStartTime;
 394     }
 395
 396     /**
 397      * @since 2.0
 398      */
 399     @Override
 400     public ITmfTimestamp getEndTime() {
 401         return fEndTime;
 402     }
 403
 404     /**
 405      * @since 2.0
 406      */
 407     @Override
 408     public ITmfTimestamp getInitialRangeOffset() {
 409         final long DEFAULT_INITIAL_OFFSET_VALUE = (1L * 100 * 1000 * 1000); // .1sec
 410         return new TmfTimestamp(DEFAULT_INITIAL_OFFSET_VALUE, ITmfTimestamp.NANOSECOND_SCALE);
 411     }
 412
 413     /**
 414      * @since 3.0
 415      */
 416     @Override
 417     public String getHostId() {
 418         return this.getName();
 419     }
 420
 421     // ------------------------------------------------------------------------
 422     // Convenience setters
 423     // ------------------------------------------------------------------------
 424
 425     /**
 426      * Set the trace cache size. Must be done at initialization time.
 427      *
 428      * @param cacheSize The trace cache size
 429      */
 430     protected void setCacheSize(final int cacheSize) {
 431         fCacheSize = cacheSize;
 432     }
 433
 434     /**
 435      * Set the trace known number of events. This can be quite dynamic
 436      * during indexing or for live traces.
 437      *
 438      * @param nbEvents The number of events
 439      */
 440     protected synchronized void setNbEvents(final long nbEvents) {
 441         fNbEvents = (nbEvents > 0) ? nbEvents : 0;
 442     }
 443
 444     /**
 445      * Update the trace events time range
 446      *
 447      * @param range the new time range
 448      * @since 2.0
 449      */
 450     protected void setTimeRange(final TmfTimeRange range) {
 451         fStartTime = range.getStartTime();
 452         fEndTime = range.getEndTime();
 453     }
 454
 455     /**
 456      * Update the trace chronologically first event timestamp
 457      *
 458      * @param startTime the new first event timestamp
 459      * @since 2.0
 460      */
 461     protected void setStartTime(final ITmfTimestamp startTime) {
 462         fStartTime = startTime;
 463     }
 464
 465     /**
 466      * Update the trace chronologically last event timestamp
 467      *
 468      * @param endTime the new last event timestamp
 469      * @since 2.0
 470      */
 471     protected void setEndTime(final ITmfTimestamp endTime) {
 472         fEndTime = endTime;
 473     }
 474
 475     /**
 476      * Set the polling interval for live traces (default = 0 = no streaming).
 477      *
 478      * @param interval the new trace streaming interval
 479      */
 480     protected void setStreamingInterval(final long interval) {
 481         fStreamingInterval = (interval > 0) ? interval : 0;
 482     }
 483
 484     /**
 485      * Set the trace indexer. Must be done at initialization time.
 486      *
 487      * @param indexer the trace indexer
 488      */
 489     protected void setIndexer(final ITmfTraceIndexer indexer) {
 490         fIndexer = indexer;
 491     }
 492
 493     /**
 494      * Set the trace parser. Must be done at initialization time.
 495      *
 496      * @param parser the new trace parser
 497      */
 498     protected void setParser(final ITmfEventParser parser) {
 499         fParser = parser;
 500     }
 501
 502     // ------------------------------------------------------------------------
 503     // ITmfTrace - SeekEvent operations (returning a trace context)
 504     // ------------------------------------------------------------------------
 505
 506     @Override
 507     public synchronized ITmfContext seekEvent(final long rank) {
 508
 509         // A rank <= 0 indicates to seek the first event
 510         if (rank <= 0) {
 511             ITmfContext context = seekEvent((ITmfLocation) null);
 512             context.setRank(0);
 513             return context;
 514         }
 515
 516         // Position the trace at the checkpoint
 517         final ITmfContext context = fIndexer.seekIndex(rank);
 518
 519         // And locate the requested event context
 520         long pos = context.getRank();
 521         if (pos < rank) {
 522             ITmfEvent event = getNext(context);
 523             while ((event != null) && (++pos < rank)) {
 524                 event = getNext(context);
 525             }
 526         }
 527         return context;
 528     }
 529
 530     /**
 531      * @since 2.0
 532      */
 533     @Override
 534     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 535
 536         // A null timestamp indicates to seek the first event
 537         if (timestamp == null) {
 538             ITmfContext context = seekEvent((ITmfLocation) null);
 539             context.setRank(0);
 540             return context;
 541         }
 542
 543         // Position the trace at the checkpoint
 544         ITmfContext context = fIndexer.seekIndex(timestamp);
 545
 546         // And locate the requested event context
 547         ITmfLocation previousLocation = context.getLocation();
 548         long previousRank = context.getRank();
 549         ITmfEvent event = getNext(context);
 550         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 551             previousLocation = context.getLocation();
 552             previousRank = context.getRank();
 553             event = getNext(context);
 554         }
 555         if (event == null) {
 556             context.setLocation(null);
 557             context.setRank(ITmfContext.UNKNOWN_RANK);
 558         } else {
 559             context.dispose();
 560             context = seekEvent(previousLocation);
 561             context.setRank(previousRank);
 562         }
 563         return context;
 564     }
 565
 566     // ------------------------------------------------------------------------
 567     // ITmfTrace - Read operations (returning an actual event)
 568     // ------------------------------------------------------------------------
 569
 570     @Override
 571     public synchronized ITmfEvent getNext(final ITmfContext context) {
 572         // parseEvent() does not update the context
 573         final ITmfEvent event = fParser.parseEvent(context);
 574         if (event != null) {
 575             updateAttributes(context, event.getTimestamp());
 576             context.setLocation(getCurrentLocation());
 577             context.increaseRank();
 578             processEvent(event);
 579         }
 580         return event;
 581     }
 582
 583     /**
 584      * Hook for special event processing by the concrete class
 585      * (called by TmfTrace.getEvent())
 586      *
 587      * @param event the event
 588      */
 589     protected void processEvent(final ITmfEvent event) {
 590         // Do nothing
 591     }
 592
 593     /**
 594      * Update the trace attributes
 595      *
 596      * @param context the current trace context
 597      * @param timestamp the corresponding timestamp
 598      * @since 2.0
 599      */
 600     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 601         if (fStartTime.equals(TmfTimestamp.BIG_BANG) || (fStartTime.compareTo(timestamp, false) > 0)) {
 602             fStartTime = timestamp;
 603         }
 604         if (fEndTime.equals(TmfTimestamp.BIG_CRUNCH) || (fEndTime.compareTo(timestamp, false) < 0)) {
 605             fEndTime = timestamp;
 606         }
 607         if (context.hasValidRank()) {
 608             long rank = context.getRank();
 609             if (fNbEvents <= rank) {
 610                 fNbEvents = rank + 1;
 611             }
 612             if (fIndexer != null) {
 613                 fIndexer.updateIndex(context, timestamp);
 614             }
 615         }
 616     }
 617
 618     // ------------------------------------------------------------------------
 619     // TmfDataProvider
 620     // ------------------------------------------------------------------------
 621
 622     /**
 623      * @since 2.0
 624      */
 625     @Override
 626     public synchronized ITmfContext armRequest(final ITmfDataRequest request) {
 627         if (executorIsShutdown()) {
 628             return null;
 629         }
 630         if ((request instanceof ITmfEventRequest)
 631             && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest) request).getRange().getStartTime())
 632             && (request.getIndex() == 0))
 633         {
 634             final ITmfContext context = seekEvent(((ITmfEventRequest) request).getRange().getStartTime());
 635             ((ITmfEventRequest) request).setStartIndex((int) context.getRank());
 636             return context;
 637
 638         }
 639         return seekEvent(request.getIndex());
 640     }
 641
 642     // ------------------------------------------------------------------------
 643     // Signal handlers
 644     // ------------------------------------------------------------------------
 645
 646     /**
 647      * Handler for the Trace Opened signal
 648      *
 649      * @param signal
 650      *            The incoming signal
 651      * @since 2.0
 652      */
 653     @TmfSignalHandler
 654     public void traceOpened(TmfTraceOpenedSignal signal) {
 655         boolean signalIsForUs = false;
 656         for (ITmfTrace trace : TmfTraceManager.getTraceSet(signal.getTrace())) {
 657             if (trace == this) {
 658                 signalIsForUs = true;
 659                 break;
 660             }
 661         }
 662
 663         if (!signalIsForUs) {
 664             return;
 665         }
 666
 667         /*
 668          * The signal is either for this trace, or for an experiment containing
 669          * this trace.
 670          */
 671         try {
 672             buildStatistics();
 673             buildStateSystem();
 674         } catch (TmfTraceException e) {
 675             e.printStackTrace();
 676         }
 677
 678         /* Refresh the project, so it can pick up new files that got created. */
 679         try {
 680             if (fResource != null) {
 681                 fResource.getProject().refreshLocal(IResource.DEPTH_INFINITE, null);
 682             }
 683         } catch (CoreException e) {
 684             e.printStackTrace();
 685         }
 686
 687         if (signal.getTrace() == this) {
 688             /* Additionally, the signal is directly for this trace. */
 689             if (getNbEvents() == 0) {
 690                 return;
 691             }
 692
 693             /* For a streaming trace, the range updated signal should be sent
 694              * by the subclass when a new safe time is determined.
 695              */
 696             if (getStreamingInterval() > 0) {
 697                 return;
 698             }
 699
 700             final TmfTimeRange timeRange = new TmfTimeRange(getStartTime(), TmfTimestamp.BIG_CRUNCH);
 701             final TmfTraceRangeUpdatedSignal rangeUpdatedsignal = new TmfTraceRangeUpdatedSignal(this, this, timeRange);
 702
 703             // Broadcast in separate thread to prevent deadlock
 704             new Thread() {
 705                 @Override
 706                 public void run() {
 707                     broadcast(rangeUpdatedsignal);
 708                 }
 709             }.start();
 710             return;
 711         }
 712     }
 713
 714     /**
 715      * Signal handler for the TmfTraceRangeUpdatedSignal signal
 716      *
 717      * @param signal The incoming signal
 718      * @since 2.0
 719      */
 720     @TmfSignalHandler
 721     public void traceRangeUpdated(final TmfTraceRangeUpdatedSignal signal) {
 722         if (signal.getTrace() == this) {
 723             getIndexer().buildIndex(getNbEvents(), signal.getRange(), false);
 724         }
 725     }
 726
 727     // ------------------------------------------------------------------------
 728     // toString
 729     // ------------------------------------------------------------------------
 730
 731     @Override
 732     @SuppressWarnings("nls")
 733     public synchronized String toString() {
 734         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 735                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 736                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 737     }
 738
 739 }