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