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