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