include/llvm/ADT/SparseSet.h

   1 //===--- llvm/ADT/SparseSet.h - Sparse set ----------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file defines the SparseSet class derived from the version described in
  11 // Briggs, Torczon, "An efficient representation for sparse sets", ACM Letters
  12 // on Programming Languages and Systems, Volume 2 Issue 1-4, March-Dec.  1993.
  13 //
  14 // A sparse set holds a small number of objects identified by integer keys from
  15 // a moderately sized universe. The sparse set uses more memory than other
  16 // containers in order to provide faster operations.
  17 //
  18 //===----------------------------------------------------------------------===//
  19
  20 #ifndef LLVM_ADT_SPARSESET_H
  21 #define LLVM_ADT_SPARSESET_H
  22
  23 #include "llvm/ADT/STLExtras.h"
  24 #include "llvm/ADT/SmallVector.h"
  25 #include "llvm/Support/DataTypes.h"
  26 #include <limits>
  27
  28 namespace llvm {
  29
  30 /// SparseSetValTraits - Objects in a SparseSet are identified by keys that can
  31 /// be uniquely converted to a small integer less than the set's universe. This
  32 /// class allows the set to hold values that differ from the set's key type as
  33 /// long as an index can still be derived from the value. SparseSet never
  34 /// directly compares ValueT, only their indices, so it can map keys to
  35 /// arbitrary values. SparseSetValTraits computes the index from the value
  36 /// object. To compute the index from a key, SparseSet uses a separate
  37 /// KeyFunctorT template argument.
  38 ///
  39 /// A simple type declaration, SparseSet<Type>, handles these cases:
  40 /// - unsigned key, identity index, identity value
  41 /// - unsigned key, identity index, fat value providing getSparseSetIndex()
  42 ///
  43 /// The type declaration SparseSet<Type, UnaryFunction> handles:
  44 /// - unsigned key, remapped index, identity value (virtual registers)
  45 /// - pointer key, pointer-derived index, identity value (node+ID)
  46 /// - pointer key, pointer-derived index, fat value with getSparseSetIndex()
  47 ///
  48 /// Only other, unexpected cases require specializing SparseSetValTraits.
  49 ///
  50 /// For best results, ValueT should not require a destructor.
  51 ///
  52 template<typename ValueT>
  53 struct SparseSetValTraits {
  54   static unsigned getValIndex(const ValueT &Val) {
  55     return Val.getSparseSetIndex();
  56   }
  57 };
  58
  59 /// SparseSetValFunctor - Helper class for selecting SparseSetValTraits. The
  60 /// generic implementation handles ValueT classes which either provide
  61 /// getSparseSetIndex() or specialize SparseSetValTraits<>.
  62 ///
  63 template<typename KeyT, typename ValueT, typename KeyFunctorT>
  64 struct SparseSetValFunctor {
  65   unsigned operator()(const ValueT &Val) const {
  66     return SparseSetValTraits<ValueT>::getValIndex(Val);
  67   }
  68 };
  69
  70 /// SparseSetValFunctor<KeyT, KeyT> - Helper class for the common case of
  71 /// identity key/value sets.
  72 template<typename KeyT, typename KeyFunctorT>
  73 struct SparseSetValFunctor<KeyT, KeyT, KeyFunctorT> {
  74   unsigned operator()(const KeyT &Key) const {
  75     return KeyFunctorT()(Key);
  76   }
  77 };
  78
  79 /// SparseSet - Fast set implmentation for objects that can be identified by
  80 /// small unsigned keys.
  81 ///
  82 /// SparseSet allocates memory proportional to the size of the key universe, so
  83 /// it is not recommended for building composite data structures.  It is useful
  84 /// for algorithms that require a single set with fast operations.
  85 ///
  86 /// Compared to DenseSet and DenseMap, SparseSet provides constant-time fast
  87 /// clear() and iteration as fast as a vector.  The find(), insert(), and
  88 /// erase() operations are all constant time, and typically faster than a hash
  89 /// table.  The iteration order doesn't depend on numerical key values, it only
  90 /// depends on the order of insert() and erase() operations.  When no elements
  91 /// have been erased, the iteration order is the insertion order.
  92 ///
  93 /// Compared to BitVector, SparseSet<unsigned> uses 8x-40x more memory, but
  94 /// offers constant-time clear() and size() operations as well as fast
  95 /// iteration independent on the size of the universe.
  96 ///
  97 /// SparseSet contains a dense vector holding all the objects and a sparse
  98 /// array holding indexes into the dense vector.  Most of the memory is used by
  99 /// the sparse array which is the size of the key universe.  The SparseT
 100 /// template parameter provides a space/speed tradeoff for sets holding many
 101 /// elements.
 102 ///
 103 /// When SparseT is uint32_t, find() only touches 2 cache lines, but the sparse
 104 /// array uses 4 x Universe bytes.
 105 ///
 106 /// When SparseT is uint8_t (the default), find() touches up to 2+[N/256] cache
 107 /// lines, but the sparse array is 4x smaller.  N is the number of elements in
 108 /// the set.
 109 ///
 110 /// For sets that may grow to thousands of elements, SparseT should be set to
 111 /// uint16_t or uint32_t.
 112 ///
 113 /// @tparam ValueT      The type of objects in the set.
 114 /// @tparam KeyFunctorT A functor that computes an unsigned index from KeyT.
 115 /// @tparam SparseT     An unsigned integer type. See above.
 116 ///
 117 template<typename ValueT,
 118          typename KeyFunctorT = llvm::identity<unsigned>,
 119          typename SparseT = uint8_t>
 120 class SparseSet {
 121   static_assert(std::numeric_limits<SparseT>::is_integer &&
 122                 !std::numeric_limits<SparseT>::is_signed,
 123                 "SparseT must be an unsigned integer type");
 124
 125   typedef typename KeyFunctorT::argument_type KeyT;
 126   typedef SmallVector<ValueT, 8> DenseT;
 127   DenseT Dense;
 128   SparseT *Sparse;
 129   unsigned Universe;
 130   KeyFunctorT KeyIndexOf;
 131   SparseSetValFunctor<KeyT, ValueT, KeyFunctorT> ValIndexOf;
 132
 133   // Disable copy construction and assignment.
 134   // This data structure is not meant to be used that way.
 135   SparseSet(const SparseSet&) LLVM_DELETED_FUNCTION;
 136   SparseSet &operator=(const SparseSet&) LLVM_DELETED_FUNCTION;
 137
 138 public:
 139   typedef ValueT value_type;
 140   typedef ValueT &reference;
 141   typedef const ValueT &const_reference;
 142   typedef ValueT *pointer;
 143   typedef const ValueT *const_pointer;
 144
 145   SparseSet() : Sparse(0), Universe(0) {}
 146   ~SparseSet() { free(Sparse); }
 147
 148   /// setUniverse - Set the universe size which determines the largest key the
 149   /// set can hold.  The universe must be sized before any elements can be
 150   /// added.
 151   ///
 152   /// @param U Universe size. All object keys must be less than U.
 153   ///
 154   void setUniverse(unsigned U) {
 155     // It's not hard to resize the universe on a non-empty set, but it doesn't
 156     // seem like a likely use case, so we can add that code when we need it.
 157     assert(empty() && "Can only resize universe on an empty map");
 158     // Hysteresis prevents needless reallocations.
 159     if (U >= Universe/4 && U <= Universe)
 160       return;
 161     free(Sparse);
 162     // The Sparse array doesn't actually need to be initialized, so malloc
 163     // would be enough here, but that will cause tools like valgrind to
 164     // complain about branching on uninitialized data.
 165     Sparse = reinterpret_cast<SparseT*>(calloc(U, sizeof(SparseT)));
 166     Universe = U;
 167   }
 168
 169   // Import trivial vector stuff from DenseT.
 170   typedef typename DenseT::iterator iterator;
 171   typedef typename DenseT::const_iterator const_iterator;
 172
 173   const_iterator begin() const { return Dense.begin(); }
 174   const_iterator end() const { return Dense.end(); }
 175   iterator begin() { return Dense.begin(); }
 176   iterator end() { return Dense.end(); }
 177
 178   /// empty - Returns true if the set is empty.
 179   ///
 180   /// This is not the same as BitVector::empty().
 181   ///
 182   bool empty() const { return Dense.empty(); }
 183
 184   /// size - Returns the number of elements in the set.
 185   ///
 186   /// This is not the same as BitVector::size() which returns the size of the
 187   /// universe.
 188   ///
 189   unsigned size() const { return Dense.size(); }
 190
 191   /// clear - Clears the set.  This is a very fast constant time operation.
 192   ///
 193   void clear() {
 194     // Sparse does not need to be cleared, see find().
 195     Dense.clear();
 196   }
 197
 198   /// findIndex - Find an element by its index.
 199   ///
 200   /// @param   Idx A valid index to find.
 201   /// @returns An iterator to the element identified by key, or end().
 202   ///
 203   iterator findIndex(unsigned Idx) {
 204     assert(Idx < Universe && "Key out of range");
 205     const unsigned Stride = std::numeric_limits<SparseT>::max() + 1u;
 206     for (unsigned i = Sparse[Idx], e = size(); i < e; i += Stride) {
 207       const unsigned FoundIdx = ValIndexOf(Dense[i]);
 208       assert(FoundIdx < Universe && "Invalid key in set. Did object mutate?");
 209       if (Idx == FoundIdx)
 210         return begin() + i;
 211       // Stride is 0 when SparseT >= unsigned.  We don't need to loop.
 212       if (!Stride)
 213         break;
 214     }
 215     return end();
 216   }
 217
 218   /// find - Find an element by its key.
 219   ///
 220   /// @param   Key A valid key to find.
 221   /// @returns An iterator to the element identified by key, or end().
 222   ///
 223   iterator find(const KeyT &Key) {
 224     return findIndex(KeyIndexOf(Key));
 225   }
 226
 227   const_iterator find(const KeyT &Key) const {
 228     return const_cast<SparseSet*>(this)->findIndex(KeyIndexOf(Key));
 229   }
 230
 231   /// count - Returns 1 if this set contains an element identified by Key,
 232   /// 0 otherwise.
 233   ///
 234   unsigned count(const KeyT &Key) const {
 235     return find(Key) == end() ? 0 : 1;
 236   }
 237
 238   /// insert - Attempts to insert a new element.
 239   ///
 240   /// If Val is successfully inserted, return (I, true), where I is an iterator
 241   /// pointing to the newly inserted element.
 242   ///
 243   /// If the set already contains an element with the same key as Val, return
 244   /// (I, false), where I is an iterator pointing to the existing element.
 245   ///
 246   /// Insertion invalidates all iterators.
 247   ///
 248   std::pair<iterator, bool> insert(const ValueT &Val) {
 249     unsigned Idx = ValIndexOf(Val);
 250     iterator I = findIndex(Idx);
 251     if (I != end())
 252       return std::make_pair(I, false);
 253     Sparse[Idx] = size();
 254     Dense.push_back(Val);
 255     return std::make_pair(end() - 1, true);
 256   }
 257
 258   /// array subscript - If an element already exists with this key, return it.
 259   /// Otherwise, automatically construct a new value from Key, insert it,
 260   /// and return the newly inserted element.
 261   ValueT &operator[](const KeyT &Key) {
 262     return *insert(ValueT(Key)).first;
 263   }
 264
 265   /// erase - Erases an existing element identified by a valid iterator.
 266   ///
 267   /// This invalidates all iterators, but erase() returns an iterator pointing
 268   /// to the next element.  This makes it possible to erase selected elements
 269   /// while iterating over the set:
 270   ///
 271   ///   for (SparseSet::iterator I = Set.begin(); I != Set.end();)
 272   ///     if (test(*I))
 273   ///       I = Set.erase(I);
 274   ///     else
 275   ///       ++I;
 276   ///
 277   /// Note that end() changes when elements are erased, unlike std::list.
 278   ///
 279   iterator erase(iterator I) {
 280     assert(unsigned(I - begin()) < size() && "Invalid iterator");
 281     if (I != end() - 1) {
 282       *I = Dense.back();
 283       unsigned BackIdx = ValIndexOf(Dense.back());
 284       assert(BackIdx < Universe && "Invalid key in set. Did object mutate?");
 285       Sparse[BackIdx] = I - begin();
 286     }
 287     // This depends on SmallVector::pop_back() not invalidating iterators.
 288     // std::vector::pop_back() doesn't give that guarantee.
 289     Dense.pop_back();
 290     return I;
 291   }
 292
 293   /// erase - Erases an element identified by Key, if it exists.
 294   ///
 295   /// @param   Key The key identifying the element to erase.
 296   /// @returns True when an element was erased, false if no element was found.
 297   ///
 298   bool erase(const KeyT &Key) {
 299     iterator I = find(Key);
 300     if (I == end())
 301       return false;
 302     erase(I);
 303     return true;
 304   }
 305
 306 };
 307
 308 } // end namespace llvm
 309
 310 #endif