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

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