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

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2014 Ericsson, École Polytechnique de Montréal
   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  *   Geneviève Bastien  - Added timestamp transforms and timestamp
  13  *                        creation functions
  14  *******************************************************************************/
  15
  16 package org.eclipse.linuxtools.tmf.core.trace;
  17
  18 import org.eclipse.core.resources.IProject;
  19 import org.eclipse.core.resources.IResource;
  20 import org.eclipse.core.runtime.IStatus;
  21 import org.eclipse.jdt.annotation.NonNull;
  22 import org.eclipse.jdt.annotation.Nullable;
  23 import org.eclipse.linuxtools.tmf.core.analysis.IAnalysisModule;
  24 import org.eclipse.linuxtools.tmf.core.component.ITmfEventProvider;
  25 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  26 import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
  27 import org.eclipse.linuxtools.tmf.core.synchronization.ITmfTimestampTransform;
  28 import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
  29 import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimeRange;
  30 import org.eclipse.linuxtools.tmf.core.trace.indexer.ITmfTraceIndexer;
  31 import org.eclipse.linuxtools.tmf.core.trace.location.ITmfLocation;
  32
  33 /**
  34  * The event stream structure in TMF. In its basic form, a trace has:
  35  * <ul>
  36  * <li> an associated Eclipse resource
  37  * <li> a path to its location on the file system
  38  * <li> the type of the events it contains
  39  * <li> the number of events it contains
  40  * <li> the time range (span) of the events it contains
  41  * </ul>
  42  * Concrete ITmfTrace classes have to provide a parameter-less constructor and
  43  * an initialization method (<i>initTrace</i>) if they are to be opened from the
  44  * Project View. Also, a validation method (<i>validate</i>) has to be provided
  45  * to ensure that the trace is of the correct type.
  46  * <p>
  47  * A trace can be accessed simultaneously from multiple threads by various
  48  * application components. To avoid obvious multi-threading issues, the trace
  49  * uses an ITmfContext as a synchronization aid for its read operations.
  50  * <p>
  51  * A proper ITmfContext can be obtained by performing a seek operation on the
  52  * trace. Seek operations can be performed for a particular event (by rank or
  53  * timestamp) or for a plain trace location.
  54  * <p>
  55  * <b>Example 1</b>: Process a whole trace
  56  * <pre>
  57  * ITmfContext context = trace.seekEvent(0);
  58  * ITmfEvent event = trace.getNext(context);
  59  * while (event != null) {
  60  *     processEvent(event);
  61  *     event = trace.getNext(context);
  62  * }
  63  * </pre>
  64  * <b>Example 2</b>: Process 50 events starting from the 1000th event
  65  * <pre>
  66  * int nbEventsRead = 0;
  67  * ITmfContext context = trace.seekEvent(1000);
  68  * ITmfEvent event = trace.getNext(context);
  69  * while (event != null && nbEventsRead < 50) {
  70  *     nbEventsRead++;
  71  *     processEvent(event);
  72  *     event = trace.getNext(context);
  73  * }
  74  * </pre>
  75  * <b>Example 3</b>: Process the events between 2 timestamps (inclusive)
  76  * <pre>
  77  * ITmfTimestamp startTime = ...;
  78  * ITmfTimestamp endTime = ...;
  79  * ITmfContext context = trace.seekEvent(startTime);
  80  * ITmfEvent event = trace.getNext(context);
  81  * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
  82  *     processEvent(event);
  83  *     event = trace.getNext(context);
  84  * }
  85  * </pre>
  86  *
  87  * A trace is also an event provider so it can process event requests
  88  * asynchronously (and coalesce compatible, concurrent requests).
  89  * <p>
  90  *
  91  * <b>Example 4</b>: Process a whole trace (see ITmfEventRequest for
  92  * variants)
  93  * <pre>
  94  * ITmfRequest request = new TmfEventRequest&lt;MyEventType&gt;(MyEventType.class) {
  95  *     &#064;Override
  96  *     public void handleData(MyEventType event) {
  97  *         super.handleData(event);
  98  *         processEvent(event);
  99  *     }
 100  *
 101  *     &#064;Override
 102  *     public void handleCompleted() {
 103  *         finish();
 104  *         super.handleCompleted();
 105  *     }
 106  * };
 107  *
 108  * fTrace.handleRequest(request);
 109  * if (youWant) {
 110  *     request.waitForCompletion();
 111  * }
 112  * </pre>
 113  *
 114  * @version 1.0
 115  * @author Francois Chouinard
 116  *
 117  * @see ITmfContext
 118  * @see ITmfEvent
 119  * @see ITmfTraceIndexer
 120  * @see ITmfEventParser
 121  */
 122 public interface ITmfTrace extends ITmfEventProvider {
 123
 124     // ------------------------------------------------------------------------
 125     // Constants
 126     // ------------------------------------------------------------------------
 127
 128     /**
 129      * The default trace cache size
 130      */
 131     public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
 132
 133     // ------------------------------------------------------------------------
 134     // Initializers
 135     // ------------------------------------------------------------------------
 136
 137     /**
 138      * Initialize a newly instantiated "empty" trace object. This is used to
 139      * properly parameterize an ITmfTrace instantiated with its parameterless
 140      * constructor.
 141      * <p>
 142      * Typically, the parameterless constructor will provide the block size and
 143      * its associated parser and indexer.
 144      *
 145      * @param resource
 146      *            the trace resource
 147      * @param path
 148      *            the trace path
 149      * @param type
 150      *            the trace event type
 151      * @throws TmfTraceException
 152      *             If we couldn't open the trace
 153      */
 154     void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type) throws TmfTraceException;
 155
 156     /**
 157      * Validate that the trace is of the correct type. The implementation should
 158      * return a TraceValidationStatus to indicate success with a certain level
 159      * of confidence.
 160      *
 161      * @param project
 162      *            the eclipse project
 163      * @param path
 164      *            the trace path
 165      *
 166      * @return an IStatus object with validation result. Use severity OK to
 167      *         indicate success.
 168      * @see {@link TraceValidationStatus}
 169      * @since 2.0
 170      */
 171     IStatus validate(IProject project, String path);
 172
 173     // ------------------------------------------------------------------------
 174     // Basic getters
 175     // ------------------------------------------------------------------------
 176
 177     /**
 178      * @return the trace event type
 179      */
 180     Class<? extends ITmfEvent> getEventType();
 181
 182     /**
 183      * @return the associated trace resource
 184      */
 185     IResource getResource();
 186
 187     /**
 188      * @return the trace path
 189      */
 190     String getPath();
 191
 192     /**
 193      * @return the trace cache size
 194      */
 195     int getCacheSize();
 196
 197     /**
 198      * Index the trace. Depending on the trace type, this could be done at the
 199      * constructor or initTrace phase too, so this could be implemented as a
 200      * no-op.
 201      *
 202      * @param waitForCompletion
 203      *            Should we block the caller until indexing is finished, or not.
 204      * @since 2.0
 205      */
 206     void indexTrace(boolean waitForCompletion);
 207
 208     // ------------------------------------------------------------------------
 209     // Analysis getters
 210     // ------------------------------------------------------------------------
 211
 212     /**
 213      * Returns an analysis module with the given ID.
 214      *
 215      * @param id
 216      *            The analysis module ID
 217      * @return The {@link IAnalysisModule} object, or null if an analysis with
 218      *         the given ID does no exist.
 219      * @since 3.0
 220      */
 221     @Nullable
 222     IAnalysisModule getAnalysisModule(String id);
 223
 224     /**
 225      * Get a list of all analysis modules currently available for this trace.
 226      *
 227      * @return An iterable view of the analysis modules
 228      * @since 3.0
 229      */
 230     @NonNull
 231     Iterable<IAnalysisModule> getAnalysisModules();
 232
 233     /**
 234      * Get an analysis module belonging to this trace, with the specified ID and
 235      * class.
 236      *
 237      * @param moduleClass
 238      *            Returned modules must extend this class
 239      * @param id
 240      *            The ID of the analysis module
 241      * @return The analysis module with specified class and ID, or null if no
 242      *         such module exists.
 243      * @since 3.0
 244      */
 245     @Nullable
 246     <T extends IAnalysisModule> T getAnalysisModuleOfClass(Class<T> moduleClass, String id);
 247
 248     /**
 249      * Return the analysis modules that are of a given class. Module are already
 250      * casted to the requested class.
 251      *
 252      * @param moduleClass
 253      *            Returned modules must extend this class
 254      * @return List of modules of class moduleClass
 255      * @since 3.0
 256      */
 257     @NonNull
 258     <T> Iterable<T> getAnalysisModulesOfClass(Class<T> moduleClass);
 259
 260     // ------------------------------------------------------------------------
 261     // Trace characteristics getters
 262     // ------------------------------------------------------------------------
 263
 264     /**
 265      * @return the number of events in the trace
 266      */
 267     long getNbEvents();
 268
 269     /**
 270      * @return the trace time range
 271      * @since 2.0
 272      */
 273     TmfTimeRange getTimeRange();
 274
 275     /**
 276      * @return the timestamp of the first trace event
 277      * @since 2.0
 278      */
 279     ITmfTimestamp getStartTime();
 280
 281     /**
 282      * @return the timestamp of the last trace event
 283      * @since 2.0
 284      */
 285     ITmfTimestamp getEndTime();
 286
 287     /**
 288      * @return the streaming interval in ms (0 if not a streaming trace)
 289      */
 290     long getStreamingInterval();
 291
 292     // ------------------------------------------------------------------------
 293     // Trace positioning getters
 294     // ------------------------------------------------------------------------
 295
 296     /**
 297      * @return the current trace location
 298      * @since 3.0
 299      */
 300     ITmfLocation getCurrentLocation();
 301
 302     /**
 303      * Returns the ratio (proportion) corresponding to the specified location.
 304      *
 305      * @param location
 306      *            a trace specific location
 307      * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 308      * @since 3.0
 309      */
 310     double getLocationRatio(ITmfLocation location);
 311
 312     // ------------------------------------------------------------------------
 313     // SeekEvent operations (returning a trace context)
 314     // ------------------------------------------------------------------------
 315
 316     /**
 317      * Position the trace at the specified (trace specific) location.
 318      * <p>
 319      * A null location is interpreted as seeking for the first event of the
 320      * trace.
 321      * <p>
 322      * If not null, the location requested must be valid otherwise the returned
 323      * context is undefined (up to the implementation to recover if possible).
 324      * <p>
 325      *
 326      * @param location
 327      *            the trace specific location
 328      * @return a context which can later be used to read the corresponding event
 329      * @since 3.0
 330      */
 331     ITmfContext seekEvent(ITmfLocation location);
 332
 333     /**
 334      * Position the trace at the 'rank'th event in the trace.
 335      * <p>
 336      * A rank <= 0 is interpreted as seeking for the first event of the trace.
 337      * <p>
 338      * If the requested rank is beyond the last trace event, the context
 339      * returned will yield a null event if used in a subsequent read.
 340      *
 341      * @param rank
 342      *            the event rank
 343      * @return a context which can later be used to read the corresponding event
 344      */
 345     ITmfContext seekEvent(long rank);
 346
 347     /**
 348      * Position the trace at the first event with the specified timestamp. If
 349      * there is no event with the requested timestamp, a context pointing to the
 350      * next chronological event is returned.
 351      * <p>
 352      * A null timestamp is interpreted as seeking for the first event of the
 353      * trace.
 354      * <p>
 355      * If the requested timestamp is beyond the last trace event, the context
 356      * returned will yield a null event if used in a subsequent read.
 357      *
 358      * @param timestamp
 359      *            the timestamp of desired event
 360      * @return a context which can later be used to read the corresponding event
 361      * @since 2.0
 362      */
 363     ITmfContext seekEvent(ITmfTimestamp timestamp);
 364
 365     /**
 366      * Position the trace at the event located at the specified ratio in the
 367      * trace file.
 368      * <p>
 369      * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
 370      * voluntarily vague. Typically, it would refer to the event proportional
 371      * rank (arguably more intuitive) or timestamp in the trace file.
 372      *
 373      * @param ratio
 374      *            the proportional 'rank' in the trace
 375      * @return a context which can later be used to read the corresponding event
 376      */
 377     ITmfContext seekEvent(double ratio);
 378
 379     /**
 380      * Returns the initial range offset
 381      *
 382      * @return the initial range offset
 383      * @since 2.0
 384      */
 385     ITmfTimestamp getInitialRangeOffset();
 386
 387     /**
 388      * Returns the ID of the host this trace is from. The host ID is not
 389      * necessarily the hostname, but should be a unique identifier for the
 390      * machine on which the trace was taken. It can be used to determine if two
 391      * traces were taken on the exact same machine (timestamp are already
 392      * synchronized, resources with same id are the same if taken at the same
 393      * time, etc).
 394      *
 395      * @return The host id of this trace
 396      * @since 3.0
 397      */
 398     String getHostId();
 399
 400     // ------------------------------------------------------------------------
 401     // Timestamp transformation functions
 402     // ------------------------------------------------------------------------
 403
 404     /**
 405      * Returns the timestamp transformation for this trace
 406      *
 407      * @return the timestamp transform
 408      * @since 3.0
 409      */
 410     ITmfTimestampTransform getTimestampTransform();
 411
 412     /**
 413      * Sets the trace's timestamp transform
 414      *
 415      * @param tt
 416      *            The timestamp transform for all timestamps of this trace
 417      * @since 3.0
 418      */
 419     void setTimestampTransform(final ITmfTimestampTransform tt);
 420
 421     /**
 422      * Creates a timestamp for this trace, using the transformation formula
 423      *
 424      * @param ts
 425      *            The time in long with which to create the timestamp
 426      * @return The new timestamp
 427      * @since 3.0
 428      */
 429     ITmfTimestamp createTimestamp(long ts);
 430
 431 }