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

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2011, 2012 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  *******************************************************************************/
  13
  14 package org.eclipse.linuxtools.tmf.core.trace;
  15
  16 import org.eclipse.core.resources.IProject;
  17 import org.eclipse.core.resources.IResource;
  18 import org.eclipse.linuxtools.tmf.core.component.ITmfDataProvider;
  19 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  20 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  21 import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
  22 import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
  23 import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
  24 import org.eclipse.linuxtools.tmf.core.statistics.ITmfStatistics;
  25
  26 /**
  27  * The event stream structure in TMF. In its basic form, a trace has:
  28  * <ul>
  29  * <li> an associated Eclipse resource
  30  * <li> a path to its location on the file system
  31  * <li> the type of the events it contains
  32  * <li> the number of events it contains
  33  * <li> the time range (span) of the events it contains
  34  * </ul>
  35  * Concrete ITmfTrace classes have to provide a parameter-less constructor and
  36  * an initialization method (<i>initTrace</i>) if they are to be opened from
  37  * the Project View. Also, a validation method (<i>validate</i>) has to be
  38  * provided to ensure that the trace is of the correct type.
  39  * <p>
  40  * A trace can be accessed simultaneously from multiple threads by various
  41  * application components. To avoid obvious multi-threading issues, the trace
  42  * uses an ITmfContext as a synchronization aid for its read operations.
  43  * <p>
  44  * A proper ITmfContext can be obtained by performing a seek operation on the
  45  * trace. Seek operations can be performed for a particular event (by rank or
  46  * timestamp) or for a plain trace location.
  47  * <p>
  48  * <b>Example 1</b>: Process a whole trace
  49  * <pre>
  50  * ITmfContext context = trace.seekEvent(0);
  51  * ITmfEvent event = trace.getNext(context);
  52  * while (event != null) {
  53  *     processEvent(event);
  54  *     event = trace.getNext(context);
  55  * }
  56  * </pre>
  57  * <b>Example 2</b>: Process 50 events starting from the 1000th event
  58  * <pre>
  59  * int nbEventsRead = 0;
  60  * ITmfContext context = trace.seekEvent(1000);
  61  * ITmfEvent event = trace.getNext(context);
  62  * while (event != null && nbEventsRead < 50) {
  63  *     nbEventsRead++;
  64  *     processEvent(event);
  65  *     event = trace.getNext(context);
  66  * }
  67  * </pre>
  68  * <b>Example 3</b>: Process the events between 2 timestamps (inclusive)
  69  * <pre>
  70  * ITmfTimestamp startTime = ...;
  71  * ITmfTimestamp endTime = ...;
  72  * ITmfContext context = trace.seekEvent(startTime);
  73  * ITmfEvent event = trace.getNext(context);
  74  * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
  75  *     processEvent(event);
  76  *     event = trace.getNext(context);
  77  * }
  78  * </pre>
  79  * A trace is also an event provider so it can process event requests
  80  * asynchronously (and coalesce compatible, concurrent requests).
  81  * <p>
  82  * </pre>
  83  * <b>Example 4</b>: Process a whole trace (see ITmfEventRequest for variants)
  84  * <pre>
  85  * ITmfRequest request = new TmfEventRequest&lt;MyEventType&gt;(MyEventType.class) {
  86  *     &#64;Override
  87  *     public void handleData(MyEventType event) {
  88  *         super.handleData(event);
  89  *         processEvent(event);
  90  *     }
  91  *     &#64;Override
  92  *     public void handleCompleted() {
  93  *         finish();
  94  *         super.handleCompleted();
  95  *     }
  96  * };
  97  *
  98  * fTrace.handleRequest(request);
  99  * if (youWant) {
 100  *     request.waitForCompletion();
 101  * }
 102  * </pre>
 103  *
 104  * @version 1.0
 105  * @author Francois Chouinard
 106  *
 107  * @see ITmfContext
 108  * @see ITmfEvent
 109  * @see ITmfTraceIndexer
 110  * @see ITmfEventParser
 111  */
 112 public interface ITmfTrace extends ITmfDataProvider {
 113
 114     // ------------------------------------------------------------------------
 115     // Constants
 116     // ------------------------------------------------------------------------
 117
 118     /**
 119      * The default trace cache size
 120      */
 121     public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
 122
 123     // ------------------------------------------------------------------------
 124     // Initializers
 125     // ------------------------------------------------------------------------
 126
 127     /**
 128      * Initialize a newly instantiated "empty" trace object. This is used to
 129      * properly parameterize an ITmfTrace instantiated with its parameterless
 130      * constructor.
 131      * <p>
 132      * Typically, the parameterless constructor will provide the block size
 133      * and its associated parser and indexer.
 134      *
 135      * @param resource the trace resource
 136      * @param path the trace path
 137      * @param type the trace event type
 138      * @throws TmfTraceException If we couldn't open the trace
 139      */
 140     public void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type) throws TmfTraceException;
 141
 142     /**
 143      * Validate that the trace is of the correct type.
 144      *
 145      * @param project the eclipse project
 146      * @param path the trace path
 147      *
 148      * @return true if trace is valid
 149      */
 150     public boolean validate(IProject project, String path);
 151
 152     // ------------------------------------------------------------------------
 153     // Basic getters
 154     // ------------------------------------------------------------------------
 155
 156     /**
 157      * @return the trace event type
 158      */
 159     public Class<? extends ITmfEvent> getEventType();
 160
 161     /**
 162      * @return the associated trace resource
 163      */
 164     public IResource getResource();
 165
 166     /**
 167      * @return the trace path
 168      */
 169     public String getPath();
 170
 171     /**
 172      * @return the trace cache size
 173      */
 174     public int getCacheSize();
 175
 176     /**
 177      * @return The statistics provider for this trace
 178      * @since 2.0
 179      */
 180     public ITmfStatistics getStatistics();
 181
 182     /**
 183      * @return The state system that is associated with this trace
 184      * @since 2.0
 185      */
 186     public ITmfStateSystem getStateSystem();
 187
 188     // ------------------------------------------------------------------------
 189     // Trace characteristics getters
 190     // ------------------------------------------------------------------------
 191
 192     /**
 193      * @return the number of events in the trace
 194      */
 195     public long getNbEvents();
 196
 197     /**
 198      * @return the trace time range
 199      */
 200     public TmfTimeRange getTimeRange();
 201
 202     /**
 203      * @return the timestamp of the first trace event
 204      */
 205     public ITmfTimestamp getStartTime();
 206
 207     /**
 208      * @return the timestamp of the last trace event
 209      */
 210     public ITmfTimestamp getEndTime();
 211
 212     /**
 213      * @return the streaming interval in ms (0 if not a streaming trace)
 214      */
 215     public long getStreamingInterval();
 216
 217     // ------------------------------------------------------------------------
 218     // Trace positioning getters
 219     // ------------------------------------------------------------------------
 220
 221     /**
 222      * @return the current trace location
 223      */
 224     public ITmfLocation getCurrentLocation();
 225
 226     /**
 227      * Returns the ratio (proportion) corresponding to the specified location.
 228      *
 229      * @param location a trace specific location
 230      * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 231      */
 232     public double getLocationRatio(ITmfLocation location);
 233
 234     // ------------------------------------------------------------------------
 235     // SeekEvent operations (returning a trace context)
 236     // ------------------------------------------------------------------------
 237
 238     /**
 239      * Position the trace at the specified (trace specific) location.
 240      * <p>
 241      * A null location is interpreted as seeking for the first event of the
 242      * trace.
 243      * <p>
 244      * If not null, the location requested must be valid otherwise the returned
 245      * context is undefined (up to the implementation to recover if possible).
 246      * <p>
 247      * @param location the trace specific location
 248      * @return a context which can later be used to read the corresponding event
 249      */
 250     public ITmfContext seekEvent(ITmfLocation location);
 251
 252     /**
 253      * Position the trace at the 'rank'th event in the trace.
 254      * <p>
 255      * A rank <= 0 is interpreted as seeking for the first event of the
 256      * trace.
 257      * <p>
 258      * If the requested rank is beyond the last trace event, the context
 259      * returned will yield a null event if used in a subsequent read.
 260      *
 261      * @param rank the event rank
 262      * @return a context which can later be used to read the corresponding event
 263      */
 264     public ITmfContext seekEvent(long rank);
 265
 266     /**
 267      * Position the trace at the first event with the specified timestamp. If
 268      * there is no event with the requested timestamp, a context pointing to
 269      * the next chronological event is returned.
 270      * <p>
 271      * A null timestamp is interpreted as seeking for the first event of the
 272      * trace.
 273      * <p>
 274      * If the requested timestamp is beyond the last trace event, the context
 275      * returned will yield a null event if used in a subsequent read.
 276      *
 277      * @param timestamp the timestamp of desired event
 278      * @return a context which can later be used to read the corresponding event
 279      */
 280     public ITmfContext seekEvent(ITmfTimestamp timestamp);
 281
 282     /**
 283      * Position the trace at the event located at the specified ratio in the
 284      * trace file.
 285      * <p>
 286      * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
 287      * voluntarily vague. Typically, it would refer to the event proportional
 288      * rank (arguably more intuitive) or timestamp in the trace file.
 289      *
 290      * @param ratio the proportional 'rank' in the trace
 291      * @return a context which can later be used to read the corresponding event
 292      */
 293     public ITmfContext seekEvent(double ratio);
 294
 295 }