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
31 namespace 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.
39 template <class GraphT, class GT = GraphTraits<GraphT>>
40 class 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
StackElementStackElement55 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
scc_iterator(NodeType * entryN)91 scc_iterator(NodeType *entryN) : visitNum(0) {
92 DFSVisitOne(entryN);
93 GetNextSCC();
94 }
95
96 /// End is when the DFS stack is empty.
scc_iterator()97 scc_iterator() {}
98
99 public:
begin(const GraphT & G)100 static scc_iterator begin(const GraphT &G) {
101 return scc_iterator(GT::getEntryNode(G));
102 }
end(const GraphT &)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().
isAtEnd()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.
ReplaceNode(NodeType * Old,NodeType * New)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
141 template <class GraphT, class GT>
DFSVisitOne(NodeType * N)142 void 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
153 template <class GraphT, class GT>
DFSVisitChildren()154 void 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
GetNextSCC()173 template <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
210 template <class GraphT, class GT>
hasLoop()211 bool 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.
scc_begin(const T & G)224 template <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.
scc_end(const T & G)229 template <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>.
scc_begin(const Inverse<T> & G)234 template <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>.
scc_end(const Inverse<T> & G)239 template <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