1 /*******************************************************************************
2 * Copyright (c) 2012, 2016 Ericsson and others.
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
10 * Alexandre Montplaisir - Initial API
11 ******************************************************************************/
13 package org
.eclipse
.tracecompass
.statesystem
.core
;
15 import java
.util
.List
;
17 import org
.eclipse
.jdt
.annotation
.NonNull
;
18 import org
.eclipse
.tracecompass
.statesystem
.core
.exceptions
.AttributeNotFoundException
;
19 import org
.eclipse
.tracecompass
.statesystem
.core
.exceptions
.StateSystemDisposedException
;
20 import org
.eclipse
.tracecompass
.statesystem
.core
.exceptions
.TimeRangeException
;
21 import org
.eclipse
.tracecompass
.statesystem
.core
.interval
.ITmfStateInterval
;
22 import org
.eclipse
.tracecompass
.statesystem
.core
.statevalue
.ITmfStateValue
;
26 * This is the read-only interface to the generic state system. It contains all
27 * the read-only quark-getting methods, as well as the history-querying ones.
29 * @author Alexandre Montplaisir
30 * @noimplement Only the internal StateSystem class should implement this
33 public interface ITmfStateSystem
{
35 /** Root attribute quark
37 int ROOT_ATTRIBUTE
= -1;
38 /** Invalid attribute quark
40 int INVALID_ATTRIBUTE
= -2;
43 * Get the ID of this state system.
45 * @return The state system's ID
50 * Return the start time of this history. It usually matches the start time
51 * of the original trace.
53 * @return The history's registered start time
58 * Return the current end time of the history.
60 * @return The current end time of this state history
62 long getCurrentEndTime();
65 * Check if the construction of this state system was cancelled or not. If
66 * false is returned, it can mean that the building was finished
67 * successfully, or that it is still ongoing. You can check independently
68 * with {@link #waitUntilBuilt()} if it is finished or not.
70 * @return If the construction was cancelled or not. In true is returned, no
71 * queries should be run afterwards.
73 boolean isCancelled();
76 * While it's possible to query a state history that is being built,
77 * sometimes we might want to wait until the construction is finished before
78 * we start doing queries.
80 * This method blocks the calling thread until the history back-end is done
81 * building. If it's already built (ie, opening a pre-existing file) this
82 * should return immediately.
84 * You should always check with {@link #isCancelled()} if it is safe to
85 * query this state system before doing queries.
87 void waitUntilBuilt();
90 * Wait until the state system construction is finished. Similar to
91 * {@link #waitUntilBuilt()}, but we also specify a timeout. If the timeout
92 * elapses before the construction is finished, the method will return.
94 * The return value determines if the return was due to the construction
95 * finishing (true), or the timeout elapsing (false).
97 * This can be useful, for example, for a component doing queries
98 * periodically to the system while it is being built.
101 * Timeout value in milliseconds
102 * @return True if the return was due to the construction finishing, false
103 * if it was because the timeout elapsed. Same logic as
104 * {@link java.util.concurrent.CountDownLatch#await(long, java.util.concurrent.TimeUnit)}
106 boolean waitUntilBuilt(long timeout
);
109 * Notify the state system that the trace is being closed, so it should
110 * clean up, close its files, etc.
114 // ------------------------------------------------------------------------
115 // Read-only quark-getting methods
116 // ------------------------------------------------------------------------
119 * Return the current total amount of attributes in the system. This is also
120 * equal to the quark that will be assigned to the next attribute that's
123 * @return The current number of attributes in the system
125 int getNbAttributes();
128 * Basic quark-retrieving method. Pass an attribute in parameter as an array
129 * of strings, the matching quark will be returned.
131 * This version will NOT create any new attributes. If an invalid attribute
132 * is requested, an exception will be thrown.
134 * If it is expected that the requested attribute might be absent, it is
135 * recommended to use {@link #optQuarkAbsolute(String...)} instead.
138 * Attribute given as its full path in the Attribute Tree
139 * @return The quark of the requested attribute, if it existed.
140 * @throws AttributeNotFoundException
141 * This exception is thrown if the requested attribute simply
142 * did not exist in the system.
144 int getQuarkAbsolute(String
... attribute
)
145 throws AttributeNotFoundException
;
148 * Quark-retrieving method for an optional attribute that may or may not be
149 * present. Pass an attribute in parameter as an array of strings, if it
150 * exists, the matching quark will be returned.
152 * This version will NOT create any new attributes. If an attribute that
153 * does not exist is requested, {@link #INVALID_ATTRIBUTE} will be returned.
156 * Attribute given as its full path in the Attribute Tree
157 * @return The quark of the requested attribute, or
158 * {@link #INVALID_ATTRIBUTE} if it does not exist.
161 int optQuarkAbsolute(String
... attribute
);
164 * "Relative path" quark-getting method. Instead of specifying a full path,
165 * if you know the path is relative to another attribute for which you
166 * already have the quark, use this for better performance.
168 * This is useful for cases where a lot of modifications or queries will
169 * originate from the same branch of the attribute tree : the common part of
170 * the path won't have to be re-hashed for every access.
172 * This version will NOT create any new attributes. If an invalid attribute
173 * is requested, an exception will be thrown.
175 * If it is expected that the requested sub-attribute might be absent, it is
176 * recommended to use {@link #optQuarkRelative(int, String...)} instead.
178 * @param startingNodeQuark
179 * The quark of the attribute from which 'subPath' originates.
181 * "Rest" of the path to get to the final attribute
182 * @return The matching quark, if it existed
183 * @throws IndexOutOfBoundsException
184 * If the starting node quark is out of range
185 * @throws AttributeNotFoundException
186 * If the sub-attribute does not exist
188 int getQuarkRelative(int startingNodeQuark
, String
... subPath
)
189 throws AttributeNotFoundException
;
192 * "Relative path" quark-getting method for an optional attribute that may
193 * or may not be present. Instead of specifying a full path, if you know the
194 * path is relative to another attribute for which you already have the
195 * quark, use this for better performance.
197 * This is useful for cases where a lot of modifications or queries will
198 * originate from the same branch of the attribute tree : the common part of
199 * the path won't have to be re-hashed for every access.
201 * This version will NOT create any new attributes. If a sub-attribute that
202 * does not exist is requested, {@link #INVALID_ATTRIBUTE} will be returned.
204 * @param startingNodeQuark
205 * The quark of the attribute from which 'subPath' originates.
207 * "Rest" of the path to get to the final attribute
208 * @return The quark of the requested sub-attribute, or
209 * {@link #INVALID_ATTRIBUTE} if it does not exist.
210 * @throws IndexOutOfBoundsException
211 * If the starting node quark is out of range
214 int optQuarkRelative(int startingNodeQuark
, String
... subPath
);
217 * Return the sub-attributes of the target attribute, as a List of quarks.
220 * The attribute of which you want to sub-attributes. You can use
221 * {@link #ROOT_ATTRIBUTE} here to specify the root node.
223 * True if you want all recursive sub-attributes, false if you
224 * only want the first level.
225 * @return A List of integers, matching the quarks of the sub-attributes.
226 * @throws IndexOutOfBoundsException
227 * If the quark is out of range
229 @NonNull List
<@NonNull Integer
> getSubAttributes(int quark
, boolean recursive
);
232 * Return the sub-attributes of the target attribute, as a List of quarks,
233 * similarly to {@link #getSubAttributes(int, boolean)}, but with an added
234 * regex pattern to filter on the return attributes.
237 * The attribute of which you want to sub-attributes. You can use
238 * {@link #ROOT_ATTRIBUTE} here to specify the root node.
240 * True if you want all recursive sub-attributes, false if you
241 * only want the first level. Note that the returned value will
244 * The regular expression to match the attribute base name.
245 * @return A List of integers, matching the quarks of the sub-attributes
246 * that match the regex. An empty list is returned if there is no
247 * matching attribute.
248 * @throws IndexOutOfBoundsException
249 * If the quark is out of range
251 @NonNull List
<@NonNull Integer
> getSubAttributes(int quark
, boolean recursive
, String pattern
);
254 * Batch quark-retrieving method. This method allows you to specify a path
255 * pattern which can include wildcard "*" or parent ".." elements. It will
256 * check all the existing attributes in the attribute tree and return those
257 * who match the pattern.
259 * For example, passing ("Threads", "*", "Exec_mode") will return the list
260 * of quarks for attributes "Threads/1000/Exec_mode",
261 * "Threads/1500/Exec_mode", and so on, depending on what exists at this
262 * time in the attribute tree.
264 * If no wildcard or parent element is specified, the behavior is the same
265 * as getQuarkAbsolute() (except it will return a List with one entry, or an
266 * empty list if there is no match instead of throwing an exception). This
267 * method will never create new attributes.
270 * The array of strings representing the pattern to look for.
271 * @return A List of unique attribute quarks, representing attributes that
272 * matched the pattern. If no attribute matched, the list will be
273 * empty (but not null). If the pattern is empty,
274 * {@link #ROOT_ATTRIBUTE} is returned in the list.
276 @NonNull List
<@NonNull Integer
> getQuarks(String
... pattern
);
279 * Relative batch quark-retrieving method. This method allows you to specify
280 * a path pattern which can include wildcard "*" or parent ".." elements. It
281 * will check all the existing attributes in the attribute tree and return
282 * those who match the pattern.
284 * For example, passing (5, "Threads", "*", "Exec_mode") will return the
285 * list of quarks for attributes "<path of quark 5>/Threads/1000/Exec_mode",
286 * "<path of quark 5>/Threads/1500/Exec_mode", and so on, depending on what
287 * exists at this time in the attribute tree.
289 * If no wildcard or parent element is specified, the behavior is the same
290 * as getQuarkRelative() (except it will return a List with one entry, or an
291 * empty list if there is no match instead of throwing an exception). This
292 * method will never create new attributes.
294 * @param startingNodeQuark
295 * The quark of the attribute from which 'pattern' originates.
297 * The array of strings representing the pattern to look for.
298 * @return A List of unique attribute quarks, representing attributes that
299 * matched the pattern. If no attribute matched, the list will be
300 * empty (but not null). If the pattern is empty, the starting node
301 * quark is returned in the list.
302 * @throws IndexOutOfBoundsException
303 * If the starting node quark is out of range
306 @NonNull List
<@NonNull Integer
> getQuarks(int startingNodeQuark
, String
... pattern
);
309 * Return the name assigned to this quark. This returns only the "basename",
310 * not the complete path to this attribute.
312 * @param attributeQuark
313 * The quark for which we want the name
314 * @return The name of the quark
315 * @throws IndexOutOfBoundsException
316 * If the attribute quark is out of range
318 @NonNull String
getAttributeName(int attributeQuark
);
321 * This returns the slash-separated path of an attribute by providing its
324 * @param attributeQuark
325 * The quark of the attribute we want
326 * @return One single string separated with '/', like a filesystem path
327 * @throws IndexOutOfBoundsException
328 * If the attribute quark is out of range
330 @NonNull String
getFullAttributePath(int attributeQuark
);
333 * Return the full attribute path, as an array of strings representing each
336 * @param attributeQuark
337 * The quark of the attribute we want.
338 * @return The array of path elements
339 * @throws IndexOutOfBoundsException
340 * If the attribute quark is out of range
343 String
@NonNull [] getFullAttributePathArray(int attributeQuark
);
346 * Returns the parent quark of the attribute.
348 * @param attributeQuark
349 * The quark of the attribute
350 * @return Quark of the parent attribute or {@link #ROOT_ATTRIBUTE} if root
351 * quark or no parent.
352 * @throws IndexOutOfBoundsException
353 * If the attribute quark is out of range
355 int getParentAttributeQuark(int attributeQuark
);
357 // ------------------------------------------------------------------------
359 // ------------------------------------------------------------------------
362 * Returns the current state value we have (in the Transient State) for the
365 * This is useful even for a StateHistorySystem, as we are guaranteed it
366 * will only do a memory access and not go look on disk (and we don't even
367 * have to provide a timestamp!)
369 * @param attributeQuark
370 * For which attribute we want the current state
371 * @return The State value that's "current" for this attribute
372 * @throws IndexOutOfBoundsException
373 * If the attribute quark is out of range
375 @NonNull ITmfStateValue
queryOngoingState(int attributeQuark
);
378 * Get the start time of the current ongoing state, for the specified
381 * @param attributeQuark
382 * Quark of the attribute
383 * @return The current start time of the ongoing state
384 * @throws IndexOutOfBoundsException
385 * If the attribute quark is out of range
387 long getOngoingStartTime(int attributeQuark
);
390 * Load the complete state information at time 't' into the returned List.
391 * You can then get the intervals for single attributes by using
392 * List.get(n), where 'n' is the quark of the attribute.
394 * On average if you need around 10 or more queries for the same timestamps,
395 * use this method. If you need less than 10 (for example, running many
396 * queries for the same attributes but at different timestamps), you might
397 * be better using the querySingleState() methods instead.
400 * We will recreate the state information to what it was at time
402 * @return The List of intervals, where the offset = the quark
403 * @throws TimeRangeException
404 * If the 't' parameter is outside of the range of the state
406 * @throws StateSystemDisposedException
407 * If the query is sent after the state system has been disposed
409 @NonNull List
<@NonNull ITmfStateInterval
> queryFullState(long t
)
410 throws StateSystemDisposedException
;
413 * Singular query method. This one does not update the whole stateInfo
414 * vector, like queryFullState() does. It only searches for one specific
415 * entry in the state history.
417 * It should be used when you only want very few entries, instead of the
418 * whole state (or many entries, but all at different timestamps). If you do
419 * request many entries all at the same time, you should use the
420 * conventional queryFullState() + List.get() method.
423 * The timestamp at which we want the state
424 * @param attributeQuark
425 * Which attribute we want to get the state of
426 * @return The StateInterval representing the state
427 * @throws TimeRangeException
429 * @throws IndexOutOfBoundsException
430 * If the attribute quark is out of range
431 * @throws StateSystemDisposedException
432 * If the query is sent after the state system has been disposed
434 @NonNull ITmfStateInterval
querySingleState(long t
, int attributeQuark
)
435 throws StateSystemDisposedException
;