org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/statistics/ITmfStatistics.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2014 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  *   Alexandre Montplaisir - Initial API
  11  ******************************************************************************/
  12
  13 package org.eclipse.tracecompass.tmf.core.statistics;
  14
  15 import java.util.List;
  16 import java.util.Map;
  17
  18 import org.eclipse.tracecompass.tmf.core.timestamp.ITmfTimestamp;
  19
  20 /**
  21  * Provider for statistics, which is assigned to a trace. This can be used to
  22  * populate views like the Statistics View or the Histogram.
  23  *
  24  * As a guideline, since any trace type can use this interface, all timestamps
  25  * should be normalized to nanoseconds when using these methods
  26  * ({@link ITmfTimestamp#NANOSECOND_SCALE}).
  27  *
  28  * @author Alexandre Montplaisir
  29  */
  30 public interface ITmfStatistics {
  31
  32     /**
  33      * Run a histogram query on the statistics back-end. This means, return the
  34      * total number of events in a series of 'nb' equal-sized ranges between
  35      * 'start' and 'end'. As its name implies, this is typically used to fill
  36      * the histogram data (where each range represents one pixel on the
  37      * histogram).
  38      *
  39      * This method will block the caller until the results are returned, so it
  40      * should not be called from a signal handler or from the UI thread.
  41      *
  42      * @param start
  43      *            Start time of the query
  44      * @param end
  45      *            End time of the query
  46      * @param nb
  47      *            The number of ranges to separate the complete time range into.
  48      *            It will be the size() of the returned array.
  49      * @return The array representing the number of events found in each
  50      *         sub-range.
  51      */
  52     List<Long> histogramQuery(long start, long end, int nb);
  53
  54     /**
  55      * Return the total number of events in the trace.
  56      *
  57      * @return The total number of events
  58      */
  59     long getEventsTotal();
  60
  61     /**
  62      * Return a Map of the total events in the trace, per event type. The event
  63      * type should come from ITmfEvent.getType().getName().
  64      *
  65      * @return The map of <event_type, count>, for the whole trace
  66      */
  67     Map<String, Long> getEventTypesTotal();
  68
  69     /**
  70      * Retrieve the number of events in the trace in a given time interval.
  71      *
  72      * @param start
  73      *            Start time of the time range
  74      * @param end
  75      *            End time of the time range
  76      * @return The number of events found
  77      */
  78     long getEventsInRange(long start, long end);
  79
  80     /**
  81      * Retrieve the number of events in the trace, per event type, in a given
  82      * time interval.
  83      *
  84      * @param start
  85      *            Start time of the time range
  86      * @param end
  87      *            End time of the time range
  88      * @return The map of <event_type, count>, for the given time range
  89      */
  90     Map<String, Long> getEventTypesInRange(long start, long end);
  91
  92     /**
  93      * Notify the statistics back-end that the trace is being closed, so it
  94      * should dispose itself as appropriate (release file descriptors, etc.)
  95      */
  96     void dispose();
  97 }