* @param stateChangeInput
* The input plugin to use. This is required.
* @param backend
- * The backend storage to use. Use "null" here if you want a
- * state system with no history.
+ * The backend storage to use.
+ * @param buildManually
+ * Should we build this history in-band or not. True means we
+ * will start the building ourselves and block the caller until
+ * construction is done. False (out-of-band) means we will
+ * start listening for the signal and return immediately. Another
+ * signal will be sent when finished.
* @throws IOException
* Is thrown if anything went wrong (usually with the storage
* backend)
* construction.
*
* @param signal
+ * The "experiment range updated" signal. Listening to this
+ * signal will coalesce this request with the one from the
+ * indexer and histogram.
*/
@SuppressWarnings("unchecked")
@TmfSignalHandler
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
*******************************************************************************/
package org.eclipse.linuxtools.internal.tmf.core.statesystem;
* allows 'seeking' back in time to reload a Current State at a previous time.
* "How to go back in time" is defined by the implementation of the
* HistoryBackend.
- *
+ *
* A StateHistorySystem contains one and only one HistoryBackend. If you want to
* use a paradigm with more than one provider (eg. more or less precision
* depending on what's asked by the user), implement one wrapper HistoryBackend
* which can then contain your 2-3 other backends underneath.
- *
+ *
* @author alexmont
- *
+ *
*/
public interface IStateHistoryBackend {
/**
* Get the start time of this state history. This is usually the same as the
* start time of the originating trace.
- *
+ *
* @return The start time
*/
public long getStartTime();
/**
* Get the current end time of the state history. It will change as the
* history is being built.
- *
+ *
* @return The end time
*/
public long getEndTime();
/**
* Main method to insert state intervals into the history.
- *
+ *
* @param stateStartTime
* The start time of the interval
* @param stateEndTime
/**
* Indicate to the provider that we are done building the history (so it can
* close off, stop threads, etc.)
- *
+ *
* @param endTime
* The end time to assign to this state history. It could be
* farther in time than the last state inserted, for example.
* It is the responsibility of the backend to define where to save the
* Attribute Tree (since it's only useful to "reopen" an Attribute Tree if
* we have the matching History).
- *
+ *
* This method defines where to read for the attribute tree when opening an
* already-existing history. Refer to the file format documentation.
- *
+ *
* @return A FileInputStream object pointing to the correct file/location in
* the file where to read the attribute tree information.
*/
public FileInputStream supplyAttributeTreeReader();
// FIXME change to FOS too?
+ /**
+ * Supply the File object to which we will write the attribute tree. The
+ * position in this file is supplied by -TreeWriterFilePosition.
+ *
+ * @return The target File
+ */
public File supplyAttributeTreeWriterFile();
+ /**
+ * Supply the position in the file where we should write the attribute tree
+ * when asked to.
+ *
+ * @return The file position (we will seek() to it)
+ */
public long supplyAttributeTreeWriterFilePosition();
/**
* Delete any generated files or anything that might have been created by
* the history backend (either temporary or save files). By calling this, we
* return to the state as it was before ever building the history.
- *
+ *
* You might not want to call automatically if, for example, you want an
* index file to persist on disk. This could be limited to actions
* originating from the user.
* an "out" parameter, that is, write to it the needed information and
* return. DO NOT 'new' currentStateInfo, it will be lost and nothing will
* be returned!
- *
+ *
* @param currentStateInfo
* List of StateValues (index == quark) to fill up
* @param t
* Target timestamp of the query
+ * @throws TimeRangeException
+ * If the timestamp is outside of the history/trace
*/
public void doQuery(List<ITmfStateInterval> currentStateInfo, long t)
throws TimeRangeException;
* single StateValue instead of updating the whole list. If the method to
* use is the same, then feel free to just implement this as a wrapper using
* doQuery().
- *
+ *
* @param t
* The target timestamp of the query.
* @param attributeQuark
*/
public ITmfStateInterval doSingularQuery(long t, int attributeQuark)
throws TimeRangeException, AttributeNotFoundException;
-
+
/**
* Simple check to make sure the requested timestamps are within the borders
- * of this state history. This is used internally, but could also be used
- * by the request sender (to check before sending in a lot of requests for
+ * of this state history. This is used internally, but could also be used by
+ * the request sender (to check before sending in a lot of requests for
* example).
- *
+ *
* @param t
* The queried timestamp
* @return True if the timestamp is within range, false if not.
/**
* Debug method to print the contents of the history backend.
- *
+ *
* @param writer
* The PrintWriter where to write the output
*/
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
*******************************************************************************/
package org.eclipse.linuxtools.internal.tmf.core.statesystem;
* This is the extension of the StateSystem, which will save the state intervals
* that are created from the transient state (instead of discarding them, like a
* simple StateSystem would do).
- *
+ *
* This allows the user to then run queries at past timestamps.
- *
+ *
* DON'T FORGET to call .closeHistory() when you are done inserting intervals,
* or the storage backend will have no way of knowing it can close and write
* itself to disk, and its thread will keep running.
- *
+ *
* @author alexmont
- *
+ *
*/
public class StateHistorySystem extends StateSystem implements
IStateSystemBuilder {
/**
* General constructor
- *
+ *
* @param backend
* The "state history storage" backend to use.
* @param newFile
* Put true if this is a new history started from scratch. It is
* used to tell the state system where to get its attribute tree.
* @throws IOException
+ * If there was a problem creating the new history file
*/
public StateHistorySystem(IStateHistoryBackend backend, boolean newFile)
throws IOException {
if (currentInterval.getEndTime() < tEnd) {
currentInterval = querySingleState(tEnd, attributeQuark);
intervals.add(currentInterval);
- }
+ }
return intervals;
}
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
*******************************************************************************/
package org.eclipse.linuxtools.internal.tmf.core.statesystem;
/**
* This is the base class for the StateHistorySystem. It contains all the
* current-state-updating methods.
- *
+ *
* It's not abstract, as it can be used by itself: in this case, no History tree
* 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
- *
+ *
*/
+@SuppressWarnings("javadoc") // the javadoc is in the IStateSystem* interfaces
public class StateSystem {
/* References to the inner structures */
/**
* Print out the contents of the inner structures.
- *
+ *
* @param writer
* The PrintWriter in which to print the output
*/
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
*******************************************************************************/
package org.eclipse.linuxtools.internal.tmf.core.statesystem.historytree;
/**
* History Tree backend for storing a state history. This is the basic version
* that runs in the same thread as the class creating it.
- *
+ *
* @author alexmont
- *
+ *
*/
public class HistoryTreeBackend implements IStateHistoryBackend {
/**
* Construtor for new history files. Use this when creating a new history
* from scratch.
- *
+ *
* @param newStateFile
* The filename/location where to store the state history (Should
* end in .ht)
* Construtor for new history files. Use this when creating a new history
* from scratch. This version supplies sane defaults for the configuration
* parameters.
- *
+ *
* @param newStateFile
* The filename/location where to store the state history (Should
* end in .ht)
/**
* Existing history constructor. Use this to open an existing state-file.
- *
+ *
* @param existingStateFile
* Filename/location of the history we want to load
* @throws IOException
/**
* Inner method to find the interval in the tree containing the requested
* key/timestamp pair, wherever in which node it is.
- *
+ *
* @param t
* @param key
* @return The node containing the information we want
/**
* Return the size of the tree history file
- *
+ *
* @return The current size of the history file in bytes
*/
public long getFileSize() {
/**
* Return the current depth of the tree, ie the number of node levels.
- *
+ *
* @return The tree depth
*/
public int getTreeDepth() {
/**
* Return the average node usage as a percentage (between 0 and 100)
- *
+ *
* @return Average node usage %
*/
public int getAverageNodeUsage() {
/**
* The basic debugPrint method will print the tree structure, but not their
* contents.
- *
+ *
* This method here print the contents (the intervals) as well.
- *
+ *
* @param writer
+ * The PrintWriter to which the debug info will be written
* @param printIntervals
+ * Should we also print every contained interval individually?
*/
public void debugPrint(PrintWriter writer, boolean printIntervals) {
/* Only used for debugging, shouldn't be externalized */
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
*******************************************************************************/
package org.eclipse.linuxtools.tmf.core.interval;
* The StateInterval represents the "state" a particular attribute was in, at a
* given time. It is the main object being returned from queries to the state
* system.
- *
+ *
- *
+ *
* @author alexmont
- *
+ *
*/
public final class TmfStateInterval implements ITmfStateInterval {
/**
* Construct an interval from its given parameters
- *
+ *
* @param start
+ * Start time
* @param end
+ * End time
* @param attribute
+ * Attribute linked to this interval
* @param sv
+ * State value this interval will contain
*/
public TmfStateInterval(long start, long end, int attribute,
ITmfStateValue sv) {
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
*******************************************************************************/
package org.eclipse.linuxtools.tmf.core.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.
- *
+ *
* Usually a state change input, also called "state provider" is the piece of
* the pipeline which converts trace events to state changes.
- *
+ *
* @author alexmont
- *
+ *
*/
public interface IStateChangeInput {
/**
* Get the trace with which this state input plugin is associated.
- *
+ *
* @return The associated trace
*/
@SuppressWarnings("rawtypes")
public ITmfTrace getTrace();
-
+
/**
* Return the start time of this "state change input", which is normally the
* start time of the originating trace (or it can be the time of the first
* state-changing event).
- *
+ *
* @return The start time
*/
public long getStartTime();
* Method for the input plugin to specify which type of events it expects.
* This will guarantee that all events it receives via processEvent() are
* indeed of the given type, so it should be safe to cast to that type.
- *
+ *
* @return An example event of the expected class, which implements
* ITmfEvent. The contents of that event doesn't matter, only the
* class will be checked.
* Assign the target state system where this SCI will insert its state
* changes. Because of dependencies issues, this can normally not be done at
* the constructor.
- *
+ *
* This needs to be called before .run()!
- *
+ *
* @param ssb
+ * Target state system for the state changes generated by this
+ * input plugin
*/
public void assignTargetStateSystem(IStateSystemBuilder ssb);
* Send an event to this input plugin for processing. The implementation
* should check the contents, and call the state-modifying methods of its
* IStateSystemBuilder object accordingly.
- *
+ *
* @param event
* The event (which should be safe to cast to the
* expectedEventType) that has to be processed.
/**
* 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
+ *
+ * @return The current end time of this state history
*/
public long getCurrentEndTime();
/**
* Return the current total amount of attributes in the system.
- *
- * @return
+ *
+ * @return The current number of attributes in the system
*/
public int getNbAttributes();
/**
* 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.
* "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
+ * If the quark is invalid
*/
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.
* 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 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
/**
* 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
/**
* 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
* 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.
+ * @return The List of intervals, where the offset = the quark
* @throws TimeRangeException
* If the 't' parameter is outside of the range of the state
* history.
* Singular query method. This one does not update the whole stateInfo
* vector, like queryFullState() 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 queryFullState() + List.get() method.
- *
+ *
* @param t
* The timestamp at which we want the state
* @param attributeQuark
* 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 queryFullState(), the returned list here is in the
* "direction" of time (and not in the direction of attributes, as is the
* case with queryFullState()).
- *
+ *
* @param attributeQuark
* Which attribute this query is interested in
* @param t1
* 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
* @return A IStateSystemQuerier handler to the state system, with which you
* can then run queries on the history.
* @throws TmfTraceException
+ * If there was a problem reading or writing one of the files.
+ * See the contents of this exception for more info.
*/
public static IStateSystemQuerier loadStateHistory(File htFile,
IStateChangeInput htInput, boolean buildManually)
/*******************************************************************************
* 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
******************************************************************************/
/**
* This is the interface for using state values and reading their contents.
- *
+ *
* @author alexmont
- *
+ *
*/
public interface ITmfStateValue {
+ /** The 'byte' value associated to null state values (-1) */
public static final byte TYPE_NULL = -1;
+
+ /** The 'byte' value associated to integer state values (0) */
public static final byte TYPE_INTEGER = 0;
+
+ /** The 'byte' value associated to null state values (1) */
public static final byte TYPE_STRING = 1;
/**
* Each implementation has to supply a "type" number. This will get written
* as-is in the History file to recognize the type, so it needs to be unique
- *
+ *
* @return The unique "int8" assigned to this state value type
*/
public byte getType();
/**
* Only "null values" should return true here
- *
+ *
* @return True if this type of SV is considered "null", false if it
* contains a real value.
*/
/**
* Read the contained value as an 'int' primitive
- *
+ *
* @return The integer contained in the state value
* @throws StateValueTypeException
* If the contained value cannot be read as an integer
/**
* Read the contained value as a String
- *
+ *
* @return The String contained in the state value
* @throws StateValueTypeException
* If the contained value cannot be read as a String
* Copyright (c) 2012 Ericsson
* Copyright (c) 2010, 2011 École Polytechnique de Montréal
* Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
- *
+ *
* 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
- *
+ *
******************************************************************************/
package org.eclipse.linuxtools.tmf.core.statevalue;
/**
* This is the wrapper class that exposes the different types of 'state values'
* available to use in the State System.
- *
+ *
* This also defines how these values are to be stored in the History Tree. For
* example, we can save numerical values as integers instead of arrays of
* 1-digit characters.
- *
+ *
* For now the two available types are either int or String.
- *
+ *
* @author alexmont
- *
+ *
*/
public abstract class TmfStateValue implements ITmfStateValue {
/**
* Retrieve directly the value object contained within. Implementing
* subclasses may limit the return type here.
- *
+ *
* It's protected, since we do not want to expose this directly in the
* public API (and require all its users to manually cast to the right
* types). All accesses to the values should go through the "unbox-"
* methods.
- *
+ *
* @return The underneath object assigned to this state value.
*/
protected abstract Object getValue();
* Alternatively you can return "null" here if you do not need a byte-array
* indirection (the getValue will get written as-in instead of the offset in
* the file block)
+ *
+ * @return The state value in byte array form
*/
public abstract byte[] toByteArray();
/**
* Return the max size that a variable-length state value can have when
* serialized.
- *
+ *
* @return The maximum size in bytes
*/
public static int getStateValueMaxSize() {
/**
* Return an instance of a "null" value. Only one copy exists in memory.
- *
+ *
* @return A null value
*/
public final static TmfStateValue nullValue() {
/**
* Factory constructor for Integer state values
- *
+ *
* @param intValue The integer value to contain
* @return The newly-created TmfStateValue object
*/
/**
* Factory constructor for String state values
- *
+ *
* @param strValue The string value to contain
* @return The newly-create TmfStateValue object
*/
projects / deliverable / tracecompass.git / commitdiff
