import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfIterator;
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateChangeInput;
+import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateSystemBuilder;
/**
* "Dummy" version of the CTF event input plugin. This one only reads events
* method does nothing.
*/
@Override
- public void assignTargetStateSystem(StateSystem ss) {
+ public void assignTargetStateSystem(IStateSystemBuilder ssb) {
//
}
-
- /**
- * Since there is no target state system in the dummy input, this always
- * returns null.
- */
- @Override
- public StateSystem getStateSystem() {
- return null;
- }
-
}
import org.eclipse.linuxtools.internal.lttng2.kernel.core.stateprovider.CtfKernelStateInput;
import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateChangeInput;
import org.junit.AfterClass;
import org.junit.BeforeClass;
assertEquals(testStartTime, CtfTestFiles.startTime);
}
- @Test
- public void testRunning() {
- StateSystem ss = new StateSystem();
- input.assignTargetStateSystem(ss);
- input.getStateSystem(); /* Let's pad that coverage... */
- input.run();
- }
+ //FIXME re-enable once we offer history-less state systems again
+// @Test
+// public void testRunning() {
+// StateSystem ss = new StateSystem();
+// input.assignTargetStateSystem(ss);
+// input.run();
+// }
}
import static org.junit.Assert.*;
import java.io.File;
-import java.io.FileNotFoundException;
import java.io.IOException;
-import java.io.PrintWriter;
import java.util.List;
import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateHistorySystem;
import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
import org.eclipse.linuxtools.tmf.core.statesystem.backend.historytree.HistoryTreeBackend;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.HistoryBuilder;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateChangeInput;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateHistoryBackend;
+import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateSystemBuilder;
import org.eclipse.linuxtools.tmf.core.statevalue.StateValueTypeException;
import org.eclipse.linuxtools.internal.lttng2.kernel.core.stateprovider.CtfKernelStateInput;
import org.eclipse.linuxtools.lttng2.kernel.core.trace.Attributes;
static HistoryBuilder builder;
static IStateChangeInput input;
static IStateHistoryBackend hp;
- static StateHistorySystem shs;
+ static IStateSystemBuilder ssb;
/* Offset in the trace + start time of the trace */
private final static long interestingTimestamp1 = 18670067372290L + 1331649577946812237L;
e.printStackTrace();
}
builder.run();
- shs = (StateHistorySystem) builder.getSS();
+ ssb = builder.getStateSystemBuilder();
builder.close(); /* Waits for the construction to finish */
}
@Test
public void testOpenExistingStateFile() throws IOException {
IStateHistoryBackend hp2 = null;
- StateHistorySystem shs2 = null;
+ IStateSystemBuilder ssb2 = null;
/* 'newStateFile' should have already been created */
hp2 = new HistoryTreeBackend(stateFile);
- shs2 = new StateHistorySystem(hp2, false);
+ ssb2 = HistoryBuilder.openExistingHistory(hp2);
- assertNotNull(shs2);
+ assertNotNull(ssb2);
assertEquals(CtfTestFiles.startTime, hp2.getStartTime());
assertEquals(CtfTestFiles.endTime, hp2.getEndTime());
}
int quark, quark2, valueInt;
String valueStr;
- list = shs.loadStateAtTime(interestingTimestamp1);
+ list = ssb.loadStateAtTime(interestingTimestamp1);
- quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
interval = list.get(quark);
valueInt = interval.getStateValue().unboxInt();
assertEquals(1397, valueInt);
- quark = shs.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_NAME);
+ quark = ssb.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_NAME);
interval = list.get(quark);
valueStr = interval.getStateValue().unboxStr();
assertEquals("gdbus", valueStr);
/* Query a stack attribute, has to be done in two passes */
- quark = shs.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_MODE_STACK);
+ quark = ssb.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_MODE_STACK);
interval = list.get(quark);
valueInt = interval.getStateValue().unboxInt(); /* The stack depth */
- quark2 = shs.getQuarkRelative(quark, Integer.toString(valueInt));
+ quark2 = ssb.getQuarkRelative(quark, Integer.toString(valueInt));
interval = list.get(quark2);
valueStr = interval.getStateValue().unboxStr();
assertTrue(valueStr.equals("sys_poll"));
ITmfStateInterval interval;
String valueStr;
- quark = shs.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_NAME);
- interval = shs.querySingleState(timestamp, quark);
+ quark = ssb.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_NAME);
+ interval = ssb.querySingleState(timestamp, quark);
valueStr = interval.getStateValue().unboxStr();
assertEquals("gdbus", valueStr);
}
int quark;
List<ITmfStateInterval> intervals;
- quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
- intervals = shs.queryHistoryRange(quark, time1, time2);
+ quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ intervals = ssb.queryHistoryRange(quark, time1, time2);
assertEquals(487, intervals.size()); /* Number of context switches! */
assertEquals(1685, intervals.get(100).getStateValue().unboxInt());
assertEquals(1331668248427681372L, intervals.get(205).getEndTime());
List<ITmfStateInterval> intervals;
- int quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.IRQ_STACK);
- long ts1 = shs.getHistoryBackend().getStartTime(); /* start of the trace */
+ int quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.IRQ_STACK);
+ long ts1 = ssb.getStartTime(); /* start of the trace */
long ts2 = CtfTestFiles.startTime + 20L * CtfTestFiles.NANOSECS_PER_SEC; /* invalid, but ignored */
- intervals = shs.queryHistoryRange(quark, ts1, ts2);
+ intervals = ssb.queryHistoryRange(quark, ts1, ts2);
/* Nb of IRQs on CPU 0 during the whole trace */
assertEquals(1653, intervals.size());
int quark;
List<ITmfStateInterval> intervals;
- quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
- intervals = shs.queryHistoryRange(quark, time1, time2, resolution);
+ quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ intervals = ssb.queryHistoryRange(quark, time1, time2, resolution);
assertEquals(129, intervals.size()); /* Number of context switches! */
assertEquals(1452, intervals.get(50).getStateValue().unboxInt());
assertEquals(1331668248784789238L, intervals.get(100).getEndTime());
@Test(expected = TimeRangeException.class)
public void testFullQueryInvalidTime1() throws TimeRangeException {
long ts = CtfTestFiles.startTime + 20L * CtfTestFiles.NANOSECS_PER_SEC;
- shs.loadStateAtTime(ts);
+ ssb.loadStateAtTime(ts);
}
@Test(expected = TimeRangeException.class)
public void testFullQueryInvalidTime2() throws TimeRangeException {
long ts = CtfTestFiles.startTime - 20L * CtfTestFiles.NANOSECS_PER_SEC;
- shs.loadStateAtTime(ts);
+ ssb.loadStateAtTime(ts);
}
public void testSingleQueryInvalidTime1()
throws AttributeNotFoundException, TimeRangeException {
- int quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ int quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
long ts = CtfTestFiles.startTime + 20L * CtfTestFiles.NANOSECS_PER_SEC;
- shs.querySingleState(ts, quark);
+ ssb.querySingleState(ts, quark);
}
@Test(expected = TimeRangeException.class)
public void testSingleQueryInvalidTime2()
throws AttributeNotFoundException, TimeRangeException {
- int quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ int quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
long ts = CtfTestFiles.startTime - 20L * CtfTestFiles.NANOSECS_PER_SEC;
- shs.querySingleState(ts, quark);
+ ssb.querySingleState(ts, quark);
}
@Test(expected = TimeRangeException.class)
public void testRangeQueryInvalidTime1() throws AttributeNotFoundException,
TimeRangeException {
- int quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ int quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
long ts1 = CtfTestFiles.startTime - 20L * CtfTestFiles.NANOSECS_PER_SEC; /* invalid */
long ts2 = CtfTestFiles.startTime + 1L * CtfTestFiles.NANOSECS_PER_SEC; /* valid */
- shs.queryHistoryRange(quark, ts1, ts2);
+ ssb.queryHistoryRange(quark, ts1, ts2);
}
@Test(expected = TimeRangeException.class)
public void testRangeQueryInvalidTime2() throws TimeRangeException,
AttributeNotFoundException {
- int quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ int quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
long ts1 = CtfTestFiles.startTime - 1L * CtfTestFiles.NANOSECS_PER_SEC; /* invalid */
long ts2 = CtfTestFiles.startTime + 20L * CtfTestFiles.NANOSECS_PER_SEC; /* invalid */
- shs.queryHistoryRange(quark, ts1, ts2);
+ ssb.queryHistoryRange(quark, ts1, ts2);
}
/**
@Test(expected = AttributeNotFoundException.class)
public void testQueryInvalidAttribute() throws AttributeNotFoundException {
- shs.getQuarkAbsolute("There", "is", "no", "cow", "level");
+ ssb.getQuarkAbsolute("There", "is", "no", "cow", "level");
}
/**
ITmfStateInterval interval;
int quark;
- list = shs.loadStateAtTime(interestingTimestamp1);
- quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ list = ssb.loadStateAtTime(interestingTimestamp1);
+ quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
interval = list.get(quark);
/* This is supposed to be an int value */
ITmfStateInterval interval;
int quark;
- list = shs.loadStateAtTime(interestingTimestamp1);
- quark = shs.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_NAME);
+ list = ssb.loadStateAtTime(interestingTimestamp1);
+ quark = ssb.getQuarkAbsolute(Attributes.THREADS, "1432", Attributes.EXEC_NAME);
interval = list.get(quark);
/* This is supposed to be a String value */
@Test
public void testFullAttributeName() throws AttributeNotFoundException {
- int quark = shs.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
- String name = shs.getFullAttributePath(quark);
+ int quark = ssb.getQuarkAbsolute(Attributes.CPUS, "0", Attributes.CURRENT_THREAD);
+ String name = ssb.getFullAttributePath(quark);
assertEquals(name, "CPUs/0/Current_thread");
}
@Test
public void testGetQuarks_begin() {
- List<Integer> list = shs.getQuarks("*", "1577", Attributes.EXEC_NAME);
+ List<Integer> list = ssb.getQuarks("*", "1577", Attributes.EXEC_NAME);
assertEquals(1, list.size());
assertEquals(Integer.valueOf(398), list.get(0));
@Test
public void testGetQuarks_middle() {
- List<Integer> list = shs.getQuarks(Attributes.THREADS, "*", Attributes.EXEC_NAME);
+ List<Integer> list = ssb.getQuarks(Attributes.THREADS, "*", Attributes.EXEC_NAME);
assertEquals(Integer.valueOf(18), list.get(4));
assertEquals(Integer.valueOf(54), list.get(10));
@Test
public void testGetQuarks_end() {
- List<Integer> list = shs.getQuarks(Attributes.THREADS, "1577", "*");
+ List<Integer> list = ssb.getQuarks(Attributes.THREADS, "1577", "*");
assertEquals(3, list.size());
assertEquals(Integer.valueOf(398), list.get(1));
}
-
- @Test
- public void testDebugPrinting() throws FileNotFoundException {
- PrintWriter pw = new PrintWriter(new File("/dev/null"));
- shs.debugPrint(pw);
- pw.close();
- }
}
import java.io.File;
import org.eclipse.linuxtools.internal.lttng2.kernel.core.stateprovider.CtfKernelStateInput;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateHistorySystem;
import org.eclipse.linuxtools.tmf.core.statesystem.backend.historytree.ThreadedHistoryTreeBackend;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.HistoryBuilder;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateChangeInput;
e.printStackTrace();
}
builder.run();
- shs = (StateHistorySystem) builder.getSS();
+ ssb = builder.getStateSystemBuilder();
builder.close(); /* Waits for the construction to finish */
}
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
import org.eclipse.linuxtools.tmf.core.event.ITmfEventField;
import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateHistorySystem;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
+import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateSystemBuilder;
import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
import org.eclipse.linuxtools.tmf.core.statevalue.StateValueTypeException;
import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
class CtfKernelHandler implements Runnable {
private final BlockingQueue<CtfTmfEvent> inQueue;
- private StateSystem ss;
+ private IStateSystemBuilder ss;
private CtfTmfEvent currentEvent;
knownEventNames = fillEventNames();
}
- void assignStateSystem(StateSystem targetSS) {
+ void assignStateSystem(IStateSystemBuilder targetSS) {
this.ss = targetSS;
}
- StateSystem getStateSystem() {
- return ss;
- }
-
@Override
public void run() {
if (ss == null) {
private void closeStateSystem() {
/* Close the History system, if there is one */
- if (ss.getClass() == StateHistorySystem.class) {
- try {
- ((StateHistorySystem) ss).closeHistory(currentEvent.getTimestamp().getValue());
- } catch (TimeRangeException e) {
- /*
- * Since we're using currentEvent.getTimestamp, this shouldn't
- * cause any problem
- */
- e.printStackTrace();
- }
+ try {
+ ss.closeHistory(currentEvent.getTimestamp().getValue());
+ } catch (TimeRangeException e) {
+ /*
+ * Since we're using currentEvent.getTimestamp, this shouldn't
+ * cause any problem
+ */
+ e.printStackTrace();
}
}
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfIterator;
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateChangeInput;
+import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateSystemBuilder;
/**
* This is the state change input plugin for TMF's state system which handles
}
@Override
- public void assignTargetStateSystem(StateSystem ss) {
- eventHandler.assignStateSystem(ss);
+ public void assignTargetStateSystem(IStateSystemBuilder ssb) {
+ eventHandler.assignStateSystem(ssb);
ssAssigned = true;
}
- @Override
- public StateSystem getStateSystem() {
- return eventHandler.getStateSystem();
- }
-
@Override
public long getStartTime() {
return traceReader.getCtfTmfTrace().getStartTime().getValue();
import org.eclipse.linuxtools.internal.lttng2.kernel.core.stateprovider.CtfKernelStateInput;
import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateHistorySystem;
import org.eclipse.linuxtools.tmf.core.statesystem.backend.historytree.HistoryTreeBackend;
import org.eclipse.linuxtools.tmf.core.statesystem.backend.historytree.ThreadedHistoryTreeBackend;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.HistoryBuilder;
return true;
}
- @Override
- public StateHistorySystem getStateSystem() {
- return (StateHistorySystem) this.ss;
- }
-
@Override
protected void buildStateSystem() throws TmfTraceException {
/* Set up the path to the history tree file we'll use */
/* Load an existing history */
try {
htBackend = new HistoryTreeBackend(htFile);
- this.ss = new StateHistorySystem(htBackend, false);
+ this.ss = HistoryBuilder.openExistingHistory(htBackend);
return;
} catch (IOException e) {
/*
throw new TmfTraceException(e.getMessage());
}
- this.ss = builder.getSS();
+ this.ss = builder.getStateSystemQuerier();
builder.run(); /* Start the construction of the history */
//FIXME We will have to call close() once we are notified that the
import org.eclipse.linuxtools.tmf.core.request.ITmfEventRequest;
import org.eclipse.linuxtools.tmf.core.signal.TmfSignal;
import org.eclipse.linuxtools.tmf.core.signal.TmfSignalManager;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
+import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateSystemQuerier;
import org.eclipse.linuxtools.tmf.core.trace.ITmfContext;
import org.eclipse.linuxtools.tmf.core.trace.ITmfLocation;
import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
protected CtfIterator iterator;
/* Reference to the state system assigned to this trace */
- protected StateSystem ss = null;
+ protected IStateSystemQuerier ss = null;
// ------------------------------------------------------------------------
// Constructors
return this.fResource;
}
- public StateSystem getStateSystem() {
+ public IStateSystemQuerier getStateSystem() {
return this.ss;
}
CTFTrace getCTFTrace() {
return fTrace;
}
+
+ /**
+ * Suppressing the warning, because the 'throws' will usually happen in
+ * sub-classes.
+ */
+ @SuppressWarnings("unused")
protected void buildStateSystem() throws TmfTraceException {
/*
* Nothing is done in the basic implementation, please specify
import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateHistoryBackend;
+import org.eclipse.linuxtools.tmf.core.statesystem.helpers.IStateSystemBuilder;
/**
* This is the extension of the StateSystem, which will save the state intervals
* @author alexmont
*
*/
-public class StateHistorySystem extends StateSystem {
-
- /*
- * Inherited from StateSystem
- *
- * protected ArrayList<AttributeTreeNode> attributeList; protected
- * TransientState transState; protected CurrentState curState;
- */
+public class StateHistorySystem extends StateSystem implements
+ IStateSystemBuilder {
/**
* In addition, a state "history" system has a storage back-end from which
}
}
- public IStateHistoryBackend getHistoryBackend() {
- return backend;
+ @Override
+ public long getStartTime() {
+ return backend.getStartTime();
}
- /**
- * Method to close off the History Provider. This happens for example when
- * we are done reading an off-line trace. First we close the TransientState,
- * commit it to the Provider, mark it as inactive, then we write the
- * Attribute Tree somewhere so we can reopen it later.
- *
- * @param endTime
- * The requested End Time of the history, since it could be
- * bigger than the timestamp of the last event or state change we
- * have seen. All "ongoing" states will be extended until this
- * 'endTime'.
- * @throws TimeRangeException
- * If the passed endTime doesn't make sense (for example, if
- * it's earlier than the latest time) and the backend doesn't
- * know how to handle it.
- */
+ @Override
+ public long getCurrentEndTime() {
+ return backend.getEndTime();
+ }
+
+ @Override
public void closeHistory(long endTime) throws TimeRangeException {
File attributeTreeFile;
long attributeTreeFilePos;
* @name External query methods
*/
- /**
- * Load the complete state information at time 't' into the returned List.
- * You can then get the intervals for single attributes by using
- * List.get(n), where 'n' is the quark of the attribute.
- *
- * On average if you need around 10 or more queries for the same timestamps,
- * use this method. If you need less than 10 (for example, running many
- * queries for the same attributes but at different timestamps), you might
- * be better using the querySingleState() methods instead.
- *
- * @param t
- * We will recreate the state information to what it was at time
- * t.
- * @throws TimeRangeException
- * If the 't' parameter is outside of the range of the state
- * history.
- */
+ @Override
public synchronized List<ITmfStateInterval> loadStateAtTime(long t)
throws TimeRangeException {
List<ITmfStateInterval> stateInfo = new ArrayList<ITmfStateInterval>(
return stateInfo;
}
- /**
- * Singular query method. This one does not update the whole stateInfo
- * vector, like loadStateAtTimes() does. It only searches for one specific
- * entry in the state history.
- *
- * It should be used when you only want very few entries, instead of the
- * whole state (or many entries, but all at different timestamps). If you do
- * request many entries all at the same time, you should use the
- * conventional loadStateAtTime() + List.get() method.
- *
- * @param t
- * The timestamp at which we want the state
- * @param attributeQuark
- * Which attribute we want to get the state of
- * @return The StateInterval representing the state
- * @throws TimeRangeException
- * If 't' is invalid
- * @throws AttributeNotFoundException
- * If the requested quark does not exist in the model
- */
+ @Override
public ITmfStateInterval querySingleState(long t, int attributeQuark)
throws AttributeNotFoundException, TimeRangeException {
ITmfStateInterval ret;
return ret;
}
- /**
- * Return a list of state intervals, containing the "history" of a given
- * attribute between timestamps t1 and t2. The list will be ordered by
- * ascending time.
- *
- * Note that contrary to loadStateAtTime(), the returned list here is in the
- * "direction" of time (and not in the direction of attributes, as is the
- * case with loadStateAtTime()).
- *
- * @param attributeQuark
- * Which attribute this query is interested in
- * @param t1
- * Start time of the range query
- * @param t2
- * Target end time of the query. If t2 is greater than the end of
- * the trace, we will return what we have up to the end of the
- * history.
- * @return The List of state intervals that happened between t1 and t2
- * @throws TimeRangeException
- * If t1 is invalid, or if t2 <= t1
- * @throws AttributeNotFoundException
- * If the requested quark does not exist in the model.
- */
+ @Override
public List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
long t1, long t2) throws TimeRangeException,
AttributeNotFoundException {
return intervals;
}
- /**
- * Return the state history of a given attribute, but with at most one
- * update per "resolution". This can be useful for populating views (where
- * it's useless to have more than one query per pixel, for example).
- *
- * @param attributeQuark
- * Which attribute this query is interested in
- * @param t1
- * Start time of the range query
- * @param t2
- * Target end time of the query. If t2 is greater than the end of
- * the trace, we will return what we have up to the end of the
- * history.
- * @param resolution
- * The "step" of this query
- * @return The List of states that happened between t1 and t2
- * @throws TimeRangeException
- * If t1 is invalid, or if t2 <= t1
- * @throws AttributeNotFoundException
- * If the attribute doesn't exist
- */
+ @Override
public List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
long t1, long t2, long resolution) throws TimeRangeException,
AttributeNotFoundException {
* will be built underneath (no information will be saved to disk) and it will
* only be able to respond to queries to the current, latest time.
*
+ * (See IStateSystemQuerier and IStateSystemBuilder for the Javadoc.)
+ *
* @author alexmont
*
*/
* @name Quark-retrieving methods
*/
- /**
- * Basic quark-retrieving method. Pass an attribute in parameter as an array
- * of strings, the matching quark will be returned.
- *
- * This version will NOT create any new attributes. If an invalid attribute
- * is requested, an exception will be thrown. This should ideally be used
- * for doing read-only operations on the system, like queries for example.
- *
- * @param attribute
- * Attribute given as its full path in the Attribute Tree
- * @return The quark of the requested attribute, if it existed.
- * @throws AttributeNotFoundException
- * This exception is thrown if the requested attribute simply
- * did not exist in the system.
- */
public int getQuarkAbsolute(String... attribute)
throws AttributeNotFoundException {
return attributeTree.getQuarkDontAdd(-1, attribute);
}
- /**
- * Basic quark-retrieving method. Pass an attribute in parameter as an array
- * of strings, the matching quark will be returned.
- *
- * This version WILL create new attributes: if the attribute passed in
- * parameter is new in the system, it will be added and its new quark will
- * be returned.
- *
- * @param attribute
- * Attribute given as its full path in the Attribute Tree
- * @return The quark of the attribute (which either existed or just got
- * created)
- */
public int getQuarkAbsoluteAndAdd(String... attribute) {
return attributeTree.getQuarkAndAdd(-1, attribute);
}
- /**
- * "Relative path" quark-getting method. Instead of specifying a full path,
- * if you know the path is relative to another attribute for which you
- * already have the quark, use this for better performance.
- *
- * This is useful for cases where a lot of modifications or queries will
- * originate from the same branch of the attribute tree : the common part of
- * the path won't have to be re-hashed for every access.
- *
- * This version will NOT create any new attributes. If an invalid attribute
- * is requested, an exception will be thrown. This should ideally be used
- * for doing read-only operations on the system, like queries for example.
- *
- * @param startingNodeQuark
- * The quark of the attribute from which 'subPath' originates.
- * @param subPath
- * "Rest" of the path to get to the final attribute
- * @return The matching quark, if it existed
- * @throws AttributeNotFoundException
- */
public int getQuarkRelative(int startingNodeQuark, String... subPath)
throws AttributeNotFoundException {
return attributeTree.getQuarkDontAdd(startingNodeQuark, subPath);
}
- /**
- * "Relative path" quark-getting method. Instead of specifying a full path,
- * if you know the path is relative to another attribute for which you
- * already have the quark, use this for better performance.
- *
- * This is useful for cases where a lot of modifications or queries will
- * originate from the same branch of the attribute tree : the common part of
- * the path won't have to be re-hashed for every access.
- *
- * This version WILL create new attributes: if the attribute passed in
- * parameter is new in the system, it will be added and its new quark will
- * be returned.
- *
- * @param startingNodeQuark
- * The quark of the attribute from which 'subPath' originates.
- * @param subPath
- * "Rest" of the path to get to the final attribute
- * @return The matching quark, either if it's new of just got created.
- */
public int getQuarkRelativeAndAdd(int startingNodeQuark, String... subPath) {
return attributeTree.getQuarkAndAdd(startingNodeQuark, subPath);
}
- /**
- * Return the sub-attributes of the target attribute, as a List of quarks.
- *
- * @param quark
- * The attribute of which you want to sub-attributes. You can use
- * "-1" here to specify the root node.
- * @param recursive
- * True if you want all recursive sub-attributes, false if you
- * only want the first level.
- * @return A List of integers, matching the quarks of the sub-attributes.
- * @throws AttributeNotFoundException
- * If the quark was not existing or invalid.
- */
public List<Integer> getSubAttributes(int quark, boolean recursive)
throws AttributeNotFoundException {
return attributeTree.getSubAttributes(quark, recursive);
}
- /**
- * Batch quark-retrieving method. This method allows you to specify a path
- * pattern which includes a wildcard "*" somewhere. It will check all the
- * existing attributes in the attribute tree and return those who match the
- * pattern.
- *
- * For example, passing ("Threads", "*", "Exec_mode") will return the list
- * of quarks for attributes "Threads/1000/Exec_mode",
- * "Threads/1500/Exec_mode", and so on, depending on what exists at this
- * time in the attribute tree.
- *
- * If no wildcard is specified, the behavior is the same as
- * getQuarkAbsolute() (except it will return a List with one entry). This
- * method will never create new attributes.
- *
- * Only one wildcard "*" is supported at this time.
- *
- * @param pattern
- * The array of strings representing the pattern to look for. It
- * should ideally contain one entry that is only a "*".
- * @return A List of attribute quarks, representing attributes that matched
- * the pattern. If no attribute matched, the list will be empty (but
- * not null).
- */
public List<Integer> getQuarks(String... pattern) {
List<Integer> quarks = new LinkedList<Integer>();
List<String> prefix = new LinkedList<String>();
* @name External methods related to insertions in the history -
*/
- /**
- * Basic attribute modification method, we simply specify a new value, for a
- * given attribute, effective at the given timestamp.
- *
- * @param t
- * Timestamp of the state change
- * @param value
- * The State Value we want to assign to the attribute
- * @param attributeQuark
- * Integer value of the quark corresponding to the attribute we
- * want to modify
- * @throws TimeRangeException
- * If the requested time is outside of the trace's range
- * @throws AttributeNotFoundException
- * If the requested attribute quark is invalid
- * @throws StateValueTypeException
- * If the inserted state value's type does not match what is
- * already assigned to this attribute.
- */
public void modifyAttribute(long t, ITmfStateValue value, int attributeQuark)
throws TimeRangeException, AttributeNotFoundException,
StateValueTypeException {
transState.processStateChange(t, value, attributeQuark);
}
- /**
- * Increment attribute method. Reads the current value of a given integer
- * attribute (this value is right now in the Transient State), and increment
- * it by 1. Useful for statistics.
- *
- * @param t
- * Timestamp of the state change
- * @param attributeQuark
- * Attribute to increment. If it doesn't exist it will be added,
- * with a new value of 1.
- * @throws StateValueTypeException
- * If the attribute already exists but is not of type Integer
- * @throws TimeRangeException
- * If the given timestamp is invalid
- * @throws AttributeNotFoundException
- * If the quark is invalid
- */
public void incrementAttribute(long t, int attributeQuark)
throws StateValueTypeException, TimeRangeException,
AttributeNotFoundException {
attributeQuark);
}
- /**
- * "Push" helper method. This uses the given integer attribute as a stack:
- * The value of that attribute will represent the stack depth (always >= 1).
- * Sub-attributes will be created, their base-name will be the position in
- * the stack (1, 2, etc.) and their value will be the state value 'value'
- * that was pushed to this position.
- *
- * @param t
- * Timestamp of the state change
- * @param value
- * State value to assign to this stack position.
- * @param attributeQuark
- * The base attribute to use as a stack. If it does not exist if
- * will be created (with depth = 1)
- * @throws TimeRangeException
- * If the requested timestamp is invalid
- * @throws AttributeNotFoundException
- * If the attribute is invalid
- * @throws StateValueTypeException
- * If the attribute 'attributeQuark' already exists, but is not
- * of integer type.
- */
public void pushAttribute(long t, ITmfStateValue value, int attributeQuark)
throws TimeRangeException, AttributeNotFoundException,
StateValueTypeException {
modifyAttribute(t, value, subAttributeQuark);
}
- /**
- * Antagonist of the pushAttribute(), pops the top-most attribute on the
- * stack-attribute. If this brings it back to depth = 0, the attribute is
- * kept with depth = 0. If the value is already 0, or if the attribute
- * doesn't exist, nothing is done.
- *
- * @param t
- * Timestamp of the state change
- * @param attributeQuark
- * Quark of the stack-attribute to pop
- * @throws AttributeNotFoundException
- * If the attribute is invalid
- * @throws TimeRangeException
- * If the timestamp is invalid
- * @throws StateValueTypeException
- * If the target attribute already exists, but its state value
- * type is invalid (not an integer)
- */
public void popAttribute(long t, int attributeQuark)
throws AttributeNotFoundException, TimeRangeException,
StateValueTypeException {
removeAttribute(t, subAttributeQuark);
}
- /**
- * Remove attribute method. Similar to the above modify- methods, with value
- * = 0 / null, except we will also "nullify" all the sub-contents of the
- * requested path (a bit like "rm -rf")
- *
- * @param t
- * Timestamp of the state change
- * @param attributeQuark
- * Attribute to remove
- * @throws TimeRangeException
- * If the timestamp is invalid
- * @throws AttributeNotFoundException
- * If the quark is invalid
- */
public void removeAttribute(long t, int attributeQuark)
throws TimeRangeException, AttributeNotFoundException {
assert (attributeQuark >= 0);
* @name "Current" query/update methods -
*/
- /**
- * Returns the current state value we have (in the Transient State) for the
- * given attribute.
- *
- * This is useful even for a StateHistorySystem, as we are guaranteed it
- * will only do a memory access and not go look on disk (and we don't even
- * have to provide a timestamp!)
- *
- * @param attributeQuark
- * For which attribute we want the current state
- * @return The State value that's "current" for this attribute
- * @throws AttributeNotFoundException
- * If the requested attribute is invalid
- */
public ITmfStateValue queryOngoingState(int attributeQuark)
throws AttributeNotFoundException {
return transState.getOngoingStateValue(attributeQuark);
}
- /**
- * Modify a current "ongoing" state (instead of inserting a state change,
- * like modifyAttribute() and others).
- *
- * This can be used to update the value of a previous state change, for
- * example when we get information at the end of the state and not at the
- * beginning. (return values of system calls, etc.)
- *
- * Note that past states can only be modified while they are still in
- * memory, so only the "current state" can be updated. Once they get
- * committed to disk (by inserting a new state change) it becomes too late.
- *
- * @param newValue
- * The new value that will overwrite the "current" one.
- * @param attributeQuark
- * For which attribute in the system
- * @throws AttributeNotFoundException
- * If the requested attribute is invalid
- */
public void updateOngoingState(ITmfStateValue newValue, int attributeQuark)
throws AttributeNotFoundException {
transState.changeOngoingStateValue(attributeQuark, newValue);
}
- /**
- * Return the name assigned to this quark. This returns only the "basename",
- * not the complete path to this attribute.
- *
- * @param attributeQuark
- * The quark for which we want the name
- * @return The name of the quark
- */
public String getAttributeName(int attributeQuark) {
return attributeTree.getAttributeName(attributeQuark);
}
- /**
- * @name Debugging methods
- */
-
- /**
- * This returns the slash-separated path of an attribute by providing its
- * quark
- *
- * @param attributeQuark
- * The quark of the attribute we want
- * @return One single string separated with '/', like a filesystem path
- */
public String getFullAttributePath(int attributeQuark) {
return attributeTree.getFullAttributeName(attributeQuark);
}
import java.io.IOException;
import org.eclipse.linuxtools.tmf.core.statesystem.StateHistorySystem;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
/**
* This is the high-level wrapper around the State History and its input and
public class HistoryBuilder implements Runnable {
private final IStateChangeInput sci;
- private final StateSystem ss;
+ private final StateHistorySystem shs;
private final IStateHistoryBackend hb;
private final Thread sciThread;
public HistoryBuilder(IStateChangeInput stateChangeInput,
IStateHistoryBackend backend) throws IOException {
assert (stateChangeInput != null);
- /* "backend" can be null, this implies no history */
- sci = stateChangeInput;
+ assert (backend != null);
- if (backend == null) {
- hb = null;
- ss = new StateSystem();
- } else {
- hb = backend;
- ss = new StateHistorySystem(hb, true);
- }
+ sci = stateChangeInput;
+ hb = backend;
+ shs = new StateHistorySystem(hb, true);
- sci.assignTargetStateSystem(ss);
+ sci.assignTargetStateSystem(shs);
sciThread = new Thread(sci, "Input Plugin"); //$NON-NLS-1$
}
+ /**
+ * Factory-style method to open an existing history, you only have to
+ * provide the already-instantiated IStateHistoryBackend object.
+ *
+ * @param hb
+ * The history-backend object
+ * @return A IStateSystemBuilder reference to the new state system. If you
+ * will only run queries on this history, you should *definitely*
+ * cast it to IStateSystemQuerier.
+ * @throws IOException
+ * If there was something wrong.
+ */
+ public static IStateSystemBuilder openExistingHistory(
+ IStateHistoryBackend hb) throws IOException {
+ return new StateHistorySystem(hb, false);
+ }
+
@Override
public void run() {
sciThread.start();
}
/**
- * Return the StateSystem (or StateHistorySystem) object that was created by
- * this builder. You will need this reference to run queries.
+ * Return a read/write reference to the state system object that was
+ * created.
+ *
+ * @return Reference to the state system, with access to everything.
+ */
+ public IStateSystemBuilder getStateSystemBuilder() {
+ return shs;
+ }
+
+ /**
+ * Return a read-only reference to the state system object that was created.
*
- * @return The StateSystem that was generated
+ * @return Reference to the state system, but only with the query methods
+ * available.
*/
- public StateSystem getSS() {
- return ss;
+ public IStateSystemQuerier getStateSystemQuerier() {
+ return shs;
}
}
\ No newline at end of file
package org.eclipse.linuxtools.tmf.core.statesystem.helpers;
-import org.eclipse.linuxtools.tmf.core.statesystem.StateSystem;
-
/**
* This is the interface used to define the "state change input", which is the
* main type of input that goes in the state system.
*
* This needs to be called before .run()!
*
- * @param ss
- */
- public void assignTargetStateSystem(StateSystem ss);
-
- /**
- * Return the State System that was assigned to this SCI.
- *
- * @return The target state system
+ * @param ssb
*/
- public StateSystem getStateSystem();
-
+ public void assignTargetStateSystem(IStateSystemBuilder ssb);
}
--- /dev/null
+/*******************************************************************************
+ * Copyright (c) 2012 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * Alexandre Montplaisir - Initial API
+ ******************************************************************************/
+
+package org.eclipse.linuxtools.tmf.core.statesystem.helpers;
+
+import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
+import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
+import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
+import org.eclipse.linuxtools.tmf.core.statevalue.StateValueTypeException;
+
+/**
+ * This is the external interface to build or modify an existing state history.
+ *
+ * It extends IStateSystemEnquirer, so you can still use it for reading the
+ * history, but it also provides write-access to it with the quark-creating and
+ * state-change insertion methods.
+ *
+ * @author alexmont
+ *
+ */
+public interface IStateSystemBuilder extends IStateSystemQuerier {
+
+ /**
+ * @name Read/write quark-getting methods
+ */
+
+ /**
+ * Basic quark-retrieving method. Pass an attribute in parameter as an array
+ * of strings, the matching quark will be returned.
+ *
+ * This version WILL create new attributes: if the attribute passed in
+ * parameter is new in the system, it will be added and its new quark will
+ * be returned.
+ *
+ * @param attribute
+ * Attribute given as its full path in the Attribute Tree
+ * @return The quark of the attribute (which either existed or just got
+ * created)
+ */
+ public int getQuarkAbsoluteAndAdd(String... attribute);
+
+ /**
+ * "Relative path" quark-getting method. Instead of specifying a full path,
+ * if you know the path is relative to another attribute for which you
+ * already have the quark, use this for better performance.
+ *
+ * This is useful for cases where a lot of modifications or queries will
+ * originate from the same branch of the attribute tree : the common part of
+ * the path won't have to be re-hashed for every access.
+ *
+ * This version WILL create new attributes: if the attribute passed in
+ * parameter is new in the system, it will be added and its new quark will
+ * be returned.
+ *
+ * @param startingNodeQuark
+ * The quark of the attribute from which 'subPath' originates.
+ * @param subPath
+ * "Rest" of the path to get to the final attribute
+ * @return The matching quark, either if it's new of just got created.
+ */
+ public int getQuarkRelativeAndAdd(int startingNodeQuark, String... subPath);
+
+ /**
+ * @name State-changing methods
+ */
+
+ /**
+ * Modify a current "ongoing" state (instead of inserting a state change,
+ * like modifyAttribute() and others).
+ *
+ * This can be used to update the value of a previous state change, for
+ * example when we get information at the end of the state and not at the
+ * beginning. (return values of system calls, etc.)
+ *
+ * Note that past states can only be modified while they are still in
+ * memory, so only the "current state" can be updated. Once they get
+ * committed to disk (by inserting a new state change) it becomes too late.
+ *
+ * @param newValue
+ * The new value that will overwrite the "current" one.
+ * @param attributeQuark
+ * For which attribute in the system
+ * @throws AttributeNotFoundException
+ * If the requested attribute is invalid
+ */
+ public void updateOngoingState(ITmfStateValue newValue, int attributeQuark)
+ throws AttributeNotFoundException;
+
+ /**
+ * Basic attribute modification method, we simply specify a new value, for a
+ * given attribute, effective at the given timestamp.
+ *
+ * @param t
+ * Timestamp of the state change
+ * @param value
+ * The State Value we want to assign to the attribute
+ * @param attributeQuark
+ * Integer value of the quark corresponding to the attribute we
+ * want to modify
+ * @throws TimeRangeException
+ * If the requested time is outside of the trace's range
+ * @throws AttributeNotFoundException
+ * If the requested attribute quark is invalid
+ * @throws StateValueTypeException
+ * If the inserted state value's type does not match what is
+ * already assigned to this attribute.
+ */
+ public void modifyAttribute(long t, ITmfStateValue value, int attributeQuark)
+ throws TimeRangeException, AttributeNotFoundException,
+ StateValueTypeException;
+
+ /**
+ * Increment attribute method. Reads the current value of a given integer
+ * attribute (this value is right now in the Transient State), and increment
+ * it by 1. Useful for statistics.
+ *
+ * @param t
+ * Timestamp of the state change
+ * @param attributeQuark
+ * Attribute to increment. If it doesn't exist it will be added,
+ * with a new value of 1.
+ * @throws StateValueTypeException
+ * If the attribute already exists but is not of type Integer
+ * @throws TimeRangeException
+ * If the given timestamp is invalid
+ * @throws AttributeNotFoundException
+ * If the quark is invalid
+ */
+ public void incrementAttribute(long t, int attributeQuark)
+ throws StateValueTypeException, TimeRangeException,
+ AttributeNotFoundException;
+
+ /**
+ * "Push" helper method. This uses the given integer attribute as a stack:
+ * The value of that attribute will represent the stack depth (always >= 1).
+ * Sub-attributes will be created, their base-name will be the position in
+ * the stack (1, 2, etc.) and their value will be the state value 'value'
+ * that was pushed to this position.
+ *
+ * @param t
+ * Timestamp of the state change
+ * @param value
+ * State value to assign to this stack position.
+ * @param attributeQuark
+ * The base attribute to use as a stack. If it does not exist if
+ * will be created (with depth = 1)
+ * @throws TimeRangeException
+ * If the requested timestamp is invalid
+ * @throws AttributeNotFoundException
+ * If the attribute is invalid
+ * @throws StateValueTypeException
+ * If the attribute 'attributeQuark' already exists, but is not
+ * of integer type.
+ */
+ public void pushAttribute(long t, ITmfStateValue value, int attributeQuark)
+ throws TimeRangeException, AttributeNotFoundException,
+ StateValueTypeException;
+
+ /**
+ * Antagonist of the pushAttribute(), pops the top-most attribute on the
+ * stack-attribute. If this brings it back to depth = 0, the attribute is
+ * kept with depth = 0. If the value is already 0, or if the attribute
+ * doesn't exist, nothing is done.
+ *
+ * @param t
+ * Timestamp of the state change
+ * @param attributeQuark
+ * Quark of the stack-attribute to pop
+ * @throws AttributeNotFoundException
+ * If the attribute is invalid
+ * @throws TimeRangeException
+ * If the timestamp is invalid
+ * @throws StateValueTypeException
+ * If the target attribute already exists, but its state value
+ * type is invalid (not an integer)
+ */
+ public void popAttribute(long t, int attributeQuark)
+ throws AttributeNotFoundException, TimeRangeException,
+ StateValueTypeException;
+
+ /**
+ * Remove attribute method. Similar to the above modify- methods, with value
+ * = 0 / null, except we will also "nullify" all the sub-contents of the
+ * requested path (a bit like "rm -rf")
+ *
+ * @param t
+ * Timestamp of the state change
+ * @param attributeQuark
+ * Attribute to remove
+ * @throws TimeRangeException
+ * If the timestamp is invalid
+ * @throws AttributeNotFoundException
+ * If the quark is invalid
+ */
+ public void removeAttribute(long t, int attributeQuark)
+ throws TimeRangeException, AttributeNotFoundException;
+
+ /**
+ * Method to close off the History Provider. This happens for example when
+ * we are done reading an off-line trace. First we close the TransientState,
+ * commit it to the Provider, mark it as inactive, then we write the
+ * Attribute Tree somewhere so we can reopen it later.
+ *
+ * @param endTime
+ * The requested End Time of the history, since it could be
+ * bigger than the timestamp of the last event or state change we
+ * have seen. All "ongoing" states will be extended until this
+ * 'endTime'.
+ * @throws TimeRangeException
+ * If the passed endTime doesn't make sense (for example, if
+ * it's earlier than the latest time) and the backend doesn't
+ * know how to handle it.
+ */
+ public void closeHistory(long endTime) throws TimeRangeException;
+}
--- /dev/null
+/*******************************************************************************
+ * Copyright (c) 2012 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * Alexandre Montplaisir - Initial API
+ ******************************************************************************/
+
+package org.eclipse.linuxtools.tmf.core.statesystem.helpers;
+
+import java.util.List;
+
+import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
+import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
+import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
+import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
+
+/**
+ * This is the read-only interface to the generic state system. It contains all
+ * the read-only quark-getting methods, as well as the history-querying ones.
+ *
+ * @author alexmont
+ *
+ */
+public interface IStateSystemQuerier {
+
+ /**
+ * Return the start time of this history. It usually matches the start time
+ * of the original trace.
+ *
+ * @return The history's registered start time
+ */
+ public long getStartTime();
+
+ /**
+ * Return the current end time of the history.
+ *
+ * @return
+ */
+ public long getCurrentEndTime();
+
+ /**
+ * @name Read-only quark-getting methods
+ */
+
+ /**
+ * Basic quark-retrieving method. Pass an attribute in parameter as an array
+ * of strings, the matching quark will be returned.
+ *
+ * This version will NOT create any new attributes. If an invalid attribute
+ * is requested, an exception will be thrown.
+ *
+ * @param attribute
+ * Attribute given as its full path in the Attribute Tree
+ * @return The quark of the requested attribute, if it existed.
+ * @throws AttributeNotFoundException
+ * This exception is thrown if the requested attribute simply
+ * did not exist in the system.
+ */
+ public int getQuarkAbsolute(String... attribute)
+ throws AttributeNotFoundException;
+
+ /**
+ * "Relative path" quark-getting method. Instead of specifying a full path,
+ * if you know the path is relative to another attribute for which you
+ * already have the quark, use this for better performance.
+ *
+ * This is useful for cases where a lot of modifications or queries will
+ * originate from the same branch of the attribute tree : the common part of
+ * the path won't have to be re-hashed for every access.
+ *
+ * This version will NOT create any new attributes. If an invalid attribute
+ * is requested, an exception will be thrown.
+ *
+ * @param startingNodeQuark
+ * The quark of the attribute from which 'subPath' originates.
+ * @param subPath
+ * "Rest" of the path to get to the final attribute
+ * @return The matching quark, if it existed
+ * @throws AttributeNotFoundException
+ */
+ public int getQuarkRelative(int startingNodeQuark, String... subPath)
+ throws AttributeNotFoundException;
+
+ /**
+ * Return the sub-attributes of the target attribute, as a List of quarks.
+ *
+ * @param quark
+ * The attribute of which you want to sub-attributes. You can use
+ * "-1" here to specify the root node.
+ * @param recursive
+ * True if you want all recursive sub-attributes, false if you
+ * only want the first level.
+ * @return A List of integers, matching the quarks of the sub-attributes.
+ * @throws AttributeNotFoundException
+ * If the quark was not existing or invalid.
+ */
+ public List<Integer> getSubAttributes(int quark, boolean recursive)
+ throws AttributeNotFoundException;
+
+ /**
+ * Batch quark-retrieving method. This method allows you to specify a path
+ * pattern which includes a wildcard "*" somewhere. It will check all the
+ * existing attributes in the attribute tree and return those who match the
+ * pattern.
+ *
+ * For example, passing ("Threads", "*", "Exec_mode") will return the list
+ * of quarks for attributes "Threads/1000/Exec_mode",
+ * "Threads/1500/Exec_mode", and so on, depending on what exists at this
+ * time in the attribute tree.
+ *
+ * If no wildcard is specified, the behavior is the same as
+ * getQuarkAbsolute() (except it will return a List with one entry). This
+ * method will never create new attributes.
+ *
+ * Only one wildcard "*" is supported at this time.
+ *
+ * @param pattern
+ * The array of strings representing the pattern to look for. It
+ * should ideally contain one entry that is only a "*".
+ * @return A List of attribute quarks, representing attributes that matched
+ * the pattern. If no attribute matched, the list will be empty (but
+ * not null).
+ */
+ public List<Integer> getQuarks(String... pattern);
+
+ /**
+ * Return the name assigned to this quark. This returns only the "basename",
+ * not the complete path to this attribute.
+ *
+ * @param attributeQuark
+ * The quark for which we want the name
+ * @return The name of the quark
+ */
+ public String getAttributeName(int attributeQuark);
+
+ /**
+ * This returns the slash-separated path of an attribute by providing its
+ * quark
+ *
+ * @param attributeQuark
+ * The quark of the attribute we want
+ * @return One single string separated with '/', like a filesystem path
+ */
+ public String getFullAttributePath(int attributeQuark);
+
+ /**
+ * @name Query methods
+ */
+
+ /**
+ * Returns the current state value we have (in the Transient State) for the
+ * given attribute.
+ *
+ * This is useful even for a StateHistorySystem, as we are guaranteed it
+ * will only do a memory access and not go look on disk (and we don't even
+ * have to provide a timestamp!)
+ *
+ * @param attributeQuark
+ * For which attribute we want the current state
+ * @return The State value that's "current" for this attribute
+ * @throws AttributeNotFoundException
+ * If the requested attribute is invalid
+ */
+ public ITmfStateValue queryOngoingState(int attributeQuark)
+ throws AttributeNotFoundException;
+
+ /**
+ * Load the complete state information at time 't' into the returned List.
+ * You can then get the intervals for single attributes by using
+ * List.get(n), where 'n' is the quark of the attribute.
+ *
+ * On average if you need around 10 or more queries for the same timestamps,
+ * use this method. If you need less than 10 (for example, running many
+ * queries for the same attributes but at different timestamps), you might
+ * be better using the querySingleState() methods instead.
+ *
+ * @param t
+ * We will recreate the state information to what it was at time
+ * t.
+ * @throws TimeRangeException
+ * If the 't' parameter is outside of the range of the state
+ * history.
+ */
+ public List<ITmfStateInterval> loadStateAtTime(long t)
+ throws TimeRangeException;
+
+ /**
+ * Singular query method. This one does not update the whole stateInfo
+ * vector, like loadStateAtTimes() does. It only searches for one specific
+ * entry in the state history.
+ *
+ * It should be used when you only want very few entries, instead of the
+ * whole state (or many entries, but all at different timestamps). If you do
+ * request many entries all at the same time, you should use the
+ * conventional loadStateAtTime() + List.get() method.
+ *
+ * @param t
+ * The timestamp at which we want the state
+ * @param attributeQuark
+ * Which attribute we want to get the state of
+ * @return The StateInterval representing the state
+ * @throws TimeRangeException
+ * If 't' is invalid
+ * @throws AttributeNotFoundException
+ * If the requested quark does not exist in the model
+ */
+ public ITmfStateInterval querySingleState(long t, int attributeQuark)
+ throws AttributeNotFoundException, TimeRangeException;
+
+ /**
+ * Return a list of state intervals, containing the "history" of a given
+ * attribute between timestamps t1 and t2. The list will be ordered by
+ * ascending time.
+ *
+ * Note that contrary to loadStateAtTime(), the returned list here is in the
+ * "direction" of time (and not in the direction of attributes, as is the
+ * case with loadStateAtTime()).
+ *
+ * @param attributeQuark
+ * Which attribute this query is interested in
+ * @param t1
+ * Start time of the range query
+ * @param t2
+ * Target end time of the query. If t2 is greater than the end of
+ * the trace, we will return what we have up to the end of the
+ * history.
+ * @return The List of state intervals that happened between t1 and t2
+ * @throws TimeRangeException
+ * If t1 is invalid, or if t2 <= t1
+ * @throws AttributeNotFoundException
+ * If the requested quark does not exist in the model.
+ */
+ public List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
+ long t1, long t2) throws TimeRangeException,
+ AttributeNotFoundException;
+
+ /**
+ * Return the state history of a given attribute, but with at most one
+ * update per "resolution". This can be useful for populating views (where
+ * it's useless to have more than one query per pixel, for example).
+ *
+ * @param attributeQuark
+ * Which attribute this query is interested in
+ * @param t1
+ * Start time of the range query
+ * @param t2
+ * Target end time of the query. If t2 is greater than the end of
+ * the trace, we will return what we have up to the end of the
+ * history.
+ * @param resolution
+ * The "step" of this query
+ * @return The List of states that happened between t1 and t2
+ * @throws TimeRangeException
+ * If t1 is invalid, or if t2 <= t1
+ * @throws AttributeNotFoundException
+ * If the attribute doesn't exist
+ */
+ public List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
+ long t1, long t2, long resolution) throws TimeRangeException,
+ AttributeNotFoundException;
+}
projects / deliverable / tracecompass.git / commitdiff
