include/llvm/ADT/EquivalenceClasses.h

   1 //===-- llvm/ADT/EquivalenceClasses.h - Generic Equiv. Classes --*- 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 // 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/Support/DataTypes.h"
  19 #include <cassert>
  20 #include <set>
  21
  22 namespace llvm {
  23
  24 /// EquivalenceClasses - This represents a collection of equivalence classes and
  25 /// supports three efficient operations: insert an element into a class of its
  26 /// own, union two classes, and find the class for a given element.  In
  27 /// addition to these modification methods, it is possible to iterate over all
  28 /// of the equivalence classes and all of the elements in a class.
  29 ///
  30 /// This implementation is an efficient implementation that only stores one copy
  31 /// of the element being indexed per entry in the set, and allows any arbitrary
  32 /// type to be indexed (as long as it can be ordered with operator<).
  33 ///
  34 /// Here is a simple example using integers:
  35 ///
  36 /// \code
  37 ///  EquivalenceClasses<int> EC;
  38 ///  EC.unionSets(1, 2);                // insert 1, 2 into the same set
  39 ///  EC.insert(4); EC.insert(5);        // insert 4, 5 into own sets
  40 ///  EC.unionSets(5, 1);                // merge the set for 1 with 5's set.
  41 ///
  42 ///  for (EquivalenceClasses<int>::iterator I = EC.begin(), E = EC.end();
  43 ///       I != E; ++I) {           // Iterate over all of the equivalence sets.
  44 ///    if (!I->isLeader()) continue;   // Ignore non-leader sets.
  45 ///    for (EquivalenceClasses<int>::member_iterator MI = EC.member_begin(I);
  46 ///         MI != EC.member_end(); ++MI)   // Loop over members in this set.
  47 ///      cerr << *MI << " ";  // Print member.
  48 ///    cerr << "\n";   // Finish set.
  49 ///  }
  50 /// \endcode
  51 ///
  52 /// This example prints:
  53 ///   4
  54 ///   5 1 2
  55 ///
  56 template <class ElemTy>
  57 class EquivalenceClasses {
  58   /// ECValue - The EquivalenceClasses data structure is just a set of these.
  59   /// Each of these represents a relation for a value.  First it stores the
  60   /// value itself, which provides the ordering that the set queries.  Next, it
  61   /// provides a "next pointer", which is used to enumerate all of the elements
  62   /// in the unioned set.  Finally, it defines either a "end of list pointer" or
  63   /// "leader pointer" depending on whether the value itself is a leader.  A
  64   /// "leader pointer" points to the node that is the leader for this element,
  65   /// if the node is not a leader.  A "end of list pointer" points to the last
  66   /// node in the list of members of this list.  Whether or not a node is a
  67   /// leader is determined by a bit stolen from one of the pointers.
  68   class ECValue {
  69     friend class EquivalenceClasses;
  70     mutable const ECValue *Leader, *Next;
  71     ElemTy Data;
  72     // ECValue ctor - Start out with EndOfList pointing to this node, Next is
  73     // Null, isLeader = true.
  74     ECValue(const ElemTy &Elt)
  75       : Leader(this), Next((ECValue*)(intptr_t)1), Data(Elt) {}
  76
  77     const ECValue *getLeader() const {
  78       if (isLeader()) return this;
  79       if (Leader->isLeader()) return Leader;
  80       // Path compression.
  81       return Leader = Leader->getLeader();
  82     }
  83     const ECValue *getEndOfList() const {
  84       assert(isLeader() && "Cannot get the end of a list for a non-leader!");
  85       return Leader;
  86     }
  87
  88     void setNext(const ECValue *NewNext) const {
  89       assert(getNext() == 0 && "Already has a next pointer!");
  90       Next = (const ECValue*)((intptr_t)NewNext | (intptr_t)isLeader());
  91     }
  92   public:
  93     ECValue(const ECValue &RHS) : Leader(this), Next((ECValue*)(intptr_t)1),
  94                                   Data(RHS.Data) {
  95       // Only support copying of singleton nodes.
  96       assert(RHS.isLeader() && RHS.getNext() == 0 && "Not a singleton!");
  97     }
  98
  99     bool operator<(const ECValue &UFN) const { return Data < UFN.Data; }
 100
 101     bool isLeader() const { return (intptr_t)Next & 1; }
 102     const ElemTy &getData() const { return Data; }
 103
 104     const ECValue *getNext() const {
 105       return (ECValue*)((intptr_t)Next & ~(intptr_t)1);
 106     }
 107
 108     template<typename T>
 109     bool operator<(const T &Val) const { return Data < Val; }
 110   };
 111
 112   /// TheMapping - This implicitly provides a mapping from ElemTy values to the
 113   /// ECValues, it just keeps the key as part of the value.
 114   std::set<ECValue> TheMapping;
 115
 116 public:
 117   EquivalenceClasses() {}
 118   EquivalenceClasses(const EquivalenceClasses &RHS) {
 119     operator=(RHS);
 120   }
 121
 122   const EquivalenceClasses &operator=(const EquivalenceClasses &RHS) {
 123     TheMapping.clear();
 124     for (iterator I = RHS.begin(), E = RHS.end(); I != E; ++I)
 125       if (I->isLeader()) {
 126         member_iterator MI = RHS.member_begin(I);
 127         member_iterator LeaderIt = member_begin(insert(*MI));
 128         for (++MI; MI != member_end(); ++MI)
 129           unionSets(LeaderIt, member_begin(insert(*MI)));
 130       }
 131     return *this;
 132   }
 133
 134   //===--------------------------------------------------------------------===//
 135   // Inspection methods
 136   //
 137
 138   /// iterator* - Provides a way to iterate over all values in the set.
 139   typedef typename std::set<ECValue>::const_iterator iterator;
 140   iterator begin() const { return TheMapping.begin(); }
 141   iterator end() const { return TheMapping.end(); }
 142
 143   bool empty() const { return TheMapping.empty(); }
 144
 145   /// member_* Iterate over the members of an equivalence class.
 146   ///
 147   class member_iterator;
 148   member_iterator member_begin(iterator I) const {
 149     // Only leaders provide anything to iterate over.
 150     return member_iterator(I->isLeader() ? &*I : 0);
 151   }
 152   member_iterator member_end() const {
 153     return member_iterator(0);
 154   }
 155
 156   /// findValue - Return an iterator to the specified value.  If it does not
 157   /// exist, end() is returned.
 158   iterator findValue(const ElemTy &V) const {
 159     return TheMapping.find(V);
 160   }
 161
 162   /// getLeaderValue - Return the leader for the specified value that is in the
 163   /// set.  It is an error to call this method for a value that is not yet in
 164   /// the set.  For that, call getOrInsertLeaderValue(V).
 165   const ElemTy &getLeaderValue(const ElemTy &V) const {
 166     member_iterator MI = findLeader(V);
 167     assert(MI != member_end() && "Value is not in the set!");
 168     return *MI;
 169   }
 170
 171   /// getOrInsertLeaderValue - Return the leader for the specified value that is
 172   /// in the set.  If the member is not in the set, it is inserted, then
 173   /// returned.
 174   const ElemTy &getOrInsertLeaderValue(const ElemTy &V) {
 175     member_iterator MI = findLeader(insert(V));
 176     assert(MI != member_end() && "Value is not in the set!");
 177     return *MI;
 178   }
 179
 180   /// getNumClasses - Return the number of equivalence classes in this set.
 181   /// Note that this is a linear time operation.
 182   unsigned getNumClasses() const {
 183     unsigned NC = 0;
 184     for (iterator I = begin(), E = end(); I != E; ++I)
 185       if (I->isLeader()) ++NC;
 186     return NC;
 187   }
 188
 189
 190   //===--------------------------------------------------------------------===//
 191   // Mutation methods
 192
 193   /// insert - Insert a new value into the union/find set, ignoring the request
 194   /// if the value already exists.
 195   iterator insert(const ElemTy &Data) {
 196     return TheMapping.insert(ECValue(Data)).first;
 197   }
 198
 199   /// findLeader - Given a value in the set, return a member iterator for the
 200   /// equivalence class it is in.  This does the path-compression part that
 201   /// makes union-find "union findy".  This returns an end iterator if the value
 202   /// is not in the equivalence class.
 203   ///
 204   member_iterator findLeader(iterator I) const {
 205     if (I == TheMapping.end()) return member_end();
 206     return member_iterator(I->getLeader());
 207   }
 208   member_iterator findLeader(const ElemTy &V) const {
 209     return findLeader(TheMapping.find(V));
 210   }
 211
 212
 213   /// union - Merge the two equivalence sets for the specified values, inserting
 214   /// them if they do not already exist in the equivalence set.
 215   member_iterator unionSets(const ElemTy &V1, const ElemTy &V2) {
 216     iterator V1I = insert(V1), V2I = insert(V2);
 217     return unionSets(findLeader(V1I), findLeader(V2I));
 218   }
 219   member_iterator unionSets(member_iterator L1, member_iterator L2) {
 220     assert(L1 != member_end() && L2 != member_end() && "Illegal inputs!");
 221     if (L1 == L2) return L1;   // Unifying the same two sets, noop.
 222
 223     // Otherwise, this is a real union operation.  Set the end of the L1 list to
 224     // point to the L2 leader node.
 225     const ECValue &L1LV = *L1.Node, &L2LV = *L2.Node;
 226     L1LV.getEndOfList()->setNext(&L2LV);
 227
 228     // Update L1LV's end of list pointer.
 229     L1LV.Leader = L2LV.getEndOfList();
 230
 231     // Clear L2's leader flag:
 232     L2LV.Next = L2LV.getNext();
 233
 234     // L2's leader is now L1.
 235     L2LV.Leader = &L1LV;
 236     return L1;
 237   }
 238
 239   class member_iterator : public std::iterator<std::forward_iterator_tag,
 240                                                const ElemTy, ptrdiff_t> {
 241     typedef std::iterator<std::forward_iterator_tag,
 242                           const ElemTy, ptrdiff_t> super;
 243     const ECValue *Node;
 244     friend class EquivalenceClasses;
 245   public:
 246     typedef size_t size_type;
 247     typedef typename super::pointer pointer;
 248     typedef typename super::reference reference;
 249
 250     explicit member_iterator() {}
 251     explicit member_iterator(const ECValue *N) : Node(N) {}
 252
 253     reference operator*() const {
 254       assert(Node != 0 && "Dereferencing end()!");
 255       return Node->getData();
 256     }
 257     reference operator->() const { return operator*(); }
 258
 259     member_iterator &operator++() {
 260       assert(Node != 0 && "++'d off the end of the list!");
 261       Node = Node->getNext();
 262       return *this;
 263     }
 264
 265     member_iterator operator++(int) {    // postincrement operators.
 266       member_iterator tmp = *this;
 267       ++*this;
 268       return tmp;
 269     }
 270
 271     bool operator==(const member_iterator &RHS) const {
 272       return Node == RHS.Node;
 273     }
 274     bool operator!=(const member_iterator &RHS) const {
 275       return Node != RHS.Node;
 276     }
 277   };
 278 };
 279
 280 } // End llvm namespace
 281
 282 #endif