Commit | Line | Data |
---|---|---|
200789b3 AM |
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 | ||
f3f93fa6 | 15 | import java.util.List; |
200789b3 AM |
16 | import java.util.Map; |
17 | ||
18 | import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp; | |
1c0de632 | 19 | import org.eclipse.linuxtools.tmf.core.signal.TmfStatsUpdatedSignal; |
200789b3 AM |
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 | * | |
8b260d9f AM |
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 | * | |
200789b3 AM |
29 | * @author Alexandre Montplaisir |
30 | * @since 2.0 | |
31 | */ | |
32 | public interface ITmfStatistics { | |
33 | ||
1c0de632 AM |
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 | */ | |
8b260d9f | 54 | public void updateStats(boolean isGlobal, long start, long end); |
1c0de632 | 55 | |
f3f93fa6 AM |
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 | ||
200789b3 AM |
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 | */ | |
8b260d9f | 103 | public long getEventsInRange(long start, long end); |
200789b3 AM |
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 | */ | |
8b260d9f | 115 | public Map<String, Long> getEventTypesInRange(long start, long end); |
1a4205d9 AM |
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(); | |
200789b3 | 122 | } |