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.Map;
  16
  17 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  18 import org.eclipse.linuxtools.tmf.core.signal.TmfStatsUpdatedSignal;
  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      * This method provides a centralized and asynchronous way of querying
  35      * statistics information. It is an alternative to the other get* methods,
  36      * and should not block the caller for too long.
  37      *
  38      * Implementors can usually call their own getEventTotal(),
  39      * getEventsInRange(), etc. but should do so in a separate thread, and
  40      * should send a {@link TmfStatsUpdatedSignal} whenever they are done (that
  41      * signal will carry the results).
  42      *
  43      * @param isGlobal
  44      *            Is this for a global query (whole time range of a trace), or
  45      *            just for a specific time range.
  46      * @param start
  47      *            The start time of the query range. Has no effect if isGlobal
  48      *            is true.
  49      * @param end
  50      *            The end time of the query range. Has no effect if isGlobal is
  51      *            true.
  52      */
  53     public void updateStats(boolean isGlobal, long start, long end);
  54
  55     /**
  56      * Return the total number of events in the trace.
  57      *
  58      * @return The total number of events
  59      */
  60     public 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     public 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     public 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     public 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     public void dispose();
  98 }