Line data Source code
1 : //===- llvm/ADT/SparseMultiSet.h - Sparse multiset --------------*- 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 SparseMultiSet class, which adds multiset behavior to
11 : // the SparseSet.
12 : //
13 : // A sparse multiset holds a small number of objects identified by integer keys
14 : // from a moderately sized universe. The sparse multiset uses more memory than
15 : // other containers in order to provide faster operations. Any key can map to
16 : // multiple values. A SparseMultiSetNode class is provided, which serves as a
17 : // convenient base class for the contents of a SparseMultiSet.
18 : //
19 : //===----------------------------------------------------------------------===//
20 :
21 : #ifndef LLVM_ADT_SPARSEMULTISET_H
22 : #define LLVM_ADT_SPARSEMULTISET_H
23 :
24 : #include "llvm/ADT/STLExtras.h"
25 : #include "llvm/ADT/SmallVector.h"
26 : #include "llvm/ADT/SparseSet.h"
27 : #include <cassert>
28 : #include <cstdint>
29 : #include <cstdlib>
30 : #include <iterator>
31 : #include <limits>
32 : #include <utility>
33 :
34 : namespace llvm {
35 :
36 : /// Fast multiset implementation for objects that can be identified by small
37 : /// unsigned keys.
38 : ///
39 : /// SparseMultiSet allocates memory proportional to the size of the key
40 : /// universe, so it is not recommended for building composite data structures.
41 : /// It is useful for algorithms that require a single set with fast operations.
42 : ///
43 : /// Compared to DenseSet and DenseMap, SparseMultiSet provides constant-time
44 : /// fast clear() as fast as a vector. The find(), insert(), and erase()
45 : /// operations are all constant time, and typically faster than a hash table.
46 : /// The iteration order doesn't depend on numerical key values, it only depends
47 : /// on the order of insert() and erase() operations. Iteration order is the
48 : /// insertion order. Iteration is only provided over elements of equivalent
49 : /// keys, but iterators are bidirectional.
50 : ///
51 : /// Compared to BitVector, SparseMultiSet<unsigned> uses 8x-40x more memory, but
52 : /// offers constant-time clear() and size() operations as well as fast iteration
53 : /// independent on the size of the universe.
54 : ///
55 : /// SparseMultiSet contains a dense vector holding all the objects and a sparse
56 : /// array holding indexes into the dense vector. Most of the memory is used by
57 : /// the sparse array which is the size of the key universe. The SparseT template
58 : /// parameter provides a space/speed tradeoff for sets holding many elements.
59 : ///
60 : /// When SparseT is uint32_t, find() only touches up to 3 cache lines, but the
61 : /// sparse array uses 4 x Universe bytes.
62 : ///
63 : /// When SparseT is uint8_t (the default), find() touches up to 3+[N/256] cache
64 : /// lines, but the sparse array is 4x smaller. N is the number of elements in
65 : /// the set.
66 : ///
67 : /// For sets that may grow to thousands of elements, SparseT should be set to
68 : /// uint16_t or uint32_t.
69 : ///
70 : /// Multiset behavior is provided by providing doubly linked lists for values
71 : /// that are inlined in the dense vector. SparseMultiSet is a good choice when
72 : /// one desires a growable number of entries per key, as it will retain the
73 : /// SparseSet algorithmic properties despite being growable. Thus, it is often a
74 : /// better choice than a SparseSet of growable containers or a vector of
75 : /// vectors. SparseMultiSet also keeps iterators valid after erasure (provided
76 : /// the iterators don't point to the element erased), allowing for more
77 : /// intuitive and fast removal.
78 : ///
79 : /// @tparam ValueT The type of objects in the set.
80 : /// @tparam KeyFunctorT A functor that computes an unsigned index from KeyT.
81 : /// @tparam SparseT An unsigned integer type. See above.
82 : ///
83 : template<typename ValueT,
84 : typename KeyFunctorT = identity<unsigned>,
85 : typename SparseT = uint8_t>
86 : class SparseMultiSet {
87 : static_assert(std::numeric_limits<SparseT>::is_integer &&
88 : !std::numeric_limits<SparseT>::is_signed,
89 : "SparseT must be an unsigned integer type");
90 :
91 : /// The actual data that's stored, as a doubly-linked list implemented via
92 : /// indices into the DenseVector. The doubly linked list is implemented
93 : /// circular in Prev indices, and INVALID-terminated in Next indices. This
94 : /// provides efficient access to list tails. These nodes can also be
95 : /// tombstones, in which case they are actually nodes in a single-linked
96 : /// freelist of recyclable slots.
97 : struct SMSNode {
98 : static const unsigned INVALID = ~0U;
99 :
100 : ValueT Data;
101 : unsigned Prev;
102 : unsigned Next;
103 :
104 8175385 : SMSNode(ValueT D, unsigned P, unsigned N) : Data(D), Prev(P), Next(N) {}
105 :
106 : /// List tails have invalid Nexts.
107 0 : bool isTail() const {
108 0 : return Next == INVALID;
109 : }
110 0 :
111 0 : /// Whether this node is a tombstone node, and thus is in our freelist.
112 : bool isTombstone() const {
113 0 : return Prev == INVALID;
114 0 : }
115 :
116 0 : /// Since the list is circular in Prev, all non-tombstone nodes have a valid
117 0 : /// Prev.
118 0 : bool isValid() const { return Prev != INVALID; }
119 : };
120 :
121 : using KeyT = typename KeyFunctorT::argument_type;
122 : using DenseT = SmallVector<SMSNode, 8>;
123 : DenseT Dense;
124 0 : SparseT *Sparse = nullptr;
125 : unsigned Universe = 0;
126 : KeyFunctorT KeyIndexOf;
127 0 : SparseSetValFunctor<KeyT, ValueT, KeyFunctorT> ValIndexOf;
128 :
129 : /// We have a built-in recycler for reusing tombstone slots. This recycler
130 : /// puts a singly-linked free list into tombstone slots, allowing us quick
131 : /// erasure, iterator preservation, and dense size.
132 : unsigned FreelistIdx = SMSNode::INVALID;
133 : unsigned NumFree = 0;
134 :
135 0 : unsigned sparseIndex(const ValueT &Val) const {
136 : assert(ValIndexOf(Val) < Universe &&
137 : "Invalid key in set. Did object mutate?");
138 0 : return ValIndexOf(Val);
139 : }
140 0 : unsigned sparseIndex(const SMSNode &N) const { return sparseIndex(N.Data); }
141 0 :
142 : /// Whether the given entry is the head of the list. List heads's previous
143 : /// pointers are to the tail of the list, allowing for efficient access to the
144 0 : /// list tail. D must be a valid entry node.
145 0 : bool isHead(const SMSNode &D) const {
146 0 : assert(D.isValid() && "Invalid node for head");
147 2693687 : return Dense[D.Prev].isTail();
148 : }
149 0 :
150 : /// Whether the given entry is a singleton entry, i.e. the only entry with
151 0 : /// that key.
152 0 : bool isSingleton(const SMSNode &N) const {
153 : assert(N.isValid() && "Invalid node for singleton");
154 0 : // Is N its own predecessor?
155 : return &Dense[N.Prev] == &N;
156 2770 : }
157 0 :
158 : /// Add in the given SMSNode. Uses a free entry in our freelist if
159 0 : /// available. Returns the index of the added node.
160 1581057 : unsigned addValue(const ValueT& V, unsigned Prev, unsigned Next) {
161 1581057 : if (NumFree == 0) {
162 1581057 : Dense.push_back(SMSNode(V, Prev, Next));
163 1581806 : return Dense.size() - 1;
164 0 : }
165 0 :
166 : // Peel off a free slot
167 0 : unsigned Idx = FreelistIdx;
168 0 : unsigned NextFree = Dense[Idx].Next;
169 0 : assert(Dense[Idx].isTombstone() && "Non-tombstone free?");
170 :
171 15625516 : Dense[Idx] = SMSNode(V, Prev, Next);
172 0 : FreelistIdx = NextFree;
173 0 : --NumFree;
174 0 : return Idx;
175 0 : }
176 :
177 0 : /// Make the current index a new tombstone. Pushes it onto the freelist.
178 : void makeTombstone(unsigned Idx) {
179 15 : Dense[Idx].Prev = SMSNode::INVALID;
180 : Dense[Idx].Next = FreelistIdx;
181 0 : FreelistIdx = Idx;
182 : ++NumFree;
183 0 : }
184 3 :
185 3 : public:
186 3 : using value_type = ValueT;
187 3 : using reference = ValueT &;
188 : using const_reference = const ValueT &;
189 : using pointer = ValueT *;
190 : using const_pointer = const ValueT *;
191 3781981 : using size_type = unsigned;
192 0 :
193 167111 : SparseMultiSet() = default;
194 : SparseMultiSet(const SparseMultiSet &) = delete;
195 0 : SparseMultiSet &operator=(const SparseMultiSet &) = delete;
196 10336356 : ~SparseMultiSet() { free(Sparse); }
197 9231909 :
198 6594325 : /// Set the universe size which determines the largest key the set can hold.
199 6594325 : /// The universe must be sized before any elements can be added.
200 3 : ///
201 3 : /// @param U Universe size. All object keys must be less than U.
202 3 : ///
203 2637587 : void setUniverse(unsigned U) {
204 2637584 : // It's not hard to resize the universe on a non-empty set, but it doesn't
205 : // seem like a likely use case, so we can add that code when we need it.
206 : assert(empty() && "Can only resize universe on an empty map");
207 2637584 : // Hysteresis prevents needless reallocations.
208 2637584 : if (U >= Universe/4 && U <= Universe)
209 2637584 : return;
210 2637584 : free(Sparse);
211 0 : // The Sparse array doesn't actually need to be initialized, so malloc
212 2392078 : // would be enough here, but that will cause tools like valgrind to
213 2392078 : // complain about branching on uninitialized data.
214 1441228 : Sparse = static_cast<SparseT*>(safe_calloc(U, sizeof(SparseT)));
215 1441228 : Universe = U;
216 0 : }
217 0 :
218 0 : /// Our iterators are iterators over the collection of objects that share a
219 950850 : /// key.
220 950850 : template<typename SMSPtrTy>
221 : class iterator_base : public std::iterator<std::bidirectional_iterator_tag,
222 : ValueT> {
223 950850 : friend class SparseMultiSet;
224 950850 :
225 950850 : SMSPtrTy SMS;
226 950850 : unsigned Idx;
227 0 : unsigned SparseIdx;
228 685276 :
229 685276 : iterator_base(SMSPtrTy P, unsigned I, unsigned SI)
230 685276 : : SMS(P), Idx(I), SparseIdx(SI) {}
231 685276 :
232 : /// Whether our iterator has fallen outside our dense vector.
233 : bool isEnd() const {
234 : if (Idx == SMSNode::INVALID)
235 0 : return true;
236 0 :
237 0 : assert(Idx < SMS->Dense.size() && "Out of range, non-INVALID Idx?");
238 0 : return false;
239 0 : }
240 0 :
241 0 : /// Whether our iterator is properly keyed, i.e. the SparseIdx is valid
242 0 : bool isKeyed() const { return SparseIdx < SMS->Universe; }
243 :
244 6924623 : unsigned Prev() const { return SMS->Dense[Idx].Prev; }
245 23336563 : unsigned Next() const { return SMS->Dense[Idx].Next; }
246 4467821 :
247 4467821 : void setPrev(unsigned P) { SMS->Dense[Idx].Prev = P; }
248 : void setNext(unsigned N) { SMS->Dense[Idx].Next = N; }
249 6 :
250 : public:
251 1686734 : using super = std::iterator<std::bidirectional_iterator_tag, ValueT>;
252 1686740 : using value_type = typename super::value_type;
253 : using difference_type = typename super::difference_type;
254 : using pointer = typename super::pointer;
255 1686734 : using reference = typename super::reference;
256 1686734 :
257 1686734 : reference operator*() const {
258 1686734 : assert(isKeyed() && SMS->sparseIndex(SMS->Dense[Idx].Data) == SparseIdx &&
259 0 : "Dereferencing iterator of invalid key or index");
260 :
261 17204381 : return SMS->Dense[Idx].Data;
262 : }
263 0 : pointer operator->() const { return &operator*(); }
264 0 :
265 0 : /// Comparison operators
266 0 : bool operator==(const iterator_base &RHS) const {
267 : // end compares equal
268 23185202 : if (SMS == RHS.SMS && Idx == RHS.Idx) {
269 : assert((isEnd() || SparseIdx == RHS.SparseIdx) &&
270 0 : "Same dense entry, but different keys?");
271 0 : return true;
272 : }
273 0 :
274 : return false;
275 : }
276 :
277 937336 : bool operator!=(const iterator_base &RHS) const {
278 0 : return !operator==(RHS);
279 0 : }
280 0 :
281 : /// Increment and decrement operators
282 : iterator_base &operator--() { // predecrement - Back up
283 : assert(isKeyed() && "Decrementing an invalid iterator");
284 0 : assert((isEnd() || !SMS->isHead(SMS->Dense[Idx])) &&
285 0 : "Decrementing head of list");
286 :
287 0 : // If we're at the end, then issue a new find()
288 : if (isEnd())
289 : Idx = SMS->findIndex(SparseIdx).Prev();
290 : else
291 : Idx = Prev();
292 0 :
293 0 : return *this;
294 0 : }
295 : iterator_base &operator++() { // preincrement - Advance
296 : assert(!isEnd() && isKeyed() && "Incrementing an invalid/end iterator");
297 : Idx = Next();
298 0 : return *this;
299 0 : }
300 : iterator_base operator--(int) { // postdecrement
301 0 : iterator_base I(*this);
302 : --*this;
303 : return I;
304 : }
305 : iterator_base operator++(int) { // postincrement
306 0 : iterator_base I(*this);
307 0 : ++*this;
308 0 : return I;
309 : }
310 : };
311 :
312 0 : using iterator = iterator_base<SparseMultiSet *>;
313 0 : using const_iterator = iterator_base<const SparseMultiSet *>;
314 :
315 0 : // Convenience types
316 : using RangePair = std::pair<iterator, iterator>;
317 0 :
318 0 : /// Returns an iterator past this container. Note that such an iterator cannot
319 0 : /// be decremented, but will compare equal to other end iterators.
320 0 : iterator end() { return iterator(this, SMSNode::INVALID, SMSNode::INVALID); }
321 0 : const_iterator end() const {
322 0 : return const_iterator(this, SMSNode::INVALID, SMSNode::INVALID);
323 : }
324 :
325 : /// Returns true if the set is empty.
326 0 : ///
327 0 : /// This is not the same as BitVector::empty().
328 16 : ///
329 29 : bool empty() const { return size() == 0; }
330 :
331 4 : /// Returns the number of elements in the set.
332 : ///
333 : /// This is not the same as BitVector::size() which returns the size of the
334 0 : /// universe.
335 0 : ///
336 0 : size_type size() const {
337 : assert(NumFree <= Dense.size() && "Out-of-bounds free entries");
338 : return Dense.size() - NumFree;
339 : }
340 0 :
341 0 : /// Clears the set. This is a very fast constant time operation.
342 : ///
343 : void clear() {
344 : // Sparse does not need to be cleared, see find().
345 7 : Dense.clear();
346 124424 : NumFree = 0;
347 124424 : FreelistIdx = SMSNode::INVALID;
348 : }
349 :
350 : /// Find an element by its index.
351 0 : ///
352 : /// @param Idx A valid index to find.
353 0 : /// @returns An iterator to the element identified by key, or end().
354 : ///
355 4399764 : iterator findIndex(unsigned Idx) {
356 : assert(Idx < Universe && "Key out of range");
357 0 : const unsigned Stride = std::numeric_limits<SparseT>::max() + 1u;
358 6216201 : for (unsigned i = Sparse[Idx], e = Dense.size(); i < e; i += Stride) {
359 4510124 : const unsigned FoundIdx = sparseIndex(Dense[i]);
360 0 : // Check that we're pointing at the correct entry and that it is the head
361 0 : // of a valid list.
362 4510124 : if (Idx == FoundIdx && Dense[i].isValid() && isHead(Dense[i]))
363 2693687 : return iterator(this, i, Idx);
364 2204 : // Stride is 0 when SparseT >= unsigned. We don't need to loop.
365 : if (!Stride)
366 : break;
367 0 : }
368 : return end();
369 : }
370 2218736 :
371 6413390 : /// Find an element by its key.
372 0 : ///
373 7182 : /// @param Key A valid key to find.
374 0 : /// @returns An iterator to the element identified by key, or end().
375 : ///
376 0 : iterator find(const KeyT &Key) {
377 2818707 : return findIndex(KeyIndexOf(Key));
378 : }
379 :
380 : const_iterator find(const KeyT &Key) const {
381 : iterator I = const_cast<SparseMultiSet*>(this)->findIndex(KeyIndexOf(Key));
382 0 : return const_iterator(I.SMS, I.Idx, KeyIndexOf(Key));
383 0 : }
384 0 :
385 : /// Returns the number of elements identified by Key. This will be linear in
386 : /// the number of elements of that key.
387 8493789 : size_type count(const KeyT &Key) const {
388 : unsigned Ret = 0;
389 0 : for (const_iterator It = find(Key); It != end(); ++It)
390 : ++Ret;
391 :
392 0 : return Ret;
393 0 : }
394 0 :
395 0 : /// Returns true if this set contains an element identified by Key.
396 : bool contains(const KeyT &Key) const {
397 0 : return find(Key) != end();
398 : }
399 0 :
400 : /// Return the head and tail of the subset's list, otherwise returns end().
401 0 : iterator getHead(const KeyT &Key) { return find(Key); }
402 0 : iterator getTail(const KeyT &Key) {
403 : iterator I = find(Key);
404 0 : if (I != end())
405 0 : I = iterator(this, I.Prev(), KeyIndexOf(Key));
406 : return I;
407 1158 : }
408 :
409 : /// The bounds of the range of items sharing Key K. First member is the head
410 0 : /// of the list, and the second member is a decrementable end iterator for
411 : /// that key.
412 73018561 : RangePair equal_range(const KeyT &K) {
413 : iterator B = find(K);
414 14 : iterator E = iterator(this, SMSNode::INVALID, B.SparseIdx);
415 0 : return make_pair(B, E);
416 : }
417 :
418 20 : /// Insert a new element at the tail of the subset list. Returns an iterator
419 : /// to the newly added entry.
420 1581057 : iterator insert(const ValueT &Val) {
421 : unsigned Idx = sparseIndex(Val);
422 1581057 : iterator I = findIndex(Idx);
423 :
424 1581077 : unsigned NodeIdx = addValue(Val, SMSNode::INVALID, SMSNode::INVALID);
425 7 :
426 : if (I == end()) {
427 26 : // Make a singleton list
428 810989 : Sparse[Idx] = NodeIdx;
429 811009 : Dense[NodeIdx].Prev = NodeIdx;
430 810989 : return iterator(this, NodeIdx, Idx);
431 : }
432 0 :
433 9 : // Stick it at the end.
434 : unsigned HeadIdx = I.Idx;
435 0 : unsigned TailIdx = I.Prev();
436 1540136 : Dense[TailIdx].Next = NodeIdx;
437 770068 : Dense[HeadIdx].Prev = NodeIdx;
438 770069 : Dense[NodeIdx].Prev = TailIdx;
439 0 :
440 770068 : return iterator(this, NodeIdx, Idx);
441 : }
442 0 :
443 : /// Erases an existing element identified by a valid iterator.
444 : ///
445 0 : /// This invalidates iterators pointing at the same entry, but erase() returns
446 : /// an iterator pointing to the next element in the subset's list. This makes
447 : /// it possible to erase selected elements while iterating over the subset:
448 : ///
449 : /// tie(I, E) = Set.equal_range(Key);
450 0 : /// while (I != E)
451 : /// if (test(*I))
452 0 : /// I = Set.erase(I);
453 : /// else
454 : /// ++I;
455 0 : ///
456 : /// Note that if the last element in the subset list is erased, this will
457 : /// return an end iterator which can be decremented to get the new tail (if it
458 : /// exists):
459 : ///
460 : /// tie(B, I) = Set.equal_range(Key);
461 : /// for (bool isBegin = B == I; !isBegin; /* empty */) {
462 0 : /// isBegin = (--I) == B;
463 : /// if (test(I))
464 : /// break;
465 2 : /// I = erase(I);
466 1158 : /// }
467 : iterator erase(iterator I) {
468 : assert(I.isKeyed() && !I.isEnd() && !Dense[I.Idx].isTombstone() &&
469 : "erasing invalid/end/tombstone iterator");
470 :
471 : // First, unlink the node from its list. Then swap the node out with the
472 1158 : // dense vector's last entry
473 1158 : iterator NextI = unlink(Dense[I.Idx]);
474 13 :
475 0 : // Put in a tombstone.
476 : makeTombstone(I.Idx);
477 1158 :
478 : return NextI;
479 : }
480 :
481 : /// Erase all elements with the given key. This invalidates all
482 1 : /// iterators of that key.
483 1 : void eraseAll(const KeyT &K) {
484 : for (iterator I = find(K); I != end(); /* empty */)
485 : I = erase(I);
486 : }
487 :
488 : private:
489 : /// Unlink the node from its list. Returns the next node in the list.
490 : iterator unlink(const SMSNode &N) {
491 1494 : if (isSingleton(N)) {
492 : // Singleton is already unlinked
493 : assert(N.Next == SMSNode::INVALID && "Singleton has next?");
494 3514 : return iterator(this, SMSNode::INVALID, ValIndexOf(N.Data));
495 2769 : }
496 :
497 : if (isHead(N)) {
498 2769 : // If we're the head, then update the sparse array and our next.
499 749 : Sparse[sparseIndex(N)] = N.Next;
500 : Dense[N.Next].Prev = N.Prev;
501 : return iterator(this, N.Next, ValIndexOf(N.Data));
502 : }
503 :
504 : if (N.isTail()) {
505 : // If we're the tail, then update our head and our previous.
506 8 : findIndex(sparseIndex(N)).setPrev(N.Prev);
507 : Dense[N.Prev].Next = N.Next;
508 :
509 10 : // Give back an end iterator that can be decremented
510 7 : iterator I(this, N.Prev, ValIndexOf(N.Data));
511 : return ++I;
512 : }
513 7 :
514 5 : // Otherwise, just drop us
515 : Dense[N.Next].Prev = N.Prev;
516 : Dense[N.Prev].Next = N.Next;
517 : return iterator(this, N.Next, ValIndexOf(N.Data));
518 : }
519 : };
520 :
521 1486 : } // end namespace llvm
522 :
523 : #endif // LLVM_ADT_SPARSEMULTISET_H
|
