include/llvm/ADT/EquivalenceClasses.h

   1 //===-- llvm/ADT/EquivalenceClasses.h - Generic Equiv. Classes --*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by the LLVM research group and is distributed under
   6 // the University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // Generic implementation of equivalence classes through the use Tarjan's
  11 // efficient union-find algorithm.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_ADT_EQUIVALENCECLASSES_H
  16 #define LLVM_ADT_EQUIVALENCECLASSES_H
  17
  18 #include "llvm/ADT/iterator"
  19 #include <set>
  20
  21 namespace llvm {
  22
  23 /// EquivalenceClasses - This represents a collection of equivalence classes and
  24 /// supports three efficient operations: insert an element into a class of its
  25 /// own, union two classes, and find the class for a given element.  In
  26 /// addition to these modification methods, it is possible to iterate over all
  27 /// of the equivalence classes and all of the elements in a class.
  28 ///
  29 /// This implementation is an efficient implementation that only stores one copy
  30 /// of the element being indexed per entry in the set, and allows any arbitrary
  31 /// type to be indexed (as long as it can be ordered with operator<).
  32 ///
  33 /// Here is a simple example using integers:
  34 ///
  35 ///  EquivalenceClasses<int> EC;
  36 ///  EC.unionSets(1, 2);                // insert 1, 2 into the same set
  37 ///  EC.insert(4); EC.insert(5);        // insert 4, 5 into own sets
  38 ///  EC.unionSets(5, 1);                // merge the set for 1 with 5's set.
  39 ///
  40 ///  for (EquivalenceClasses<int>::iterator I = EC.begin(), E = EC.end();
  41 ///       I != E; ++I) {           // Iterate over all of the equivalence sets.
  42 ///    if (!I->isLeader()) continue;   // Ignore non-leader sets.
  43 ///    for (EquivalenceClasses<int>::member_iterator MI = EC.member_begin(I);
  44 ///         MI != EC.member_end(); ++MI)   // Loop over members in this set.
  45 ///      std::cerr << *MI << " ";  // Print member.
  46 ///    std::cerr << "\n";   // Finish set.
  47 ///  }
  48 ///
  49 /// This example prints:
  50 ///   4
  51 ///   5 1 2
  52 ///
  53 template <class ElemTy>
  54 class EquivalenceClasses {
  55   /// ECValue - The EquivalenceClasses data structure is just a set of these.
  56   /// Each of these represents a relation for a value.  First it stores the
  57   /// value itself, which provides the ordering that the set queries.  Next, it
  58   /// provides a "next pointer", which is used to enumerate all of the elements
  59   /// in the unioned set.  Finally, it defines either a "end of list pointer" or
  60   /// "leader pointer" depending on whether the value itself is a leader.  A
  61   /// "leader pointer" points to the node that is the leader for this element,
  62   /// if the node is not a leader.  A "end of list pointer" points to the last
  63   /// node in the list of members of this list.  Whether or not a node is a
  64   /// leader is determined by a bit stolen from one of the pointers.
  65   class ECValue {
  66     friend class EquivalenceClasses;
  67     mutable const ECValue *Leader, *Next;
  68     ElemTy Data;
  69     // ECValue ctor - Start out with EndOfList pointing to this node, Next is
  70     // Null, isLeader = true.
  71     ECValue(const ElemTy &Elt)
  72       : Leader(this), Next((ECValue*)(intptr_t)1), Data(Elt) {}
  73
  74     const ECValue *getLeader() const {
  75       if (isLeader()) return this;
  76       if (Leader->isLeader() == 0) return Leader;
  77       // Path compression.
  78       return Leader = Leader->getLeader();
  79     }
  80     const ECValue *getEndOfList() const {
  81       assert(isLeader() && "Cannot get the end of a list for a non-leader!");
  82       return Leader;
  83     }
  84
  85     void setNext(const ECValue *NewNext) const {
  86       assert(getNext() == 0 && "Already has a next pointer!");
  87       bool isL = isLeader();
  88       Next = (const ECValue*)((intptr_t)NewNext | isLeader());
  89     }
  90   public:
  91     ECValue(const ECValue &RHS) : Leader(this), Next((ECValue*)(intptr_t)1),
  92                                   Data(RHS.Data) {
  93       // Only support copying of singleton nodes.
  94       assert(RHS.isLeader() && RHS.getNext() == 0 && "Not a singleton!");
  95     }
  96
  97     bool operator<(const ECValue &UFN) const { return Data < UFN.Data; }
  98
  99     bool isLeader() const { return (intptr_t)Next & 1; }
 100     const ElemTy &getData() const { return Data; }
 101
 102     const ECValue *getNext() const {
 103       return (ECValue*)((intptr_t)Next & ~(intptr_t)1);
 104     }
 105
 106     template<typename T>
 107     bool operator<(const T &Val) const { return Data < Val; }
 108   };
 109
 110   /// TheMapping - This implicitly provides a mapping from ElemTy values to the
 111   /// ECValues, it just keeps the key as part of the value.
 112   std::set<ECValue> TheMapping;
 113
 114 public:
 115
 116   //===--------------------------------------------------------------------===//
 117   // Inspection methods
 118   //
 119
 120   /// iterator* - Provides a way to iterate over all values in the set.
 121   typedef typename std::set<ECValue>::const_iterator iterator;
 122   iterator begin() const { return TheMapping.begin(); }
 123   iterator end() const { return TheMapping.end(); }
 124
 125   /// member_* Iterate over the members of an equivalence class.
 126   ///
 127   class member_iterator;
 128   member_iterator member_begin(iterator I) const {
 129     // Only leaders provide anything to iterate over.
 130     return member_iterator(I->isLeader() ? &*I : 0);
 131   }
 132   member_iterator member_end() const {
 133     return member_iterator(0);
 134   }
 135
 136   //===--------------------------------------------------------------------===//
 137   // Mutation methods
 138
 139   /// insert - Insert a new value into the union/find set, ignoring the request
 140   /// if the value already exists.
 141   iterator insert(const ElemTy &Data) {
 142     return TheMapping.insert(Data).first;
 143   }
 144
 145   /// findLeader - Given a value in the set, return a member iterator for the
 146   /// equivalence class it is in.  This does the path-compression part that
 147   /// makes union-find "union findy".  This returns an end iterator if the value
 148   /// is not in the equivalence class.
 149   ///
 150   member_iterator findLeader(iterator I) const {
 151     if (I == TheMapping.end()) return member_end();
 152     return member_iterator(I->getLeader());
 153   }
 154   member_iterator findLeader(const ElemTy &V) const {
 155     return findLeader(TheMapping.find(V));
 156   }
 157
 158
 159   /// union - Merge the two equivalence sets for the specified values, inserting
 160   /// them if they do not already exist in the equivalence set.
 161   member_iterator unionSets(const ElemTy &V1, const ElemTy &V2) {
 162     return unionSets(findLeader(insert(V1)), findLeader(insert(V2)));
 163   }
 164   member_iterator unionSets(member_iterator L1, member_iterator L2) {
 165     assert(L1 != member_end() && L2 != member_end() && "Illegal inputs!");
 166     if (L1 == L2) return L1;   // Unifying the same two sets, noop.
 167
 168     // Otherwise, this is a real union operation.  Set the end of the L1 list to
 169     // point to the L2 leader node.
 170     const ECValue &L1LV = *L1.Node, &L2LV = *L2.Node;
 171     L1LV.getEndOfList()->setNext(&L2LV);
 172
 173     // Update L1LV's end of list pointer.
 174     L1LV.Leader = L2LV.getEndOfList();
 175
 176     // Clear L2's leader flag:
 177     L2LV.Next = L2LV.getNext();
 178
 179     // L2's leader is now L1.
 180     L2LV.Leader = &L1LV;
 181     return L1;
 182   }
 183
 184   class member_iterator : public forward_iterator<ElemTy, ptrdiff_t> {
 185     typedef forward_iterator<const ElemTy, ptrdiff_t> super;
 186     const ECValue *Node;
 187     friend class EquivalenceClasses;
 188   public:
 189     typedef size_t size_type;
 190     typedef typename super::pointer pointer;
 191     typedef typename super::reference reference;
 192
 193     explicit member_iterator() {}
 194     explicit member_iterator(const ECValue *N) : Node(N) {}
 195     member_iterator(const member_iterator &I) : Node(I.Node) {}
 196
 197     reference operator*() const {
 198       assert(Node != 0 && "Dereferencing end()!");
 199       return Node->getData();
 200     }
 201     reference operator->() const { return operator*(); }
 202
 203     member_iterator &operator++() {
 204       assert(Node != 0 && "++'d off the end of the list!");
 205       Node = Node->getNext();
 206       return *this;
 207     }
 208
 209     member_iterator operator++(int) {    // postincrement operators.
 210       member_iterator tmp = *this;
 211       ++*this;
 212       return tmp;
 213     }
 214
 215     bool operator==(const member_iterator &RHS) const {
 216       return Node == RHS.Node;
 217     }
 218     bool operator!=(const member_iterator &RHS) const {
 219       return Node != RHS.Node;
 220     }
 221   };
 222 };
 223
 224 } // End llvm namespace
 225
 226 #endif