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     // Convenience setters
 415     // ------------------------------------------------------------------------
 416
 417     /**
 418      * Set the trace cache size. Must be done at initialization time.
 419      *
 420      * @param cacheSize The trace cache size
 421      */
 422     protected void setCacheSize(final int cacheSize) {
 423         fCacheSize = cacheSize;
 424     }
 425
 426     /**
 427      * Set the trace known number of events. This can be quite dynamic
 428      * during indexing or for live traces.
 429      *
 430      * @param nbEvents The number of events
 431      */
 432     protected synchronized void setNbEvents(final long nbEvents) {
 433         fNbEvents = (nbEvents > 0) ? nbEvents : 0;
 434     }
 435
 436     /**
 437      * Update the trace events time range
 438      *
 439      * @param range the new time range
 440      * @since 2.0
 441      */
 442     protected void setTimeRange(final TmfTimeRange range) {
 443         fStartTime = range.getStartTime();
 444         fEndTime = range.getEndTime();
 445     }
 446
 447     /**
 448      * Update the trace chronologically first event timestamp
 449      *
 450      * @param startTime the new first event timestamp
 451      * @since 2.0
 452      */
 453     protected void setStartTime(final ITmfTimestamp startTime) {
 454         fStartTime = startTime;
 455     }
 456
 457     /**
 458      * Update the trace chronologically last event timestamp
 459      *
 460      * @param endTime the new last event timestamp
 461      * @since 2.0
 462      */
 463     protected void setEndTime(final ITmfTimestamp endTime) {
 464         fEndTime = endTime;
 465     }
 466
 467     /**
 468      * Set the polling interval for live traces (default = 0 = no streaming).
 469      *
 470      * @param interval the new trace streaming interval
 471      */
 472     protected void setStreamingInterval(final long interval) {
 473         fStreamingInterval = (interval > 0) ? interval : 0;
 474     }
 475
 476     /**
 477      * Set the trace indexer. Must be done at initialization time.
 478      *
 479      * @param indexer the trace indexer
 480      */
 481     protected void setIndexer(final ITmfTraceIndexer indexer) {
 482         fIndexer = indexer;
 483     }
 484
 485     /**
 486      * Set the trace parser. Must be done at initialization time.
 487      *
 488      * @param parser the new trace parser
 489      */
 490     protected void setParser(final ITmfEventParser parser) {
 491         fParser = parser;
 492     }
 493
 494     // ------------------------------------------------------------------------
 495     // ITmfTrace - SeekEvent operations (returning a trace context)
 496     // ------------------------------------------------------------------------
 497
 498     @Override
 499     public synchronized ITmfContext seekEvent(final long rank) {
 500
 501         // A rank <= 0 indicates to seek the first event
 502         if (rank <= 0) {
 503             ITmfContext context = seekEvent((ITmfLocation) null);
 504             context.setRank(0);
 505             return context;
 506         }
 507
 508         // Position the trace at the checkpoint
 509         final ITmfContext context = fIndexer.seekIndex(rank);
 510
 511         // And locate the requested event context
 512         long pos = context.getRank();
 513         if (pos < rank) {
 514             ITmfEvent event = getNext(context);
 515             while ((event != null) && (++pos < rank)) {
 516                 event = getNext(context);
 517             }
 518         }
 519         return context;
 520     }
 521
 522     /**
 523      * @since 2.0
 524      */
 525     @Override
 526     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 527
 528         // A null timestamp indicates to seek the first event
 529         if (timestamp == null) {
 530             ITmfContext context = seekEvent((ITmfLocation) null);
 531             context.setRank(0);
 532             return context;
 533         }
 534
 535         // Position the trace at the checkpoint
 536         ITmfContext context = fIndexer.seekIndex(timestamp);
 537
 538         // And locate the requested event context
 539         ITmfLocation previousLocation = context.getLocation();
 540         long previousRank = context.getRank();
 541         ITmfEvent event = getNext(context);
 542         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 543             previousLocation = context.getLocation();
 544             previousRank = context.getRank();
 545             event = getNext(context);
 546         }
 547         if (event == null) {
 548             context.setLocation(null);
 549             context.setRank(ITmfContext.UNKNOWN_RANK);
 550         } else {
 551             context.dispose();
 552             context = seekEvent(previousLocation);
 553             context.setRank(previousRank);
 554         }
 555         return context;
 556     }
 557
 558     // ------------------------------------------------------------------------
 559     // ITmfTrace - Read operations (returning an actual event)
 560     // ------------------------------------------------------------------------
 561
 562     @Override
 563     public synchronized ITmfEvent getNext(final ITmfContext context) {
 564         // parseEvent() does not update the context
 565         final ITmfEvent event = fParser.parseEvent(context);
 566         if (event != null) {
 567             updateAttributes(context, event.getTimestamp());
 568             context.setLocation(getCurrentLocation());
 569             context.increaseRank();
 570             processEvent(event);
 571         }
 572         return event;
 573     }
 574
 575     /**
 576      * Hook for special event processing by the concrete class
 577      * (called by TmfTrace.getEvent())
 578      *
 579      * @param event the event
 580      */
 581     protected void processEvent(final ITmfEvent event) {
 582         // Do nothing
 583     }
 584
 585     /**
 586      * Update the trace attributes
 587      *
 588      * @param context the current trace context
 589      * @param timestamp the corresponding timestamp
 590      * @since 2.0
 591      */
 592     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 593         if (fStartTime.equals(TmfTimestamp.BIG_BANG) || (fStartTime.compareTo(timestamp, false) > 0)) {
 594             fStartTime = timestamp;
 595         }
 596         if (fEndTime.equals(TmfTimestamp.BIG_CRUNCH) || (fEndTime.compareTo(timestamp, false) < 0)) {
 597             fEndTime = timestamp;
 598         }
 599         if (context.hasValidRank()) {
 600             long rank = context.getRank();
 601             if (fNbEvents <= rank) {
 602                 fNbEvents = rank + 1;
 603             }
 604             if (fIndexer != null) {
 605                 fIndexer.updateIndex(context, timestamp);
 606             }
 607         }
 608     }
 609
 610     // ------------------------------------------------------------------------
 611     // TmfDataProvider
 612     // ------------------------------------------------------------------------
 613
 614     /**
 615      * @since 2.0
 616      */
 617     @Override
 618     public synchronized ITmfContext armRequest(final ITmfDataRequest request) {
 619         if (executorIsShutdown()) {
 620             return null;
 621         }
 622         if ((request instanceof ITmfEventRequest)
 623             && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest) request).getRange().getStartTime())
 624             && (request.getIndex() == 0))
 625         {
 626             final ITmfContext context = seekEvent(((ITmfEventRequest) request).getRange().getStartTime());
 627             ((ITmfEventRequest) request).setStartIndex((int) context.getRank());
 628             return context;
 629
 630         }
 631         return seekEvent(request.getIndex());
 632     }
 633
 634     // ------------------------------------------------------------------------
 635     // Signal handlers
 636     // ------------------------------------------------------------------------
 637
 638     /**
 639      * Handler for the Trace Opened signal
 640      *
 641      * @param signal
 642      *            The incoming signal
 643      * @since 2.0
 644      */
 645     @TmfSignalHandler
 646     public void traceOpened(TmfTraceOpenedSignal signal) {
 647         boolean signalIsForUs = false;
 648         for (ITmfTrace trace : TmfTraceManager.getTraceSet(signal.getTrace())) {
 649             if (trace == this) {
 650                 signalIsForUs = true;
 651                 break;
 652             }
 653         }
 654
 655         if (!signalIsForUs) {
 656             return;
 657         }
 658
 659         /*
 660          * The signal is either for this trace, or for an experiment containing
 661          * this trace.
 662          */
 663         try {
 664             buildStatistics();
 665             buildStateSystem();
 666         } catch (TmfTraceException e) {
 667             e.printStackTrace();
 668         }
 669
 670         /* Refresh the project, so it can pick up new files that got created. */
 671         try {
 672             if (fResource != null) {
 673                 fResource.getProject().refreshLocal(IResource.DEPTH_INFINITE, null);
 674             }
 675         } catch (CoreException e) {
 676             e.printStackTrace();
 677         }
 678
 679         if (signal.getTrace() == this) {
 680             /* Additionally, the signal is directly for this trace. */
 681             if (getNbEvents() == 0) {
 682                 return;
 683             }
 684
 685             /* For a streaming trace, the range updated signal should be sent
 686              * by the subclass when a new safe time is determined.
 687              */
 688             if (getStreamingInterval() > 0) {
 689                 return;
 690             }
 691
 692             final TmfTimeRange timeRange = new TmfTimeRange(getStartTime(), TmfTimestamp.BIG_CRUNCH);
 693             final TmfTraceRangeUpdatedSignal rangeUpdatedsignal = new TmfTraceRangeUpdatedSignal(this, this, timeRange);
 694
 695             // Broadcast in separate thread to prevent deadlock
 696             new Thread() {
 697                 @Override
 698                 public void run() {
 699                     broadcast(rangeUpdatedsignal);
 700                 }
 701             }.start();
 702             return;
 703         }
 704     }
 705
 706     /**
 707      * Signal handler for the TmfTraceRangeUpdatedSignal signal
 708      *
 709      * @param signal The incoming signal
 710      * @since 2.0
 711      */
 712     @TmfSignalHandler
 713     public void traceRangeUpdated(final TmfTraceRangeUpdatedSignal signal) {
 714         if (signal.getTrace() == this) {
 715             getIndexer().buildIndex(getNbEvents(), signal.getRange(), false);
 716         }
 717     }
 718
 719     // ------------------------------------------------------------------------
 720     // toString
 721     // ------------------------------------------------------------------------
 722
 723     @Override
 724     @SuppressWarnings("nls")
 725     public synchronized String toString() {
 726         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 727                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 728                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 729     }
 730
 731 }