/
IHostModel.java
226 lines (206 loc) · 7.67 KB
/
IHostModel.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
/*******************************************************************************
* Copyright (c) 2016 École Polytechnique de Montréal
*
* All rights reserved. This program and the accompanying materials are
* made available under the terms of the Eclipse Public License 2.0 which
* accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*******************************************************************************/
package org.eclipse.tracecompass.internal.analysis.callstack.core.model;
import java.util.Collection;
import java.util.EnumSet;
import java.util.Map;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.jdt.annotation.Nullable;
import org.eclipse.tracecompass.internal.analysis.callstack.core.callgraph.AggregatedCallSite;
import org.eclipse.tracecompass.tmf.core.analysis.IAnalysisModule;
/**
* This interface represents a host system, for example a machine running Linux,
* and allows to access information on the state of the machine at some
* time[range]. Typically, there would be one model instance per host and all
* traces taken on the same host (machine) will share the same model.
*
* Users of the model do not need to know where the information comes from. For
* each method providing information, a default value will be provided in case
* the information is not available. See the method's javadoc for that value.
*
* How the host information is accessed is up to each implementations. It can
* make use of the various analyses of the traces that compose this model.
*
* @author Geneviève Bastien
*/
public interface IHostModel {
/**
* An enumeration of the types of data one can need. It will be useful to
* retrieve and schedule the required analysis modules for a host
*/
public enum ModelDataType {
/** Need the current TID */
TID,
/** Need the time spent on the CPU */
CPU_TIME,
/** Need sampling data */
SAMPLING_DATA,
/** Need kernel statuses */
KERNEL_STATES,
/** Need the pids */
PID,
/** Need the executable name */
EXEC_NAME
}
/**
* Value to use for thread ID
*/
int UNKNOWN_TID = -1;
/**
* Value to use when a duration or timestamp is not known
*/
long TIME_UNKNOWN = -1;
/**
* Get which thread is running on the CPU at a given time
*
* @param cpu
* The CPU ID on which the thread is running
* @param t
* The desired time
* @return The ID of the thread running on the CPU, or {@link #UNKNOWN_TID}
* if it is not available
*/
default int getThreadOnCpu(int cpu, long t) {
return getThreadOnCpu(cpu, t, false);
}
/**
* Get which thread is running on the CPU at a given time, but may blocks if
* the answer is not available yet but may come later
*
* @param cpu
* The CPU ID on which the thread is running
* @param t
* The desired time
* @param block
* If <code>true</code>, the method will block until the
* providers have the data available.
* @return The ID of the thread running on the CPU, or {@link #UNKNOWN_TID}
* if it is not available
*/
int getThreadOnCpu(int cpu, long t, boolean block);
/**
* Get the process ID of a thread
*
* @param tid
* The ID of the thread for which to get the process ID
* @param t
* The desired time. A negative value will return the first found
* value
* @return The ID of the process this thread is part of, or
* {@link #UNKNOWN_TID} if it is not available
*/
int getProcessId(int tid, long t);
/**
* Get the executable name of a thread
*
* @param tid
* The ID of the thread for which to get the process ID
* @param t
* The desired time. A negative value will return the first found
* value.
* @return The executable name of the thread or <code>null</code> if the
* name is not found
*/
@Nullable String getExecName(int tid, long t);
/**
* Get the amount of time a thread was active on the CPU (any CPU) during a
* period.
*
* @param tid
* The ID of the thread
* @param start
* The start of the period for which to get the time on CPU
* @param end
* The end of the period for which to get the time on CPU
* @return The time spent on the CPU by the thread in that duration or
* {@link #TIME_UNKNOWN} if it is not available
*/
long getCpuTime(int tid, long start, long end);
/**
* Get the aggregated sample data for a thread in a time range.
*
* @param tid
* The ID of the thread
* @param start
* The start of the period for which to get the time on CPU
* @param end
* The end of the period for which to get the time on CPU
* @return The collection of aggregated sampling data for the time range
*/
Collection<AggregatedCallSite> getSamplingData(int tid, long start, long end);
/**
* Get an iterable over the status intervals of a thread
*
* @param tid
* The ID of the thread
* @param start
* The start of the period for which to get the time on CPU
* @param end
* The end of the period for which to get the time on CPU
* @param resolution
* The resolution, i.e., the number of nanoseconds between kernel
* status queries. A value lower or equal to 1 will return all
* intervals.
* @return An iterator over the status intervals for the thread
*/
Iterable<ProcessStatusInterval> getThreadStatusIntervals(int tid, long start, long end, long resolution);
/**
* Get the start time of the underlying model analyses.
*
* @return The start time
*/
long getStartTime();
/**
* Get the end time of the underlying model analyses.
*
* @return The end time
*/
long getEndTime();
/**
* Get a map with an entry for each tid and an iterable with all the process
* status intervals.
*
* @param tids
* The tids for which to get the intervals
* @param times
* The times requested from the query parameters
* @param monitor
* A monitor to cancel the query
* @return A map with an iterable of status intervals for each tid entry
*/
Map<Integer, Iterable<ProcessStatusInterval>> getThreadStatusIntervals(Collection<Integer> tids, Collection<Long> times, IProgressMonitor monitor);
/**
* Get whether sampling data is available for this host
*
* @return <code>true</code> if sampling data is available,
* <code>false</code> otherwise
*/
boolean isSamplingDataAvailable();
/**
* Get whether thread status information is available for this host
*
* @return <code>true</code> if thread status information is available,
* <code>false</code> otherwise
*/
boolean isThreadStatusAvailable();
/**
* Get the analyses modules required to get the data requested
*
* @param requiredData
* An enum set of model data that will be useful to the caller
* @return A collection of analysis modules
*/
Collection<IAnalysisModule> getRequiredModules(EnumSet<ModelDataType> requiredData);
/**
* Dispose of the model when it is not needed anymore
*/
void dispose();
}