Prune CRLF.
[oota-llvm.git] / 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   typedef unsigned size_type;
128   DenseT Dense;
129   SparseT *Sparse;
130   unsigned Universe;
131   KeyFunctorT KeyIndexOf;
132   SparseSetValFunctor<KeyT, ValueT, KeyFunctorT> ValIndexOf;
133
134   // Disable copy construction and assignment.
135   // This data structure is not meant to be used that way.
136   SparseSet(const SparseSet&) LLVM_DELETED_FUNCTION;
137   SparseSet &operator=(const SparseSet&) LLVM_DELETED_FUNCTION;
138
139 public:
140   typedef ValueT value_type;
141   typedef ValueT &reference;
142   typedef const ValueT &const_reference;
143   typedef ValueT *pointer;
144   typedef const ValueT *const_pointer;
145
146   SparseSet() : Sparse(nullptr), Universe(0) {}
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   typedef typename DenseT::iterator iterator;
172   typedef typename DenseT::const_iterator 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   /// erase - Erases an existing element identified by a valid iterator.
267   ///
268   /// This invalidates all iterators, but erase() returns an iterator pointing
269   /// to the next element.  This makes it possible to erase selected elements
270   /// while iterating over the set:
271   ///
272   ///   for (SparseSet::iterator I = Set.begin(); I != Set.end();)
273   ///     if (test(*I))
274   ///       I = Set.erase(I);
275   ///     else
276   ///       ++I;
277   ///
278   /// Note that end() changes when elements are erased, unlike std::list.
279   ///
280   iterator erase(iterator I) {
281     assert(unsigned(I - begin()) < size() && "Invalid iterator");
282     if (I != end() - 1) {
283       *I = Dense.back();
284       unsigned BackIdx = ValIndexOf(Dense.back());
285       assert(BackIdx < Universe && "Invalid key in set. Did object mutate?");
286       Sparse[BackIdx] = I - begin();
287     }
288     // This depends on SmallVector::pop_back() not invalidating iterators.
289     // std::vector::pop_back() doesn't give that guarantee.
290     Dense.pop_back();
291     return I;
292   }
293
294   /// erase - Erases an element identified by Key, if it exists.
295   ///
296   /// @param   Key The key identifying the element to erase.
297   /// @returns True when an element was erased, false if no element was found.
298   ///
299   bool erase(const KeyT &Key) {
300     iterator I = find(Key);
301     if (I == end())
302       return false;
303     erase(I);
304     return true;
305   }
306
307 };
308
309 } // end namespace llvm
310
311 #endif