include/llvm/ADT/SCCIterator.h

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