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