LLVM  6.0.0svn
SparseSet.h
Go to the documentation of this file.
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 <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>
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>
68  unsigned operator()(const ValueT &Val) const {
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;
130  using size_type = unsigned;
131  DenseT Dense;
132  SparseT *Sparse = nullptr;
133  unsigned Universe = 0;
134  KeyFunctorT KeyIndexOf;
136 
137 public:
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 = reinterpret_cast<SparseT*>(calloc(U, sizeof(SparseT)));
167  Universe = U;
168  }
169 
170  // Import trivial vector stuff from DenseT.
171  using iterator = typename DenseT::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 
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  ///
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
ValueT & operator[](const KeyT &Key)
array subscript - If an element already exists with this key, return it.
Definition: SparseSet.h:262
void push_back(const T &Elt)
Definition: SmallVector.h:212
const_iterator end(StringRef path)
Get end iterator over path.
Definition: Path.cpp:243
GCNRegPressure max(const GCNRegPressure &P1, const GCNRegPressure &P2)
const_iterator begin(StringRef path, Style style=Style::native)
Get begin iterator over path.
Definition: Path.cpp:234
typename SuperClass::const_iterator const_iterator
Definition: SmallVector.h:329
iterator end()
Definition: SparseSet.h:177
Compute iterated dominance frontiers using a linear time algorithm.
Definition: AllocatorList.h:24
LLVM_ATTRIBUTE_ALWAYS_INLINE size_type size() const
Definition: SmallVector.h:136
std::pair< iterator, bool > insert(const ValueT &Val)
insert - Attempts to insert a new element.
Definition: SparseSet.h:249
bool erase(const KeyT &Key)
erase - Erases an element identified by Key, if it exists.
Definition: SparseSet.h:304
SparseSetValTraits - Objects in a SparseSet are identified by keys that can be uniquely converted to ...
Definition: SparseSet.h:56
size_type count(const KeyT &Key) const
count - Returns 1 if this set contains an element identified by Key, 0 otherwise. ...
Definition: SparseSet.h:235
size_type size() const
size - Returns the number of elements in the set.
Definition: SparseSet.h:190
iterator findIndex(unsigned Idx)
findIndex - Find an element by its index.
Definition: SparseSet.h:204
iterator erase(iterator I)
erase - Erases an existing element identified by a valid iterator.
Definition: SparseSet.h:285
bool empty() const
empty - Returns true if the set is empty.
Definition: SparseSet.h:183
typename DenseT::const_iterator const_iterator
Definition: SparseSet.h:172
LLVM_ATTRIBUTE_ALWAYS_INLINE iterator begin()
Definition: SmallVector.h:116
unsigned operator()(const ValueT &Val) const
Definition: SparseSet.h:68
void setUniverse(unsigned U)
setUniverse - Set the universe size which determines the largest key the set can hold.
Definition: SparseSet.h:155
const_iterator end() const
Definition: SparseSet.h:175
auto find(R &&Range, const T &Val) -> decltype(std::begin(Range))
Provide wrappers to std::find which take ranges instead of having to pass begin/end explicitly...
Definition: STLExtras.h:839
iterator begin()
Definition: SparseSet.h:176
const_iterator begin() const
Definition: SparseSet.h:174
LLVM_NODISCARD T pop_back_val()
Definition: SmallVector.h:385
typename SuperClass::iterator iterator
Definition: SmallVector.h:328
SparseSetValFunctor - Helper class for selecting SparseSetValTraits.
Definition: SparseSet.h:67
LLVM_ATTRIBUTE_ALWAYS_INLINE iterator end()
Definition: SmallVector.h:120
SparseSet - Fast set implmentation for objects that can be identified by small unsigned keys...
Definition: SparseSet.h:123
LLVM_NODISCARD bool empty() const
Definition: SmallVector.h:61
iterator find(const KeyT &Key)
find - Find an element by its key.
Definition: SparseSet.h:224
#define I(x, y, z)
Definition: MD5.cpp:58
const_iterator find(const KeyT &Key) const
Definition: SparseSet.h:228
void clear()
clear - Clears the set.
Definition: SparseSet.h:194
unsigned operator()(const KeyT &Key) const
Definition: SparseSet.h:77
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
ValueT pop_back_val()
Definition: SparseSet.h:266
static unsigned getValIndex(const ValueT &Val)
Definition: SparseSet.h:57