1 //===- llvm/ADT/SparseSet.h - Sparse set ------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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.
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.
18 //===----------------------------------------------------------------------===//
20 #ifndef LLVM_ADT_SPARSESET_H
21 #define LLVM_ADT_SPARSESET_H
23 #include "llvm/ADT/STLExtras.h"
24 #include "llvm/ADT/SmallVector.h"
25 #include "llvm/Support/Allocator.h"
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.
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()
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()
52 /// Only other, unexpected cases require specializing SparseSetValTraits.
54 /// For best results, ValueT should not require a destructor.
56 template<typename ValueT>
57 struct SparseSetValTraits {
58 static unsigned getValIndex(const ValueT &Val) {
59 return Val.getSparseSetIndex();
63 /// SparseSetValFunctor - Helper class for selecting SparseSetValTraits. The
64 /// generic implementation handles ValueT classes which either provide
65 /// getSparseSetIndex() or specialize SparseSetValTraits<>.
67 template<typename KeyT, typename ValueT, typename KeyFunctorT>
68 struct SparseSetValFunctor {
69 unsigned operator()(const ValueT &Val) const {
70 return SparseSetValTraits<ValueT>::getValIndex(Val);
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);
83 /// SparseSet - Fast set implmentation for objects that can be identified by
84 /// small unsigned keys.
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.
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.
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.
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
107 /// When SparseT is uint32_t, find() only touches 2 cache lines, but the sparse
108 /// array uses 4 x Universe bytes.
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
114 /// For sets that may grow to thousands of elements, SparseT should be set to
115 /// uint16_t or uint32_t.
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.
121 template<typename ValueT,
122 typename KeyFunctorT = identity<unsigned>,
123 typename SparseT = uint8_t>
125 static_assert(std::numeric_limits<SparseT>::is_integer &&
126 !std::numeric_limits<SparseT>::is_signed,
127 "SparseT must be an unsigned integer type");
129 using KeyT = typename KeyFunctorT::argument_type;
130 using DenseT = SmallVector<ValueT, 8>;
131 using size_type = unsigned;
133 SparseT *Sparse = nullptr;
134 unsigned Universe = 0;
135 KeyFunctorT KeyIndexOf;
136 SparseSetValFunctor<KeyT, ValueT, KeyFunctorT> ValIndexOf;
139 using value_type = ValueT;
140 using reference = ValueT &;
141 using const_reference = const ValueT &;
142 using pointer = ValueT *;
143 using const_pointer = const ValueT *;
145 SparseSet() = default;
146 SparseSet(const SparseSet &) = delete;
147 SparseSet &operator=(const SparseSet &) = delete;
148 ~SparseSet() { free(Sparse); }
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
154 /// @param U Universe size. All object keys must be less than U.
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)
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)));
171 // Import trivial vector stuff from DenseT.
172 using iterator = typename DenseT::iterator;
173 using const_iterator = typename DenseT::const_iterator;
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(); }
180 /// empty - Returns true if the set is empty.
182 /// This is not the same as BitVector::empty().
184 bool empty() const { return Dense.empty(); }
186 /// size - Returns the number of elements in the set.
188 /// This is not the same as BitVector::size() which returns the size of the
191 size_type size() const { return Dense.size(); }
193 /// clear - Clears the set. This is a very fast constant time operation.
196 // Sparse does not need to be cleared, see find().
200 /// findIndex - Find an element by its index.
202 /// @param Idx A valid index to find.
203 /// @returns An iterator to the element identified by key, or end().
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?");
213 // Stride is 0 when SparseT >= unsigned. We don't need to loop.
220 /// find - Find an element by its key.
222 /// @param Key A valid key to find.
223 /// @returns An iterator to the element identified by key, or end().
225 iterator find(const KeyT &Key) {
226 return findIndex(KeyIndexOf(Key));
229 const_iterator find(const KeyT &Key) const {
230 return const_cast<SparseSet*>(this)->findIndex(KeyIndexOf(Key));
233 /// count - Returns 1 if this set contains an element identified by Key,
236 size_type count(const KeyT &Key) const {
237 return find(Key) == end() ? 0 : 1;
240 /// insert - Attempts to insert a new element.
242 /// If Val is successfully inserted, return (I, true), where I is an iterator
243 /// pointing to the newly inserted element.
245 /// If the set already contains an element with the same key as Val, return
246 /// (I, false), where I is an iterator pointing to the existing element.
248 /// Insertion invalidates all iterators.
250 std::pair<iterator, bool> insert(const ValueT &Val) {
251 unsigned Idx = ValIndexOf(Val);
252 iterator I = findIndex(Idx);
254 return std::make_pair(I, false);
255 Sparse[Idx] = size();
256 Dense.push_back(Val);
257 return std::make_pair(end() - 1, true);
260 /// array subscript - If an element already exists with this key, return it.
261 /// Otherwise, automatically construct a new value from Key, insert it,
262 /// and return the newly inserted element.
263 ValueT &operator[](const KeyT &Key) {
264 return *insert(ValueT(Key)).first;
267 ValueT pop_back_val() {
268 // Sparse does not need to be cleared, see find().
269 return Dense.pop_back_val();
272 /// erase - Erases an existing element identified by a valid iterator.
274 /// This invalidates all iterators, but erase() returns an iterator pointing
275 /// to the next element. This makes it possible to erase selected elements
276 /// while iterating over the set:
278 /// for (SparseSet::iterator I = Set.begin(); I != Set.end();)
280 /// I = Set.erase(I);
284 /// Note that end() changes when elements are erased, unlike std::list.
286 iterator erase(iterator I) {
287 assert(unsigned(I - begin()) < size() && "Invalid iterator");
288 if (I != end() - 1) {
290 unsigned BackIdx = ValIndexOf(Dense.back());
291 assert(BackIdx < Universe && "Invalid key in set. Did object mutate?");
292 Sparse[BackIdx] = I - begin();
294 // This depends on SmallVector::pop_back() not invalidating iterators.
295 // std::vector::pop_back() doesn't give that guarantee.
300 /// erase - Erases an element identified by Key, if it exists.
302 /// @param Key The key identifying the element to erase.
303 /// @returns True when an element was erased, false if no element was found.
305 bool erase(const KeyT &Key) {
306 iterator I = find(Key);
314 } // end namespace llvm
316 #endif // LLVM_ADT_SPARSESET_H