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