org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/internal/statesystem/core/TransientState.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2014 Ericsson
   3  * Copyright (c) 2010, 2011 École Polytechnique de Montréal
   4  * Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
   5  *
   6  * All rights reserved. This program and the accompanying materials are
   7  * made available under the terms of the Eclipse Public License v1.0 which
   8  * accompanies this distribution, and is available at
   9  * http://www.eclipse.org/legal/epl-v10.html
  10  *
  11  *******************************************************************************/
  12
  13 package org.eclipse.tracecompass.internal.statesystem.core;
  14
  15 import java.io.PrintWriter;
  16 import java.util.ArrayList;
  17 import java.util.List;
  18 import java.util.concurrent.locks.ReentrantReadWriteLock;
  19
  20 import org.eclipse.jdt.annotation.NonNullByDefault;
  21 import org.eclipse.jdt.annotation.Nullable;
  22 import org.eclipse.tracecompass.statesystem.core.backend.IStateHistoryBackend;
  23 import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
  24 import org.eclipse.tracecompass.statesystem.core.exceptions.StateValueTypeException;
  25 import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
  26 import org.eclipse.tracecompass.statesystem.core.interval.ITmfStateInterval;
  27 import org.eclipse.tracecompass.statesystem.core.interval.TmfStateInterval;
  28 import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
  29 import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue.Type;
  30 import org.eclipse.tracecompass.statesystem.core.statevalue.TmfStateValue;
  31
  32 /**
  33  * The Transient State is used to build intervals from punctual state changes.
  34  * It contains a "state info" vector similar to the "current state", except here
  35  * we also record the start time of every state stored in it.
  36  *
  37  * We can then build {@link ITmfStateInterval}'s, to be inserted in a
  38  * {@link IStateHistoryBackend} when we detect state changes : the "start time"
  39  * of the interval will be the recorded time we have here, and the "end time"
  40  * will be the timestamp of the new state-changing event we just read.
  41  *
  42  * @author Alexandre Montplaisir
  43  */
  44 @NonNullByDefault
  45 public class TransientState {
  46
  47     /* Indicates where to insert state changes that we generate */
  48     private final IStateHistoryBackend fBackend;
  49
  50     private final ReentrantReadWriteLock fRWLock = new ReentrantReadWriteLock(false);
  51
  52     private volatile boolean fIsActive;
  53     private volatile long fLatestTime;
  54
  55     /* A method accessing these arrays will have to go through the lock */
  56     private List<ITmfStateValue> fOngoingStateInfo;
  57     private List<Long> fOngoingStateStartTimes;
  58     private List<Type> fStateValueTypes;
  59
  60     /**
  61      * Constructor
  62      *
  63      * @param backend
  64      *            The back-end in which to insert the generated state intervals
  65      */
  66     public TransientState(IStateHistoryBackend backend) {
  67         fBackend = backend;
  68         fIsActive = true;
  69         fOngoingStateInfo = new ArrayList<>();
  70         fOngoingStateStartTimes = new ArrayList<>();
  71         fStateValueTypes = new ArrayList<>();
  72
  73         fLatestTime = backend.getStartTime();
  74     }
  75
  76     /**
  77      * Get the latest time we have seen so far.
  78      *
  79      * @return The latest time seen in the transient state
  80      */
  81     public long getLatestTime() {
  82         return fLatestTime;
  83     }
  84
  85     /**
  86      * Retrieve the ongoing state value for a given index (attribute quark).
  87      *
  88      * @param quark
  89      *            The quark of the attribute to look for
  90      * @return The corresponding state value
  91      * @throws AttributeNotFoundException
  92      *             If the quark is invalid
  93      */
  94     public ITmfStateValue getOngoingStateValue(int quark) throws AttributeNotFoundException {
  95         fRWLock.readLock().lock();
  96         try {
  97             checkValidAttribute(quark);
  98             ITmfStateValue ret = fOngoingStateInfo.get(quark);
  99             if (ret == null) {
 100                 throw new IllegalStateException("Null interval stored in transient state"); //$NON-NLS-1$
 101             }
 102             return ret;
 103         } finally {
 104             fRWLock.readLock().unlock();
 105         }
 106     }
 107
 108     /**
 109      * Retrieve the start time of the state in which the given attribute is in.
 110      *
 111      * @param quark
 112      *            The quark of the attribute to look for
 113      * @return The start time of the current state for this attribute
 114      * @throws AttributeNotFoundException
 115      *             If the quark is invalid
 116      */
 117     public long getOngoingStartTime(int quark) throws AttributeNotFoundException {
 118         fRWLock.readLock().lock();
 119         try {
 120             checkValidAttribute(quark);
 121             return fOngoingStateStartTimes.get(quark);
 122         } finally {
 123             fRWLock.readLock().unlock();
 124         }
 125     }
 126
 127     /**
 128      * Modify the current state for a given attribute. This will not update the
 129      * "ongoing state start time" in any way, so be careful when using this.
 130      *
 131      * @param quark
 132      *            The quark of the attribute to modify
 133      * @param newValue
 134      *            The state value the attribute should have
 135      * @throws AttributeNotFoundException
 136      *             If the quark is invalid
 137      */
 138     public void changeOngoingStateValue(int quark, ITmfStateValue newValue)
 139             throws AttributeNotFoundException {
 140         fRWLock.writeLock().lock();
 141         try {
 142             checkValidAttribute(quark);
 143             fOngoingStateInfo.set(quark, newValue);
 144         } finally {
 145             fRWLock.writeLock().unlock();
 146         }
 147     }
 148
 149     /**
 150      * Convenience method to return the "ongoing" value for a given attribute as
 151      * a dummy interval whose end time = the current latest time.
 152      *
 153      * @param quark
 154      *            The quark of the attribute
 155      * @return An interval representing the current state (but whose end time is
 156      *         the current one, and probably not the "final" one)
 157      * @throws AttributeNotFoundException
 158      *             If the quark is invalid
 159      */
 160     public ITmfStateInterval getOngoingInterval(int quark) throws AttributeNotFoundException {
 161         fRWLock.readLock().lock();
 162         try {
 163             checkValidAttribute(quark);
 164             return new TmfStateInterval(fOngoingStateStartTimes.get(quark), fLatestTime,
 165                     quark, fOngoingStateInfo.get(quark));
 166         } finally {
 167             fRWLock.readLock().unlock();
 168         }
 169     }
 170
 171     /**
 172      * Try to get the state interval valid for time/quark, if it is present in
 173      * this transient state. If it is not (for example, a new value is active
 174      * since after the specified timestamp) then null will be returned.
 175      *
 176      * @param time
 177      *            The timestamp to look for
 178      * @param quark
 179      *            The quark of the attribute to look for
 180      * @return The corresponding TmfStateInterval object if we could find it in
 181      *         this transient state, or null if we couldn't.
 182      */
 183     public @Nullable ITmfStateInterval getIntervalAt(long time, int quark) {
 184         fRWLock.readLock().lock();
 185         try {
 186             checkValidAttribute(quark);
 187             if (!isActive() || time < fOngoingStateStartTimes.get(quark)) {
 188                 return null;
 189             }
 190             return new TmfStateInterval(fOngoingStateStartTimes.get(quark),
 191                     fLatestTime, quark, fOngoingStateInfo.get(quark));
 192         } catch (AttributeNotFoundException e) {
 193             return null;
 194         } finally {
 195             fRWLock.readLock().unlock();
 196         }
 197     }
 198
 199     private void checkValidAttribute(int quark) throws AttributeNotFoundException {
 200         if (quark > fOngoingStateInfo.size() - 1 || quark < 0) {
 201             throw new AttributeNotFoundException();
 202         }
 203     }
 204
 205     /**
 206      * More advanced version of {@link #changeOngoingStateValue}. Replaces the
 207      * complete ongoingStateInfo in one go, and updates the
 208      * ongoingStateStartTimes and #stateValuesTypes accordingly. BE VERY CAREFUL
 209      * WITH THIS!
 210      *
 211      * @param newStateIntervals
 212      *            The List of intervals that will represent the new
 213      *            "ongoing state". Their end times don't matter, we will only
 214      *            check their value and start times.
 215      */
 216     public void replaceOngoingState(List<ITmfStateInterval> newStateIntervals) {
 217         final int size = newStateIntervals.size();
 218
 219         fRWLock.writeLock().lock();
 220         try {
 221             fOngoingStateInfo = new ArrayList<>(size);
 222             fOngoingStateStartTimes = new ArrayList<>(size);
 223             fStateValueTypes = new ArrayList<>(size);
 224
 225             for (ITmfStateInterval interval : newStateIntervals) {
 226                 fOngoingStateInfo.add(interval.getStateValue());
 227                 fOngoingStateStartTimes.add(interval.getStartTime());
 228                 fStateValueTypes.add(interval.getStateValue().getType());
 229             }
 230         } finally {
 231             fRWLock.writeLock().unlock();
 232         }
 233     }
 234
 235     /**
 236      * Add an "empty line" to both "ongoing..." vectors. This is needed so the
 237      * Ongoing... tables can stay in sync with the number of attributes in the
 238      * attribute tree, namely when we add sub-path attributes.
 239      */
 240     public void addEmptyEntry() {
 241         fRWLock.writeLock().lock();
 242         try {
 243             /*
 244              * Since this is a new attribute, we suppose it was in the
 245              * "null state" since the beginning (so we can have intervals
 246              * covering for all timestamps). A null interval will then get added
 247              * at the first state change.
 248              */
 249             fOngoingStateInfo.add(TmfStateValue.nullValue());
 250             fStateValueTypes.add(Type.NULL);
 251
 252             fOngoingStateStartTimes.add(fBackend.getStartTime());
 253         } finally {
 254             fRWLock.writeLock().unlock();
 255         }
 256     }
 257
 258     /**
 259      * Process a state change to be inserted in the history.
 260      *
 261      * @param eventTime
 262      *            The timestamp associated with this state change
 263      * @param value
 264      *            The new StateValue associated to this attribute
 265      * @param quark
 266      *            The quark of the attribute that is being modified
 267      * @throws TimeRangeException
 268      *             If 'eventTime' is invalid
 269      * @throws AttributeNotFoundException
 270      *             IF 'quark' does not represent an existing attribute
 271      * @throws StateValueTypeException
 272      *             If the state value to be inserted is of a different type of
 273      *             what was inserted so far for this attribute.
 274      */
 275     public void processStateChange(long eventTime, ITmfStateValue value, int quark)
 276             throws TimeRangeException, AttributeNotFoundException, StateValueTypeException {
 277         if (!this.fIsActive) {
 278             return;
 279         }
 280
 281         fRWLock.writeLock().lock();
 282         try {
 283             Type expectedSvType = fStateValueTypes.get(quark);
 284             checkValidAttribute(quark);
 285
 286             /*
 287              * Make sure the state value type we're inserting is the same as the
 288              * one registered for this attribute.
 289              */
 290             if (expectedSvType == Type.NULL) {
 291                 /*
 292                  * The value hasn't been used yet, set it to the value we're
 293                  * currently inserting (which might be null/-1 again).
 294                  */
 295                 fStateValueTypes.set(quark, value.getType());
 296             } else if ((value.getType() != Type.NULL) && (value.getType() != expectedSvType)) {
 297                 /*
 298                  * We authorize inserting null values in any type of attribute,
 299                  * but for every other types, it needs to match our
 300                  * expectations!
 301                  */
 302                 throw new StateValueTypeException();
 303             }
 304
 305             if (fOngoingStateInfo.get(quark).equals(value)) {
 306                 /*
 307                  * This is the case where the new value and the one already
 308                  * present in the Builder are the same. We do not need to create
 309                  * an interval, we'll just keep the current one going.
 310                  */
 311                 return;
 312             }
 313
 314             if (fOngoingStateStartTimes.get(quark) < eventTime) {
 315                 /*
 316                  * These two conditions are necessary to create an interval and
 317                  * update ongoingStateInfo.
 318                  */
 319                 fBackend.insertPastState(fOngoingStateStartTimes.get(quark),
 320                         eventTime - 1, /* End Time */
 321                         quark, /* attribute quark */
 322                         fOngoingStateInfo.get(quark)); /* StateValue */
 323
 324                 fOngoingStateStartTimes.set(quark, eventTime);
 325             }
 326             fOngoingStateInfo.set(quark, value);
 327
 328             /* Update the Transient State's lastestTime, if needed */
 329             if (fLatestTime < eventTime) {
 330                 fLatestTime = eventTime;
 331             }
 332
 333         } finally {
 334             fRWLock.writeLock().unlock();
 335         }
 336     }
 337
 338     /**
 339      * Run a "get state at time" query on the Transient State only.
 340      *
 341      * @param stateInfo
 342      *            The stateInfo object in which we will put our relevant
 343      *            information
 344      * @param t
 345      *            The requested timestamp
 346      */
 347     public void doQuery(List<ITmfStateInterval> stateInfo, long t) {
 348         fRWLock.readLock().lock();
 349         try {
 350             if (!this.fIsActive) {
 351                 return;
 352             }
 353             if (stateInfo.size() > fOngoingStateInfo.size()) {
 354                 throw new IllegalArgumentException();
 355             }
 356
 357             for (int i = 0; i < stateInfo.size(); i++) {
 358                 /*
 359                  * We build a dummy interval whose end time =
 360                  * "current transient state end time" to put in the answer to
 361                  * the query.
 362                  */
 363                 final ITmfStateInterval interval = getIntervalAt(t, i);
 364                 if (interval != null) {
 365                     stateInfo.set(i, interval);
 366                 }
 367             }
 368         } finally {
 369             fRWLock.readLock().unlock();
 370         }
 371     }
 372
 373     /**
 374      * Close off the Transient State, used for example when we are done reading
 375      * a static trace file. All the information currently contained in it will
 376      * be converted to intervals and "flushed" to the state history.
 377      *
 378      * @param endTime
 379      *            The timestamp to use as end time for the state history (since
 380      *            it may be different than the timestamp of the last state
 381      *            change)
 382      */
 383     public void closeTransientState(long endTime) {
 384         if (!this.fIsActive) {
 385             return;
 386         }
 387
 388         fRWLock.writeLock().lock();
 389         try {
 390             for (int i = 0; i < fOngoingStateInfo.size(); i++) {
 391                 if (fOngoingStateStartTimes.get(i) > endTime) {
 392                     /*
 393                      * Handle the cases where trace end > timestamp of last
 394                      * state change. This can happen when inserting "future"
 395                      * changes.
 396                      */
 397                     continue;
 398                 }
 399                 try {
 400                     fBackend.insertPastState(fOngoingStateStartTimes.get(i),
 401                             endTime, /* End Time */
 402                             i, /* attribute quark */
 403                             fOngoingStateInfo.get(i)); /* StateValue */
 404
 405                 } catch (TimeRangeException e) {
 406                     /*
 407                      * This shouldn't happen, since we control where the
 408                      * interval's start time comes from
 409                      */
 410                     throw new IllegalStateException(e);
 411                 }
 412             }
 413
 414             fOngoingStateInfo.clear();
 415             fOngoingStateStartTimes.clear();
 416             this.fIsActive = false;
 417
 418         } finally {
 419             fRWLock.writeLock().unlock();
 420         }
 421     }
 422
 423     /**
 424      * Simply returns if this Transient State is currently being used or not
 425      *
 426      * @return True if this transient state is active
 427      */
 428     public boolean isActive() {
 429         return this.fIsActive;
 430     }
 431
 432     /**
 433      * Mark this transient state as inactive
 434      */
 435     public void setInactive() {
 436         fIsActive = false;
 437     }
 438
 439     /**
 440      * Debugging method that prints the contents of the transient state
 441      *
 442      * @param writer
 443      *            The writer to which the output should be written
 444      */
 445     public void debugPrint(PrintWriter writer) {
 446         /* Only used for debugging, shouldn't be externalized */
 447         writer.println("------------------------------"); //$NON-NLS-1$
 448         writer.println("Info stored in the Builder:"); //$NON-NLS-1$
 449         if (!this.fIsActive) {
 450             writer.println("Builder is currently inactive"); //$NON-NLS-1$
 451             writer.println('\n');
 452             return;
 453         }
 454         writer.println("\nAttribute\tStateValue\tValid since time"); //$NON-NLS-1$
 455         for (int i = 0; i < fOngoingStateInfo.size(); i++) {
 456             writer.format("%d\t\t", i); //$NON-NLS-1$
 457             writer.print(fOngoingStateInfo.get(i).toString() + "\t\t"); //$NON-NLS-1$
 458             writer.println(fOngoingStateStartTimes.get(i).toString());
 459         }
 460         writer.println('\n');
 461         return;
 462     }
 463
 464 }