org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/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.linuxtools.tmf.core.statistics;
  14
  15 import java.util.List;
  16 import java.util.Map;
  17
  18 import org.eclipse.linuxtools.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  * @since 2.0
  30  */
  31 public interface ITmfStatistics {
  32
  33     /**
  34      * Run a histogram query on the statistics back-end. This means, return the
  35      * total number of events in a series of 'nb' equal-sized ranges between
  36      * 'start' and 'end'. As its name implies, this is typically used to fill
  37      * the histogram data (where each range represents one pixel on the
  38      * histogram).
  39      *
  40      * This method will block the caller until the results are returned, so it
  41      * should not be called from a signal handler or from the UI thread.
  42      *
  43      * @param start
  44      *            Start time of the query
  45      * @param end
  46      *            End time of the query
  47      * @param nb
  48      *            The number of ranges to separate the complete time range into.
  49      *            It will be the size() of the returned array.
  50      * @return The array representing the number of events found in each
  51      *         sub-range.
  52      */
  53     List<Long> histogramQuery(long start, long end, int nb);
  54
  55     /**
  56      * Return the total number of events in the trace.
  57      *
  58      * @return The total number of events
  59      */
  60     long getEventsTotal();
  61
  62     /**
  63      * Return a Map of the total events in the trace, per event type. The event
  64      * type should come from ITmfEvent.getType().getName().
  65      *
  66      * @return The map of <event_type, count>, for the whole trace
  67      */
  68     Map<String, Long> getEventTypesTotal();
  69
  70     /**
  71      * Retrieve the number of events in the trace in a given time interval.
  72      *
  73      * @param start
  74      *            Start time of the time range
  75      * @param end
  76      *            End time of the time range
  77      * @return The number of events found
  78      */
  79     long getEventsInRange(long start, long end);
  80
  81     /**
  82      * Retrieve the number of events in the trace, per event type, in a given
  83      * time interval.
  84      *
  85      * @param start
  86      *            Start time of the time range
  87      * @param end
  88      *            End time of the time range
  89      * @return The map of <event_type, count>, for the given time range
  90      */
  91     Map<String, Long> getEventTypesInRange(long start, long end);
  92
  93     /**
  94      * Notify the statistics back-end that the trace is being closed, so it
  95      * should dispose itself as appropriate (release file descriptors, etc.)
  96      */
  97     void dispose();
  98 }