ctf/org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/trace/IPacketReader.java

   1 /*******************************************************************************
   2  * Copyright (c) 2015 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are made
   5  * 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  *     Matthew Khouzam - Initial API and implementation
  11  *******************************************************************************/
  12
  13 package org.eclipse.tracecompass.ctf.core.trace;
  14
  15 import org.eclipse.tracecompass.ctf.core.CTFException;
  16 import org.eclipse.tracecompass.ctf.core.event.EventDefinition;
  17 import org.eclipse.tracecompass.ctf.core.event.types.ICompositeDefinition;
  18
  19 /**
  20  * Packet reader interface, allows for more flexible packet readers. A packet
  21  * reader must be able to do one thing only: read a ctf packet.
  22  *
  23  * In order to do that, it will have access to the packet and can then iterate
  24  * over the packet with two main functions {@link #readNextEvent()} and
  25  * {@link #hasMoreEvents()}. The packet reader must also have a notion of
  26  * whether a given packet has an assigned CPU or not, which will be given
  27  * by @link {@link #getCPU()}, as well as the event header, defined in
  28  * {@link #getCurrentPacketEventHeader()}. The packet description in the reader
  29  * can be obtained by calling {@link #getCurrentPacket()}
  30  *
  31  * @author Matthew Khouzam
  32  *
  33  * @since 2.0
  34  */
  35 public interface IPacketReader {
  36
  37     /**
  38      * The value of a cpu if it is unknown to the packet reader
  39      */
  40     int UNKNOWN_CPU = -1;
  41
  42     /**
  43      * Gets the CPU (core) number
  44      *
  45      * @return the CPU (core) number
  46      */
  47     int getCPU();
  48
  49     /**
  50      * Returns whether it is possible to read any more events from this packet.
  51      *
  52      * @return True if it is possible to read any more events from this packet.
  53      */
  54     boolean hasMoreEvents();
  55
  56     /**
  57      * Reads the next event of the packet into the right event definition.
  58      *
  59      * @return The event definition containing the event data that was just
  60      *         read.
  61      * @throws CTFException
  62      *             If there was a problem reading the trace
  63      */
  64     EventDefinition readNextEvent() throws CTFException;
  65
  66     /**
  67      * Get the packet being read
  68      *
  69      * @return the packet being read
  70      */
  71     ICTFPacketDescriptor getCurrentPacket();
  72
  73     /**
  74      * Get the current event header definition
  75      *
  76      * @return the current event header definition
  77      */
  78     ICompositeDefinition getCurrentPacketEventHeader();
  79
  80 }