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

   1 /*******************************************************************************
   2  * Copyright (c) 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  *   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.event.ITmfTimestamp;
  19 import org.eclipse.linuxtools.tmf.core.signal.TmfStatsUpdatedSignal;
  20
  21 /**
  22  * Provider for statistics, which is assigned to a trace. This can be used to
  23  * populate views like the Statistics View or the Histogram.
  24  *
  25  * As a guideline, since any trace type can use this interface, all timestamps
  26  * should be normalized to nanoseconds when using these methods
  27  * ({@link ITmfTimestamp#NANOSECOND_SCALE}).
  28  *
  29  * @author Alexandre Montplaisir
  30  * @since 2.0
  31  */
  32 public interface ITmfStatistics {
  33
  34     /**
  35      * This method provides a centralized and asynchronous way of querying
  36      * statistics information. It is an alternative to the other get* methods,
  37      * and should not block the caller for too long.
  38      *
  39      * Implementors can usually call their own getEventTotal(),
  40      * getEventsInRange(), etc. but should do so in a separate thread, and
  41      * should send a {@link TmfStatsUpdatedSignal} whenever they are done (that
  42      * signal will carry the results).
  43      *
  44      * @param isGlobal
  45      *            Is this for a global query (whole time range of a trace), or
  46      *            just for a specific time range.
  47      * @param start
  48      *            The start time of the query range. Has no effect if isGlobal
  49      *            is true.
  50      * @param end
  51      *            The end time of the query range. Has no effect if isGlobal is
  52      *            true.
  53      */
  54     public void updateStats(boolean isGlobal, long start, long end);
  55
  56     /**
  57      * Run a histogram query on the statistics back-end. This means, return the
  58      * total number of events in a series of 'nb' equal-sized ranges between
  59      * 'start' and 'end'. As its name implies, this is typically used to fill
  60      * the histogram data (where each range represents one pixel on the
  61      * histogram).
  62      *
  63      * Unlike {@link #updateStats}, this method will block the caller until the
  64      * results are returned, so it should not be called from a signal handler or
  65      * from the UI thread.
  66      *
  67      * @param start
  68      *            Start time of the query
  69      * @param end
  70      *            End time of the query
  71      * @param nb
  72      *            The number of ranges to separate the complete time range into.
  73      *            It will be the size() of the returned array.
  74      * @return The array representing the number of events found in each
  75      *         sub-range.
  76      */
  77     public List<Long> histogramQuery(long start, long end, int nb);
  78
  79     /**
  80      * Return the total number of events in the trace.
  81      *
  82      * @return The total number of events
  83      */
  84     public long getEventsTotal();
  85
  86     /**
  87      * Return a Map of the total events in the trace, per event type. The event
  88      * type should come from ITmfEvent.getType().getName().
  89      *
  90      * @return The map of <event_type, count>, for the whole trace
  91      */
  92     public Map<String, Long> getEventTypesTotal();
  93
  94     /**
  95      * Retrieve the number of events in the trace in a given time interval.
  96      *
  97      * @param start
  98      *            Start time of the time range
  99      * @param end
 100      *            End time of the time range
 101      * @return The number of events found
 102      */
 103     public long getEventsInRange(long start, long end);
 104
 105     /**
 106      * Retrieve the number of events in the trace, per event type, in a given
 107      * time interval.
 108      *
 109      * @param start
 110      *            Start time of the time range
 111      * @param end
 112      *            End time of the time range
 113      * @return The map of <event_type, count>, for the given time range
 114      */
 115     public Map<String, Long> getEventTypesInRange(long start, long end);
 116
 117     /**
 118      * Notify the statistics back-end that the trace is being closed, so it
 119      * should dispose itself as appropriate (release file descriptors, etc.)
 120      */
 121     public void dispose();
 122 }