statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/internal/statesystem/core/backend/historytree/HistoryTreeBackend.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.backend.historytree;
  17
  18 import java.io.File;
  19 import java.io.FileInputStream;
  20 import java.io.IOException;
  21 import java.io.PrintWriter;
  22 import java.nio.channels.ClosedChannelException;
  23 import java.util.List;
  24
  25 import org.eclipse.jdt.annotation.NonNull;
  26 import org.eclipse.tracecompass.internal.statesystem.core.Activator;
  27 import org.eclipse.tracecompass.statesystem.core.backend.IStateHistoryBackend;
  28 import org.eclipse.tracecompass.statesystem.core.exceptions.StateSystemDisposedException;
  29 import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
  30 import org.eclipse.tracecompass.statesystem.core.interval.ITmfStateInterval;
  31 import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
  32 import org.eclipse.tracecompass.statesystem.core.statevalue.TmfStateValue;
  33
  34 import com.google.common.annotations.VisibleForTesting;
  35
  36 /**
  37  * History Tree backend for storing a state history. This is the basic version
  38  * that runs in the same thread as the class creating it.
  39  *
  40  * @author Alexandre Montplaisir
  41  */
  42 public class HistoryTreeBackend implements IStateHistoryBackend {
  43
  44     private final @NonNull String fSsid;
  45
  46     /**
  47      * The history tree that sits underneath.
  48      */
  49     private final @NonNull HistoryTree fSht;
  50
  51     /** Indicates if the history tree construction is done */
  52     private volatile boolean fFinishedBuilding = false;
  53
  54     /**
  55      * Indicates if the history tree construction is done
  56      *
  57      * @return if the history tree construction is done
  58      */
  59     protected boolean isFinishedBuilding() {
  60         return fFinishedBuilding;
  61     }
  62
  63     /**
  64      * Sets if the history tree is finished building
  65      *
  66      * @param isFinishedBuilding
  67      *            is the history tree finished building
  68      */
  69     protected void setFinishedBuilding(boolean isFinishedBuilding) {
  70         fFinishedBuilding = isFinishedBuilding;
  71     }
  72
  73     /**
  74      * Constructor for new history files. Use this when creating a new history
  75      * from scratch.
  76      *
  77      * @param ssid
  78      *            The state system's ID
  79      * @param newStateFile
  80      *            The filename/location where to store the state history (Should
  81      *            end in .ht)
  82      * @param providerVersion
  83      *            Version of of the state provider. We will only try to reopen
  84      *            existing files if this version matches the one in the
  85      *            framework.
  86      * @param startTime
  87      *            The earliest time stamp that will be stored in the history
  88      * @param blockSize
  89      *            The size of the blocks in the history file. This should be a
  90      *            multiple of 4096.
  91      * @param maxChildren
  92      *            The maximum number of children each core node can have
  93      * @throws IOException
  94      *             Thrown if we can't create the file for some reason
  95      */
  96     public HistoryTreeBackend(@NonNull String ssid,
  97             File newStateFile,
  98             int providerVersion,
  99             long startTime,
 100             int blockSize,
 101             int maxChildren) throws IOException {
 102         fSsid = ssid;
 103         final HTConfig conf = new HTConfig(newStateFile, blockSize, maxChildren,
 104                 providerVersion, startTime);
 105         fSht = initializeSHT(conf);
 106     }
 107
 108     /**
 109      * Constructor for new history files. Use this when creating a new history
 110      * from scratch. This version supplies sane defaults for the configuration
 111      * parameters.
 112      *
 113      * @param ssid
 114      *            The state system's id
 115      * @param newStateFile
 116      *            The filename/location where to store the state history (Should
 117      *            end in .ht)
 118      * @param providerVersion
 119      *            Version of of the state provider. We will only try to reopen
 120      *            existing files if this version matches the one in the
 121      *            framework.
 122      * @param startTime
 123      *            The earliest time stamp that will be stored in the history
 124      * @throws IOException
 125      *             Thrown if we can't create the file for some reason
 126      * @since 1.0
 127      */
 128     public HistoryTreeBackend(@NonNull String ssid, File newStateFile, int providerVersion, long startTime)
 129             throws IOException {
 130         this(ssid, newStateFile, providerVersion, startTime, 64 * 1024, 50);
 131     }
 132
 133     /**
 134      * Existing history constructor. Use this to open an existing state-file.
 135      *
 136      * @param ssid
 137      *            The state system's id
 138      * @param existingStateFile
 139      *            Filename/location of the history we want to load
 140      * @param providerVersion
 141      *            Expected version of of the state provider plugin.
 142      * @throws IOException
 143      *             If we can't read the file, if it doesn't exist, is not
 144      *             recognized, or if the version of the file does not match the
 145      *             expected providerVersion.
 146      */
 147     public HistoryTreeBackend(@NonNull String ssid, @NonNull File existingStateFile, int providerVersion)
 148             throws IOException {
 149         fSsid = ssid;
 150         fSht = initializeSHT(existingStateFile, providerVersion);
 151         fFinishedBuilding = true;
 152     }
 153
 154     /**
 155      * New-tree initializer for the History Tree wrapped by this backend. Can be
 156      * overriden to use different implementations.
 157      *
 158      * @param conf
 159      *            The HTConfig configuration object
 160      * @return The new history tree
 161      * @throws IOException
 162      *             If there was a problem during creation
 163      */
 164     @VisibleForTesting
 165     protected @NonNull HistoryTree initializeSHT(@NonNull HTConfig conf) throws IOException {
 166         return HistoryTreeFactory.createHistoryTree(conf);
 167     }
 168
 169     /**
 170      * Existing-tree initializer for the History Tree wrapped by this backend.
 171      * Can be overriden to use different implementations.
 172      *
 173      * @param existingStateFile
 174      *            The file to open
 175      * @param providerVersion
 176      *            The expected state provider version
 177      * @return The history tree opened from the given file
 178      * @throws IOException
 179      *             If there was a problem during creation
 180      */
 181     @VisibleForTesting
 182     protected @NonNull HistoryTree initializeSHT(@NonNull File existingStateFile, int providerVersion) throws IOException {
 183         return HistoryTreeFactory.createFromFile(existingStateFile.toPath(), providerVersion);
 184     }
 185
 186     /**
 187      * Get the History Tree built by this backend.
 188      *
 189      * Note: Do not override this method. If you want to extend the class to use
 190      * a different History Tree implementation, override both variants of
 191      * {@link #initializeSHT} instead.
 192      *
 193      * @return The history tree
 194      */
 195     protected final @NonNull HistoryTree getSHT() {
 196         return fSht;
 197     }
 198
 199     @Override
 200     public String getSSID() {
 201         return fSsid;
 202     }
 203
 204     @Override
 205     public long getStartTime() {
 206         return getSHT().getTreeStart();
 207     }
 208
 209     @Override
 210     public long getEndTime() {
 211         return getSHT().getTreeEnd();
 212     }
 213
 214     @Override
 215     public void insertPastState(long stateStartTime, long stateEndTime,
 216             int quark, ITmfStateValue value) throws TimeRangeException {
 217         HTInterval interval = new HTInterval(stateStartTime, stateEndTime,
 218                 quark, (TmfStateValue) value);
 219
 220         /* Start insertions at the "latest leaf" */
 221         getSHT().insertInterval(interval);
 222     }
 223
 224     @Override
 225     public void finishedBuilding(long endTime) {
 226         getSHT().closeTree(endTime);
 227         fFinishedBuilding = true;
 228     }
 229
 230     @Override
 231     public FileInputStream supplyAttributeTreeReader() {
 232         return getSHT().supplyATReader();
 233     }
 234
 235     @Override
 236     public File supplyAttributeTreeWriterFile() {
 237         return getSHT().supplyATWriterFile();
 238     }
 239
 240     @Override
 241     public long supplyAttributeTreeWriterFilePosition() {
 242         return getSHT().supplyATWriterFilePos();
 243     }
 244
 245     @Override
 246     public void removeFiles() {
 247         getSHT().deleteFile();
 248     }
 249
 250     @Override
 251     public void dispose() {
 252         if (fFinishedBuilding) {
 253             getSHT().closeFile();
 254         } else {
 255             /*
 256              * The build is being interrupted, delete the file we partially
 257              * built since it won't be complete, so shouldn't be re-used in the
 258              * future (.deleteFile() will close the file first)
 259              */
 260             getSHT().deleteFile();
 261         }
 262     }
 263
 264     @Override
 265     public void doQuery(List<ITmfStateInterval> stateInfo, long t)
 266             throws TimeRangeException, StateSystemDisposedException {
 267         checkValidTime(t);
 268
 269         /* We start by reading the information in the root node */
 270         HTNode currentNode = getSHT().getRootNode();
 271         currentNode.writeInfoFromNode(stateInfo, t);
 272
 273         /* Then we follow the branch down in the relevant children */
 274         try {
 275             while (currentNode.getNodeType() == HTNode.NodeType.CORE) {
 276                 currentNode = getSHT().selectNextChild((CoreNode) currentNode, t);
 277                 currentNode.writeInfoFromNode(stateInfo, t);
 278             }
 279         } catch (ClosedChannelException e) {
 280             throw new StateSystemDisposedException(e);
 281         }
 282
 283         /*
 284          * The stateInfo should now be filled with everything needed, we pass
 285          * the control back to the State System.
 286          */
 287     }
 288
 289     @Override
 290     public ITmfStateInterval doSingularQuery(long t, int attributeQuark)
 291             throws TimeRangeException, StateSystemDisposedException {
 292         return getRelevantInterval(t, attributeQuark);
 293     }
 294
 295     private void checkValidTime(long t) {
 296         long startTime = getStartTime();
 297         long endTime = getEndTime();
 298         if (t < startTime || t > endTime) {
 299             throw new TimeRangeException(String.format("%s Time:%d, Start:%d, End:%d", //$NON-NLS-1$
 300                     fSsid, t, startTime, endTime));
 301         }
 302     }
 303
 304     /**
 305      * Inner method to find the interval in the tree containing the requested
 306      * key/timestamp pair, wherever in which node it is.
 307      *
 308      * @param t
 309      * @param key
 310      * @return The node containing the information we want
 311      */
 312     private HTInterval getRelevantInterval(long t, int key)
 313             throws TimeRangeException, StateSystemDisposedException {
 314         checkValidTime(t);
 315
 316         HTNode currentNode = getSHT().getRootNode();
 317         HTInterval interval = currentNode.getRelevantInterval(key, t);
 318
 319         try {
 320             while (interval == null && currentNode.getNodeType() == HTNode.NodeType.CORE) {
 321                 currentNode = getSHT().selectNextChild((CoreNode) currentNode, t);
 322                 interval = currentNode.getRelevantInterval(key, t);
 323             }
 324         } catch (ClosedChannelException e) {
 325             throw new StateSystemDisposedException(e);
 326         }
 327         return interval;
 328     }
 329
 330     /**
 331      * Return the size of the tree history file
 332      *
 333      * @return The current size of the history file in bytes
 334      */
 335     public long getFileSize() {
 336         return getSHT().getFileSize();
 337     }
 338
 339     /**
 340      * Return the average node usage as a percentage (between 0 and 100)
 341      *
 342      * @return Average node usage %
 343      */
 344     public int getAverageNodeUsage() {
 345         HTNode node;
 346         long total = 0;
 347         long ret;
 348
 349         try {
 350             for (int seq = 0; seq < getSHT().getNodeCount(); seq++) {
 351                 node = getSHT().readNode(seq);
 352                 total += node.getNodeUsagePercent();
 353             }
 354         } catch (ClosedChannelException e) {
 355             Activator.getDefault().logError(e.getMessage(), e);
 356         }
 357
 358         ret = total / getSHT().getNodeCount();
 359         /* The return value should be a percentage */
 360         if (ret < 0 || ret > 100) {
 361             throw new IllegalStateException("Average node usage is not a percentage: " + ret); //$NON-NLS-1$
 362         }
 363         return (int) ret;
 364     }
 365
 366     @Override
 367     public void debugPrint(PrintWriter writer) {
 368         /* By default don't print out all the intervals */
 369         debugPrint(writer, false, -1);
 370     }
 371
 372     /**
 373      * The basic debugPrint method will print the tree structure, but not their
 374      * contents.
 375      *
 376      * This method here print the contents (the intervals) as well.
 377      *
 378      * @param writer
 379      *            The PrintWriter to which the debug info will be written
 380      * @param printIntervals
 381      *            Should we also print every contained interval individually?
 382      * @param ts
 383      *            The timestamp that nodes have to intersect for intervals to be
 384      *            printed. A negative value will print intervals for all nodes.
 385      *            The timestamp only applies if printIntervals is true.
 386      */
 387     public void debugPrint(PrintWriter writer, boolean printIntervals, long ts) {
 388         /* Only used for debugging, shouldn't be externalized */
 389         writer.println("------------------------------"); //$NON-NLS-1$
 390         writer.println("State History Tree:\n"); //$NON-NLS-1$
 391         writer.println(getSHT().toString());
 392         writer.println("Average node utilization: " //$NON-NLS-1$
 393                 + getAverageNodeUsage());
 394         writer.println(""); //$NON-NLS-1$
 395
 396         getSHT().debugPrintFullTree(writer, printIntervals, ts);
 397     }
 398 }