Commit | Line | Data |
---|---|---|
200789b3 | 1 | /******************************************************************************* |
60ae41e1 | 2 | * Copyright (c) 2012, 2014 Ericsson |
200789b3 AM |
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 | ||
f3f93fa6 | 15 | import java.util.List; |
200789b3 AM |
16 | import java.util.Map; |
17 | ||
3bd46eef | 18 | import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp; |
200789b3 AM |
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 | * | |
8b260d9f AM |
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 | * | |
200789b3 AM |
28 | * @author Alexandre Montplaisir |
29 | * @since 2.0 | |
30 | */ | |
31 | public interface ITmfStatistics { | |
32 | ||
f3f93fa6 AM |
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 | * | |
d6b46913 AM |
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. | |
f3f93fa6 AM |
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 | */ | |
57a2a5ca | 53 | List<Long> histogramQuery(long start, long end, int nb); |
f3f93fa6 | 54 | |
200789b3 AM |
55 | /** |
56 | * Return the total number of events in the trace. | |
57 | * | |
58 | * @return The total number of events | |
59 | */ | |
57a2a5ca | 60 | long getEventsTotal(); |
200789b3 AM |
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 | */ | |
57a2a5ca | 68 | Map<String, Long> getEventTypesTotal(); |
200789b3 AM |
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 | */ | |
57a2a5ca | 79 | long getEventsInRange(long start, long end); |
200789b3 AM |
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 | */ | |
57a2a5ca | 91 | Map<String, Long> getEventTypesInRange(long start, long end); |
1a4205d9 AM |
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 | */ | |
57a2a5ca | 97 | void dispose(); |
200789b3 | 98 | } |