tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/statesystem/TmfAttributePool.java

   1 /*******************************************************************************
   2  * Copyright (c) 2016 École Polytechnique de Montréal
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *******************************************************************************/
   9
  10 package org.eclipse.tracecompass.tmf.core.statesystem;
  11
  12 import java.util.LinkedList;
  13 import java.util.PriorityQueue;
  14 import java.util.Queue;
  15 import java.util.Set;
  16 import java.util.TreeSet;
  17
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.eclipse.tracecompass.statesystem.core.ITmfStateSystemBuilder;
  20
  21 /**
  22  * This class allows to recycle state system attributes. Instead of creating a
  23  * lot of short-lived attributes, it is sometimes useful to re-use an attribute
  24  * (and its whole sub-tree) that was previously used and is no longer required.
  25  * This class keeps a list of children attributes of a base quark and grows that
  26  * list as needed.
  27  *
  28  * @author Geneviève Bastien
  29  * @since 2.0
  30  */
  31 public class TmfAttributePool {
  32
  33     private final ITmfStateSystemBuilder fSs;
  34     private final Integer fBaseQuark;
  35     private final Queue<@Nullable Integer> fAvailableQuarks;
  36     private final Set<Integer> fQuarksInUse = new TreeSet<>();
  37     private int fCount = 0;
  38
  39     /**
  40      * The type of queue
  41      */
  42     public enum QueueType {
  43         /**
  44          * First In First Out, available attributes are stored and returned in
  45          * the order in which they are recycled
  46          */
  47         FIFO,
  48         /**
  49          * Available attributes are returned by their number, so attributes with
  50          * lower numbers will be used more often
  51          */
  52         PRIORITY
  53     }
  54
  55     /**
  56      * Constructor
  57      *
  58      * @param ss
  59      *            The state system
  60      * @param baseQuark
  61      *            The base quark under which to add the recyclable attributes
  62      */
  63     public TmfAttributePool(ITmfStateSystemBuilder ss, Integer baseQuark) {
  64         this(ss, baseQuark, QueueType.FIFO);
  65     }
  66
  67     /**
  68      * Constructor
  69      *
  70      * @param ss
  71      *            The state system
  72      * @param baseQuark
  73      *            The base quark under which to add the recyclable attributes
  74      * @param type
  75      *            The type of queue to use for the attribute pool
  76      */
  77     public TmfAttributePool(ITmfStateSystemBuilder ss, Integer baseQuark, QueueType type) {
  78         fSs = ss;
  79         try {
  80             /* Make sure the base quark is in range */
  81             ss.getParentAttributeQuark(baseQuark);
  82             fBaseQuark = baseQuark;
  83         } catch (IndexOutOfBoundsException e) {
  84             throw new IllegalArgumentException("The quark used as base for the attribute pool does not exist"); //$NON-NLS-1$
  85         }
  86         switch (type) {
  87         case FIFO:
  88             fAvailableQuarks = new LinkedList<>();
  89             break;
  90         case PRIORITY:
  91             fAvailableQuarks = new PriorityQueue<>();
  92             break;
  93         default:
  94             throw new IllegalArgumentException("Wrong queue type"); //$NON-NLS-1$
  95         }
  96     }
  97
  98     /**
  99      * Get an available attribute quark. If there is one available, it will be
 100      * reused, otherwise a new quark will be created under the base quark. The
 101      * name of the attributes is a sequential integer. So the first quark to be
 102      * added will be named '0', the next one '1', etc.
 103      *
 104      * @return An available quark
 105      */
 106     public synchronized int getAvailable() {
 107         Integer quark = fAvailableQuarks.poll();
 108         if (quark == null) {
 109             quark = fSs.getQuarkRelativeAndAdd(fBaseQuark, String.valueOf(fCount));
 110             fCount++;
 111         }
 112         fQuarksInUse.add(quark);
 113         return quark;
 114     }
 115
 116     /**
 117      * Recycle a quark so that it can be reused by calling the
 118      * {@link #getAvailable()} method. The quark has to have been obtained from
 119      * a previous call to {@link #getAvailable()}. It will set the quark's value
 120      * in the state system to a null value.
 121      *
 122      * It is assumed that it will be reused in the same context each time, so
 123      * all children are kept and set to null in this method. The quarks are
 124      * still available for the caller, nothing prevents from re-using them
 125      * without referring to this class. That means if any attribute's value need
 126      * to be non-null after recycling the quark, the caller can do it after
 127      * calling this method.
 128      *
 129      * @param quark
 130      *            The quark to recycle.
 131      * @param ts
 132      *            The timestamp at which to close this attribute.
 133      */
 134     public synchronized void recycle(int quark, long ts) {
 135         if (!fQuarksInUse.remove(quark)) {
 136             throw new IllegalArgumentException();
 137         }
 138         fSs.removeAttribute(ts, quark);
 139         fAvailableQuarks.add(quark);
 140     }
 141
 142 }