EIC code displayed by LXR master/​include/​llvm/​ADT/​SparseMultiSet.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-05-10 08:43:09

 //===- llvm/ADT/SparseMultiSet.h - Sparse multiset --------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 ///
 /// \file
 /// This file defines the SparseMultiSet class, which adds multiset behavior to
 /// the SparseSet.
 ///
 /// A sparse multiset holds a small number of objects identified by integer keys
 /// from a moderately sized universe. The sparse multiset uses more memory than
 /// other containers in order to provide faster operations. Any key can map to
 /// multiple values. A SparseMultiSetNode class is provided, which serves as a
 /// convenient base class for the contents of a SparseMultiSet.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_ADT_SPARSEMULTISET_H
 #define LLVM_ADT_SPARSEMULTISET_H
 
 #include "llvm/ADT/identity.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/SparseSet.h"
 #include <cassert>
 #include <cstdint>
 #include <cstdlib>
 #include <iterator>
 #include <limits>
 #include <utility>
 
 namespace llvm {
 
 /// Fast multiset implementation for objects that can be identified by small
 /// unsigned keys.
 ///
 /// SparseMultiSet allocates memory proportional to the size of the key
 /// universe, so it is not recommended for building composite data structures.
 /// It is useful for algorithms that require a single set with fast operations.
 ///
 /// Compared to DenseSet and DenseMap, SparseMultiSet provides constant-time
 /// fast clear() as fast as a vector.  The find(), insert(), and erase()
 /// operations are all constant time, and typically faster than a hash table.
 /// The iteration order doesn't depend on numerical key values, it only depends
 /// on the order of insert() and erase() operations.  Iteration order is the
 /// insertion order. Iteration is only provided over elements of equivalent
 /// keys, but iterators are bidirectional.
 ///
 /// Compared to BitVector, SparseMultiSet<unsigned> uses 8x-40x more memory, but
 /// offers constant-time clear() and size() operations as well as fast iteration
 /// independent on the size of the universe.
 ///
 /// SparseMultiSet contains a dense vector holding all the objects and a sparse
 /// array holding indexes into the dense vector.  Most of the memory is used by
 /// the sparse array which is the size of the key universe. The SparseT template
 /// parameter provides a space/speed tradeoff for sets holding many elements.
 ///
 /// When SparseT is uint32_t, find() only touches up to 3 cache lines, but the
 /// sparse array uses 4 x Universe bytes.
 ///
 /// When SparseT is uint8_t (the default), find() touches up to 3+[N/256] cache
 /// lines, but the sparse array is 4x smaller.  N is the number of elements in
 /// the set.
 ///
 /// For sets that may grow to thousands of elements, SparseT should be set to
 /// uint16_t or uint32_t.
 ///
 /// Multiset behavior is provided by providing doubly linked lists for values
 /// that are inlined in the dense vector. SparseMultiSet is a good choice when
 /// one desires a growable number of entries per key, as it will retain the
 /// SparseSet algorithmic properties despite being growable. Thus, it is often a
 /// better choice than a SparseSet of growable containers or a vector of
 /// vectors. SparseMultiSet also keeps iterators valid after erasure (provided
 /// the iterators don't point to the element erased), allowing for more
 /// intuitive and fast removal.
 ///
 /// @tparam ValueT      The type of objects in the set.
 /// @tparam KeyFunctorT A functor that computes an unsigned index from KeyT.
 /// @tparam SparseT     An unsigned integer type. See above.
 ///
 template<typename ValueT,
          typename KeyFunctorT = identity<unsigned>,
          typename SparseT = uint8_t>
 class SparseMultiSet {
   static_assert(std::is_unsigned_v<SparseT>,
                 "SparseT must be an unsigned integer type");
 
   /// The actual data that's stored, as a doubly-linked list implemented via
   /// indices into the DenseVector.  The doubly linked list is implemented
   /// circular in Prev indices, and INVALID-terminated in Next indices. This
   /// provides efficient access to list tails. These nodes can also be
   /// tombstones, in which case they are actually nodes in a single-linked
   /// freelist of recyclable slots.
   struct SMSNode {
     static constexpr unsigned INVALID = ~0U;
 
     ValueT Data;
     unsigned Prev;
     unsigned Next;
 
     SMSNode(ValueT D, unsigned P, unsigned N) : Data(D), Prev(P), Next(N) {}
 
     /// List tails have invalid Nexts.
     bool isTail() const {
       return Next == INVALID;
     }
 
     /// Whether this node is a tombstone node, and thus is in our freelist.
     bool isTombstone() const {
       return Prev == INVALID;
     }
 
     /// Since the list is circular in Prev, all non-tombstone nodes have a valid
     /// Prev.
     bool isValid() const { return Prev != INVALID; }
   };
 
   using KeyT = typename KeyFunctorT::argument_type;
   using DenseT = SmallVector<SMSNode, 8>;
   DenseT Dense;
   SparseT *Sparse = nullptr;
   unsigned Universe = 0;
   KeyFunctorT KeyIndexOf;
   SparseSetValFunctor<KeyT, ValueT, KeyFunctorT> ValIndexOf;
 
   /// We have a built-in recycler for reusing tombstone slots. This recycler
   /// puts a singly-linked free list into tombstone slots, allowing us quick
   /// erasure, iterator preservation, and dense size.
   unsigned FreelistIdx = SMSNode::INVALID;
   unsigned NumFree = 0;
 
   unsigned sparseIndex(const ValueT &Val) const {
     assert(ValIndexOf(Val) < Universe &&
            "Invalid key in set. Did object mutate?");
     return ValIndexOf(Val);
   }
   unsigned sparseIndex(const SMSNode &N) const { return sparseIndex(N.Data); }
 
   /// Whether the given entry is the head of the list. List heads's previous
   /// pointers are to the tail of the list, allowing for efficient access to the
   /// list tail. D must be a valid entry node.
   bool isHead(const SMSNode &D) const {
     assert(D.isValid() && "Invalid node for head");
     return Dense[D.Prev].isTail();
   }
 
   /// Whether the given entry is a singleton entry, i.e. the only entry with
   /// that key.
   bool isSingleton(const SMSNode &N) const {
     assert(N.isValid() && "Invalid node for singleton");
     // Is N its own predecessor?
     return &Dense[N.Prev] == &N;
   }
 
   /// Add in the given SMSNode. Uses a free entry in our freelist if
   /// available. Returns the index of the added node.
   unsigned addValue(const ValueT& V, unsigned Prev, unsigned Next) {
     if (NumFree == 0) {
       Dense.push_back(SMSNode(V, Prev, Next));
       return Dense.size() - 1;
     }
 
     // Peel off a free slot
     unsigned Idx = FreelistIdx;
     unsigned NextFree = Dense[Idx].Next;
     assert(Dense[Idx].isTombstone() && "Non-tombstone free?");
 
     Dense[Idx] = SMSNode(V, Prev, Next);
     FreelistIdx = NextFree;
     --NumFree;
     return Idx;
   }
 
   /// Make the current index a new tombstone. Pushes it onto the freelist.
   void makeTombstone(unsigned Idx) {
     Dense[Idx].Prev = SMSNode::INVALID;
     Dense[Idx].Next = FreelistIdx;
     FreelistIdx = Idx;
     ++NumFree;
   }
 
 public:
   using value_type = ValueT;
   using reference = ValueT &;
   using const_reference = const ValueT &;
   using pointer = ValueT *;
   using const_pointer = const ValueT *;
   using size_type = unsigned;
 
   SparseMultiSet() = default;
   SparseMultiSet(const SparseMultiSet &) = delete;
   SparseMultiSet &operator=(const SparseMultiSet &) = delete;
   ~SparseMultiSet() { free(Sparse); }
 
   /// Set the universe size which determines the largest key the set can hold.
   /// The universe must be sized before any elements can be added.
   ///
   /// @param U Universe size. All object keys must be less than U.
   ///
   void setUniverse(unsigned U) {
     // It's not hard to resize the universe on a non-empty set, but it doesn't
     // seem like a likely use case, so we can add that code when we need it.
     assert(empty() && "Can only resize universe on an empty map");
     // Hysteresis prevents needless reallocations.
     if (U >= Universe/4 && U <= Universe)
       return;
     free(Sparse);
     // The Sparse array doesn't actually need to be initialized, so malloc
     // would be enough here, but that will cause tools like valgrind to
     // complain about branching on uninitialized data.
     Sparse = static_cast<SparseT*>(safe_calloc(U, sizeof(SparseT)));
     Universe = U;
   }
 
   /// Our iterators are iterators over the collection of objects that share a
   /// key.
   template <typename SMSPtrTy> class iterator_base {
     friend class SparseMultiSet;
 
   public:
     using iterator_category = std::bidirectional_iterator_tag;
     using value_type = ValueT;
     using difference_type = std::ptrdiff_t;
     using pointer = value_type *;
     using reference = value_type &;
 
   private:
     SMSPtrTy SMS;
     unsigned Idx;
     unsigned SparseIdx;
 
     iterator_base(SMSPtrTy P, unsigned I, unsigned SI)
       : SMS(P), Idx(I), SparseIdx(SI) {}
 
     /// Whether our iterator has fallen outside our dense vector.
     bool isEnd() const {
       if (Idx == SMSNode::INVALID)
         return true;
 
       assert(Idx < SMS->Dense.size() && "Out of range, non-INVALID Idx?");
       return false;
     }
 
     /// Whether our iterator is properly keyed, i.e. the SparseIdx is valid
     bool isKeyed() const { return SparseIdx < SMS->Universe; }
 
     unsigned Prev() const { return SMS->Dense[Idx].Prev; }
     unsigned Next() const { return SMS->Dense[Idx].Next; }
 
     void setPrev(unsigned P) { SMS->Dense[Idx].Prev = P; }
     void setNext(unsigned N) { SMS->Dense[Idx].Next = N; }
 
   public:
     reference operator*() const {
       assert(isKeyed() && SMS->sparseIndex(SMS->Dense[Idx].Data) == SparseIdx &&
              "Dereferencing iterator of invalid key or index");
 
       return SMS->Dense[Idx].Data;
     }
     pointer operator->() const { return &operator*(); }
 
     /// Comparison operators
     bool operator==(const iterator_base &RHS) const {
       // end compares equal
       if (SMS == RHS.SMS && Idx == RHS.Idx) {
         assert((isEnd() || SparseIdx == RHS.SparseIdx) &&
                "Same dense entry, but different keys?");
         return true;
       }
 
       return false;
     }
 
     bool operator!=(const iterator_base &RHS) const {
       return !operator==(RHS);
     }
 
     /// Increment and decrement operators
     iterator_base &operator--() { // predecrement - Back up
       assert(isKeyed() && "Decrementing an invalid iterator");
       assert((isEnd() || !SMS->isHead(SMS->Dense[Idx])) &&
              "Decrementing head of list");
 
       // If we're at the end, then issue a new find()
       if (isEnd())
         Idx = SMS->findIndex(SparseIdx).Prev();
       else
         Idx = Prev();
 
       return *this;
     }
     iterator_base &operator++() { // preincrement - Advance
       assert(!isEnd() && isKeyed() && "Incrementing an invalid/end iterator");
       Idx = Next();
       return *this;
     }
     iterator_base operator--(int) { // postdecrement
       iterator_base I(*this);
       --*this;
       return I;
     }
     iterator_base operator++(int) { // postincrement
       iterator_base I(*this);
       ++*this;
       return I;
     }
   };
 
   using iterator = iterator_base<SparseMultiSet *>;
   using const_iterator = iterator_base<const SparseMultiSet *>;
 
   // Convenience types
   using RangePair = std::pair<iterator, iterator>;
 
   /// Returns an iterator past this container. Note that such an iterator cannot
   /// be decremented, but will compare equal to other end iterators.
   iterator end() { return iterator(this, SMSNode::INVALID, SMSNode::INVALID); }
   const_iterator end() const {
     return const_iterator(this, SMSNode::INVALID, SMSNode::INVALID);
   }
 
   /// Returns true if the set is empty.
   ///
   /// This is not the same as BitVector::empty().
   ///
   bool empty() const { return size() == 0; }
 
   /// Returns the number of elements in the set.
   ///
   /// This is not the same as BitVector::size() which returns the size of the
   /// universe.
   ///
   size_type size() const {
     assert(NumFree <= Dense.size() && "Out-of-bounds free entries");
     return Dense.size() - NumFree;
   }
 
   /// Clears the set.  This is a very fast constant time operation.
   ///
   void clear() {
     // Sparse does not need to be cleared, see find().
     Dense.clear();
     NumFree = 0;
     FreelistIdx = SMSNode::INVALID;
   }
 
   /// Find an element by its index.
   ///
   /// @param   Idx A valid index to find.
   /// @returns An iterator to the element identified by key, or end().
   ///
   iterator findIndex(unsigned Idx) {
     assert(Idx < Universe && "Key out of range");
     const unsigned Stride = std::numeric_limits<SparseT>::max() + 1u;
     for (unsigned i = Sparse[Idx], e = Dense.size(); i < e; i += Stride) {
       const unsigned FoundIdx = sparseIndex(Dense[i]);
       // Check that we're pointing at the correct entry and that it is the head
       // of a valid list.
       if (Idx == FoundIdx && Dense[i].isValid() && isHead(Dense[i]))
         return iterator(this, i, Idx);
       // Stride is 0 when SparseT >= unsigned.  We don't need to loop.
       if (!Stride)
         break;
     }
     return end();
   }
 
   /// Find an element by its key.
   ///
   /// @param   Key A valid key to find.
   /// @returns An iterator to the element identified by key, or end().
   ///
   iterator find(const KeyT &Key) {
     return findIndex(KeyIndexOf(Key));
   }
 
   const_iterator find(const KeyT &Key) const {
     iterator I = const_cast<SparseMultiSet*>(this)->findIndex(KeyIndexOf(Key));
     return const_iterator(I.SMS, I.Idx, KeyIndexOf(Key));
   }
 
   /// Returns the number of elements identified by Key. This will be linear in
   /// the number of elements of that key.
   size_type count(const KeyT &Key) const {
     unsigned Ret = 0;
     for (const_iterator It = find(Key); It != end(); ++It)
       ++Ret;
 
     return Ret;
   }
 
   /// Returns true if this set contains an element identified by Key.
   bool contains(const KeyT &Key) const {
     return find(Key) != end();
   }
 
   /// Return the head and tail of the subset's list, otherwise returns end().
   iterator getHead(const KeyT &Key) { return find(Key); }
   iterator getTail(const KeyT &Key) {
     iterator I = find(Key);
     if (I != end())
       I = iterator(this, I.Prev(), KeyIndexOf(Key));
     return I;
   }
 
   /// The bounds of the range of items sharing Key K. First member is the head
   /// of the list, and the second member is a decrementable end iterator for
   /// that key.
   RangePair equal_range(const KeyT &K) {
     iterator B = find(K);
     iterator E = iterator(this, SMSNode::INVALID, B.SparseIdx);
     return std::make_pair(B, E);
   }
 
   /// Insert a new element at the tail of the subset list. Returns an iterator
   /// to the newly added entry.
   iterator insert(const ValueT &Val) {
     unsigned Idx = sparseIndex(Val);
     iterator I = findIndex(Idx);
 
     unsigned NodeIdx = addValue(Val, SMSNode::INVALID, SMSNode::INVALID);
 
     if (I == end()) {
       // Make a singleton list
       Sparse[Idx] = NodeIdx;
       Dense[NodeIdx].Prev = NodeIdx;
       return iterator(this, NodeIdx, Idx);
     }
 
     // Stick it at the end.
     unsigned HeadIdx = I.Idx;
     unsigned TailIdx = I.Prev();
     Dense[TailIdx].Next = NodeIdx;
     Dense[HeadIdx].Prev = NodeIdx;
     Dense[NodeIdx].Prev = TailIdx;
 
     return iterator(this, NodeIdx, Idx);
   }
 
   /// Erases an existing element identified by a valid iterator.
   ///
   /// This invalidates iterators pointing at the same entry, but erase() returns
   /// an iterator pointing to the next element in the subset's list. This makes
   /// it possible to erase selected elements while iterating over the subset:
   ///
   ///   tie(I, E) = Set.equal_range(Key);
   ///   while (I != E)
   ///     if (test(*I))
   ///       I = Set.erase(I);
   ///     else
   ///       ++I;
   ///
   /// Note that if the last element in the subset list is erased, this will
   /// return an end iterator which can be decremented to get the new tail (if it
   /// exists):
   ///
   ///  tie(B, I) = Set.equal_range(Key);
   ///  for (bool isBegin = B == I; !isBegin; /* empty */) {
   ///    isBegin = (--I) == B;
   ///    if (test(I))
   ///      break;
   ///    I = erase(I);
   ///  }
   iterator erase(iterator I) {
     assert(I.isKeyed() && !I.isEnd() && !Dense[I.Idx].isTombstone() &&
            "erasing invalid/end/tombstone iterator");
 
     // First, unlink the node from its list. Then swap the node out with the
     // dense vector's last entry
     iterator NextI = unlink(Dense[I.Idx]);
 
     // Put in a tombstone.
     makeTombstone(I.Idx);
 
     return NextI;
   }
 
   /// Erase all elements with the given key. This invalidates all
   /// iterators of that key.
   void eraseAll(const KeyT &K) {
     for (iterator I = find(K); I != end(); /* empty */)
       I = erase(I);
   }
 
 private:
   /// Unlink the node from its list. Returns the next node in the list.
   iterator unlink(const SMSNode &N) {
     if (isSingleton(N)) {
       // Singleton is already unlinked
       assert(N.Next == SMSNode::INVALID && "Singleton has next?");
       return iterator(this, SMSNode::INVALID, ValIndexOf(N.Data));
     }
 
     if (isHead(N)) {
       // If we're the head, then update the sparse array and our next.
       Sparse[sparseIndex(N)] = N.Next;
       Dense[N.Next].Prev = N.Prev;
       return iterator(this, N.Next, ValIndexOf(N.Data));
     }
 
     if (N.isTail()) {
       // If we're the tail, then update our head and our previous.
       findIndex(sparseIndex(N)).setPrev(N.Prev);
       Dense[N.Prev].Next = N.Next;
 
       // Give back an end iterator that can be decremented
       iterator I(this, N.Prev, ValIndexOf(N.Data));
       return ++I;
     }
 
     // Otherwise, just drop us
     Dense[N.Next].Prev = N.Prev;
     Dense[N.Prev].Next = N.Next;
     return iterator(this, N.Next, ValIndexOf(N.Data));
   }
 };
 
 } // end namespace llvm
 
 #endif // LLVM_ADT_SPARSEMULTISET_H

This page was automatically generated by the 2.3.7 LXR engine. The LXR team