contrib/llvm/include/llvm/ADT/SCCIterator.h

   1 //===---- ADT/SCCIterator.h - Strongly Connected Comp. Iter. ----*- 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 /// \file
  10 ///
  11 /// This builds on the llvm/ADT/GraphTraits.h file to find the strongly
  12 /// connected components (SCCs) of a graph in O(N+E) time using Tarjan's DFS
  13 /// algorithm.
  14 ///
  15 /// The SCC iterator has the important property that if a node in SCC S1 has an
  16 /// edge to a node in SCC S2, then it visits S1 *after* S2.
  17 ///
  18 /// To visit S1 *before* S2, use the scc_iterator on the Inverse graph. (NOTE:
  19 /// This requires some simple wrappers and is not supported yet.)
  20 ///
  21 //===----------------------------------------------------------------------===//
  22
  23 #ifndef LLVM_ADT_SCCITERATOR_H
  24 #define LLVM_ADT_SCCITERATOR_H
  25
  26 #include "llvm/ADT/DenseMap.h"
  27 #include "llvm/ADT/GraphTraits.h"
  28 #include "llvm/ADT/iterator.h"
  29 #include <cassert>
  30 #include <cstddef>
  31 #include <iterator>
  32 #include <vector>
  33
  34 namespace llvm {
  35
  36 /// \brief Enumerate the SCCs of a directed graph in reverse topological order
  37 /// of the SCC DAG.
  38 ///
  39 /// This is implemented using Tarjan's DFS algorithm using an internal stack to
  40 /// build up a vector of nodes in a particular SCC. Note that it is a forward
  41 /// iterator and thus you cannot backtrack or re-visit nodes.
  42 template <class GraphT, class GT = GraphTraits<GraphT>>
  43 class scc_iterator : public iterator_facade_base<
  44                          scc_iterator<GraphT, GT>, std::forward_iterator_tag,
  45                          const std::vector<typename GT::NodeRef>, ptrdiff_t> {
  46   typedef typename GT::NodeRef NodeRef;
  47   typedef typename GT::ChildIteratorType ChildItTy;
  48   typedef std::vector<NodeRef> SccTy;
  49   typedef typename scc_iterator::reference reference;
  50
  51   /// Element of VisitStack during DFS.
  52   struct StackElement {
  53     NodeRef Node;         ///< The current node pointer.
  54     ChildItTy NextChild;  ///< The next child, modified inplace during DFS.
  55     unsigned MinVisited;  ///< Minimum uplink value of all children of Node.
  56
  57     StackElement(NodeRef Node, const ChildItTy &Child, unsigned Min)
  58         : Node(Node), NextChild(Child), MinVisited(Min) {}
  59
  60     bool operator==(const StackElement &Other) const {
  61       return Node == Other.Node &&
  62              NextChild == Other.NextChild &&
  63              MinVisited == Other.MinVisited;
  64     }
  65   };
  66
  67   /// The visit counters used to detect when a complete SCC is on the stack.
  68   /// visitNum is the global counter.
  69   ///
  70   /// nodeVisitNumbers are per-node visit numbers, also used as DFS flags.
  71   unsigned visitNum;
  72   DenseMap<NodeRef, unsigned> nodeVisitNumbers;
  73
  74   /// Stack holding nodes of the SCC.
  75   std::vector<NodeRef> SCCNodeStack;
  76
  77   /// The current SCC, retrieved using operator*().
  78   SccTy CurrentSCC;
  79
  80   /// DFS stack, Used to maintain the ordering.  The top contains the current
  81   /// node, the next child to visit, and the minimum uplink value of all child
  82   std::vector<StackElement> VisitStack;
  83
  84   /// A single "visit" within the non-recursive DFS traversal.
  85   void DFSVisitOne(NodeRef N);
  86
  87   /// The stack-based DFS traversal; defined below.
  88   void DFSVisitChildren();
  89
  90   /// Compute the next SCC using the DFS traversal.
  91   void GetNextSCC();
  92
  93   scc_iterator(NodeRef entryN) : visitNum(0) {
  94     DFSVisitOne(entryN);
  95     GetNextSCC();
  96   }
  97
  98   /// End is when the DFS stack is empty.
  99   scc_iterator() = default;
 100
 101 public:
 102   static scc_iterator begin(const GraphT &G) {
 103     return scc_iterator(GT::getEntryNode(G));
 104   }
 105   static scc_iterator end(const GraphT &) { return scc_iterator(); }
 106
 107   /// \brief Direct loop termination test which is more efficient than
 108   /// comparison with \c end().
 109   bool isAtEnd() const {
 110     assert(!CurrentSCC.empty() || VisitStack.empty());
 111     return CurrentSCC.empty();
 112   }
 113
 114   bool operator==(const scc_iterator &x) const {
 115     return VisitStack == x.VisitStack && CurrentSCC == x.CurrentSCC;
 116   }
 117
 118   scc_iterator &operator++() {
 119     GetNextSCC();
 120     return *this;
 121   }
 122
 123   reference operator*() const {
 124     assert(!CurrentSCC.empty() && "Dereferencing END SCC iterator!");
 125     return CurrentSCC;
 126   }
 127
 128   /// \brief Test if the current SCC has a loop.
 129   ///
 130   /// If the SCC has more than one node, this is trivially true.  If not, it may
 131   /// still contain a loop if the node has an edge back to itself.
 132   bool hasLoop() const;
 133
 134   /// This informs the \c scc_iterator that the specified \c Old node
 135   /// has been deleted, and \c New is to be used in its place.
 136   void ReplaceNode(NodeRef Old, NodeRef New) {
 137     assert(nodeVisitNumbers.count(Old) && "Old not in scc_iterator?");
 138     nodeVisitNumbers[New] = nodeVisitNumbers[Old];
 139     nodeVisitNumbers.erase(Old);
 140   }
 141 };
 142
 143 template <class GraphT, class GT>
 144 void scc_iterator<GraphT, GT>::DFSVisitOne(NodeRef N) {
 145   ++visitNum;
 146   nodeVisitNumbers[N] = visitNum;
 147   SCCNodeStack.push_back(N);
 148   VisitStack.push_back(StackElement(N, GT::child_begin(N), visitNum));
 149 #if 0 // Enable if needed when debugging.
 150   dbgs() << "TarjanSCC: Node " << N <<
 151         " : visitNum = " << visitNum << "\n";
 152 #endif
 153 }
 154
 155 template <class GraphT, class GT>
 156 void scc_iterator<GraphT, GT>::DFSVisitChildren() {
 157   assert(!VisitStack.empty());
 158   while (VisitStack.back().NextChild != GT::child_end(VisitStack.back().Node)) {
 159     // TOS has at least one more child so continue DFS
 160     NodeRef childN = *VisitStack.back().NextChild++;
 161     typename DenseMap<NodeRef, unsigned>::iterator Visited =
 162         nodeVisitNumbers.find(childN);
 163     if (Visited == nodeVisitNumbers.end()) {
 164       // this node has never been seen.
 165       DFSVisitOne(childN);
 166       continue;
 167     }
 168
 169     unsigned childNum = Visited->second;
 170     if (VisitStack.back().MinVisited > childNum)
 171       VisitStack.back().MinVisited = childNum;
 172   }
 173 }
 174
 175 template <class GraphT, class GT> void scc_iterator<GraphT, GT>::GetNextSCC() {
 176   CurrentSCC.clear(); // Prepare to compute the next SCC
 177   while (!VisitStack.empty()) {
 178     DFSVisitChildren();
 179
 180     // Pop the leaf on top of the VisitStack.
 181     NodeRef visitingN = VisitStack.back().Node;
 182     unsigned minVisitNum = VisitStack.back().MinVisited;
 183     assert(VisitStack.back().NextChild == GT::child_end(visitingN));
 184     VisitStack.pop_back();
 185
 186     // Propagate MinVisitNum to parent so we can detect the SCC starting node.
 187     if (!VisitStack.empty() && VisitStack.back().MinVisited > minVisitNum)
 188       VisitStack.back().MinVisited = minVisitNum;
 189
 190 #if 0 // Enable if needed when debugging.
 191     dbgs() << "TarjanSCC: Popped node " << visitingN <<
 192           " : minVisitNum = " << minVisitNum << "; Node visit num = " <<
 193           nodeVisitNumbers[visitingN] << "\n";
 194 #endif
 195
 196     if (minVisitNum != nodeVisitNumbers[visitingN])
 197       continue;
 198
 199     // A full SCC is on the SCCNodeStack!  It includes all nodes below
 200     // visitingN on the stack.  Copy those nodes to CurrentSCC,
 201     // reset their minVisit values, and return (this suspends
 202     // the DFS traversal till the next ++).
 203     do {
 204       CurrentSCC.push_back(SCCNodeStack.back());
 205       SCCNodeStack.pop_back();
 206       nodeVisitNumbers[CurrentSCC.back()] = ~0U;
 207     } while (CurrentSCC.back() != visitingN);
 208     return;
 209   }
 210 }
 211
 212 template <class GraphT, class GT>
 213 bool scc_iterator<GraphT, GT>::hasLoop() const {
 214     assert(!CurrentSCC.empty() && "Dereferencing END SCC iterator!");
 215     if (CurrentSCC.size() > 1)
 216       return true;
 217     NodeRef N = CurrentSCC.front();
 218     for (ChildItTy CI = GT::child_begin(N), CE = GT::child_end(N); CI != CE;
 219          ++CI)
 220       if (*CI == N)
 221         return true;
 222     return false;
 223   }
 224
 225 /// \brief Construct the begin iterator for a deduced graph type T.
 226 template <class T> scc_iterator<T> scc_begin(const T &G) {
 227   return scc_iterator<T>::begin(G);
 228 }
 229
 230 /// \brief Construct the end iterator for a deduced graph type T.
 231 template <class T> scc_iterator<T> scc_end(const T &G) {
 232   return scc_iterator<T>::end(G);
 233 }
 234
 235 /// \brief Construct the begin iterator for a deduced graph type T's Inverse<T>.
 236 template <class T> scc_iterator<Inverse<T>> scc_begin(const Inverse<T> &G) {
 237   return scc_iterator<Inverse<T>>::begin(G);
 238 }
 239
 240 /// \brief Construct the end iterator for a deduced graph type T's Inverse<T>.
 241 template <class T> scc_iterator<Inverse<T>> scc_end(const Inverse<T> &G) {
 242   return scc_iterator<Inverse<T>>::end(G);
 243 }
 244
 245 } // end namespace llvm
 246
 247 #endif // LLVM_ADT_SCCITERATOR_H