include/llvm/ADT/SparseSet.h

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