1//===- PassManager internal APIs and implementation details -----*- 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 header provides internal APIs and implementation details used by the
11/// pass management interfaces exposed in PassManager.h. To understand more
12/// context of why these particular interfaces are needed, see that header
13/// file. None of these APIs should be used elsewhere.
14///
15//===----------------------------------------------------------------------===//
16
17#ifndef LLVM_IR_PASSMANAGERINTERNAL_H
18#define LLVM_IR_PASSMANAGERINTERNAL_H
19
20#include "llvm/ADT/STLExtras.h"
21#include "llvm/ADT/StringRef.h"
22#include "llvm/IR/Analysis.h"
23#include "llvm/Support/raw_ostream.h"
24#include <memory>
25#include <type_traits>
26#include <utility>
27
28namespace llvm {
29
30template <typename IRUnitT> class AllAnalysesOn;
31template <typename IRUnitT, typename... ExtraArgTs> class AnalysisManager;
32class PreservedAnalyses;
33
34// Implementation details of the pass manager interfaces.
35namespace detail {
36
37/// Template for the abstract base class used to dispatch
38/// polymorphically over pass objects.
39template <typename IRUnitT, typename AnalysisManagerT, typename... ExtraArgTs>
40struct PassConcept {
41 // Boiler plate necessary for the container of derived classes.
42 virtual ~PassConcept() = default;
43
44 /// The polymorphic API which runs the pass over a given IR entity.
45 ///
46 /// Note that actual pass object can omit the analysis manager argument if
47 /// desired. Also that the analysis manager may be null if there is no
48 /// analysis manager in the pass pipeline.
49 virtual PreservedAnalyses run(IRUnitT &IR, AnalysisManagerT &AM,
50 ExtraArgTs... ExtraArgs) = 0;
51
52 virtual void
53 printPipeline(raw_ostream &OS,
54 function_ref<StringRef(StringRef)> MapClassName2PassName) = 0;
55 /// Polymorphic method to access the name of a pass.
56 virtual StringRef name() const = 0;
57
58 /// Polymorphic method to let a pass optionally exempted from skipping by
59 /// PassInstrumentation.
60 /// To opt-in, pass should implement `static bool isRequired()`. It's no-op
61 /// to have `isRequired` always return false since that is the default.
62 virtual bool isRequired() const = 0;
63};
64
65/// A template wrapper used to implement the polymorphic API.
66///
67/// Can be instantiated for any object which provides a \c run method accepting
68/// an \c IRUnitT& and an \c AnalysisManager<IRUnit>&. It requires the pass to
69/// be a copyable object.
70template <typename IRUnitT, typename PassT, typename AnalysisManagerT,
71 typename... ExtraArgTs>
72struct PassModel : PassConcept<IRUnitT, AnalysisManagerT, ExtraArgTs...> {
73 explicit PassModel(PassT Pass) : Pass(std::move(Pass)) {}
74 // We have to explicitly define all the special member functions because MSVC
75 // refuses to generate them.
76 PassModel(const PassModel &Arg) : Pass(Arg.Pass) {}
77 PassModel(PassModel &&Arg) : Pass(std::move(Arg.Pass)) {}
78
79 friend void swap(PassModel &LHS, PassModel &RHS) {
80 using std::swap;
81 swap(LHS.Pass, RHS.Pass);
82 }
83
84 PassModel &operator=(PassModel RHS) {
85 swap(*this, RHS);
86 return *this;
87 }
88
89 PreservedAnalyses run(IRUnitT &IR, AnalysisManagerT &AM,
90 ExtraArgTs... ExtraArgs) override {
91 return Pass.run(IR, AM, ExtraArgs...);
92 }
93
94 void printPipeline(
95 raw_ostream &OS,
96 function_ref<StringRef(StringRef)> MapClassName2PassName) override {
97 Pass.printPipeline(OS, MapClassName2PassName);
98 }
99
100 StringRef name() const override { return PassT::name(); }
101
102 template <typename T>
103 using has_required_t = decltype(std::declval<T &>().isRequired());
104
105 template <typename T> static bool passIsRequiredImpl() {
106 if constexpr (is_detected<has_required_t, T>::value)
107 return T::isRequired();
108 return false;
109 }
110
111 bool isRequired() const override { return passIsRequiredImpl<PassT>(); }
112
113 PassT Pass;
114};
115
116/// Abstract concept of an analysis result.
117///
118/// This concept is parameterized over the IR unit that this result pertains
119/// to.
120template <typename IRUnitT, typename InvalidatorT>
121struct AnalysisResultConcept {
122 virtual ~AnalysisResultConcept() = default;
123
124 /// Method to try and mark a result as invalid.
125 ///
126 /// When the outer analysis manager detects a change in some underlying
127 /// unit of the IR, it will call this method on all of the results cached.
128 ///
129 /// \p PA is a set of preserved analyses which can be used to avoid
130 /// invalidation because the pass which changed the underlying IR took care
131 /// to update or preserve the analysis result in some way.
132 ///
133 /// \p Inv is typically a \c AnalysisManager::Invalidator object that can be
134 /// used by a particular analysis result to discover if other analyses
135 /// results are also invalidated in the event that this result depends on
136 /// them. See the documentation in the \c AnalysisManager for more details.
137 ///
138 /// \returns true if the result is indeed invalid (the default).
139 virtual bool invalidate(IRUnitT &IR, const PreservedAnalyses &PA,
140 InvalidatorT &Inv) = 0;
141};
142
143/// SFINAE metafunction for computing whether \c ResultT provides an
144/// \c invalidate member function.
145template <typename IRUnitT, typename ResultT> class ResultHasInvalidateMethod {
146 using EnabledType = char;
147 struct DisabledType {
148 char a, b;
149 };
150
151 // Purely to help out MSVC which fails to disable the below specialization,
152 // explicitly enable using the result type's invalidate routine if we can
153 // successfully call that routine.
154 template <typename T> struct Nonce { using Type = EnabledType; };
155 template <typename T>
156 static typename Nonce<decltype(std::declval<T>().invalidate(
157 std::declval<IRUnitT &>(), std::declval<PreservedAnalyses>()))>::Type
158 check(rank<2>);
159
160 // First we define an overload that can only be taken if there is no
161 // invalidate member. We do this by taking the address of an invalidate
162 // member in an adjacent base class of a derived class. This would be
163 // ambiguous if there were an invalidate member in the result type.
164 template <typename T, typename U> static DisabledType NonceFunction(T U::*);
165 struct CheckerBase { int invalidate; };
166 template <typename T> struct Checker : CheckerBase, std::remove_cv_t<T> {};
167 template <typename T>
168 static decltype(NonceFunction(&Checker<T>::invalidate)) check(rank<1>);
169
170 // Now we have the fallback that will only be reached when there is an
171 // invalidate member, and enables the trait.
172 template <typename T>
173 static EnabledType check(rank<0>);
174
175public:
176 enum { Value = sizeof(check<ResultT>(rank<2>())) == sizeof(EnabledType) };
177};
178
179/// Wrapper to model the analysis result concept.
180///
181/// By default, this will implement the invalidate method with a trivial
182/// implementation so that the actual analysis result doesn't need to provide
183/// an invalidation handler. It is only selected when the invalidation handler
184/// is not part of the ResultT's interface.
185template <typename IRUnitT, typename PassT, typename ResultT,
186 typename InvalidatorT,
187 bool HasInvalidateHandler =
188 ResultHasInvalidateMethod<IRUnitT, ResultT>::Value>
189struct AnalysisResultModel;
190
191/// Specialization of \c AnalysisResultModel which provides the default
192/// invalidate functionality.
193template <typename IRUnitT, typename PassT, typename ResultT,
194 typename InvalidatorT>
195struct AnalysisResultModel<IRUnitT, PassT, ResultT, InvalidatorT, false>
196 : AnalysisResultConcept<IRUnitT, InvalidatorT> {
197 explicit AnalysisResultModel(ResultT Result) : Result(std::move(Result)) {}
198 // We have to explicitly define all the special member functions because MSVC
199 // refuses to generate them.
200 AnalysisResultModel(const AnalysisResultModel &Arg) : Result(Arg.Result) {}
201 AnalysisResultModel(AnalysisResultModel &&Arg)
202 : Result(std::move(Arg.Result)) {}
203
204 friend void swap(AnalysisResultModel &LHS, AnalysisResultModel &RHS) {
205 using std::swap;
206 swap(LHS.Result, RHS.Result);
207 }
208
209 AnalysisResultModel &operator=(AnalysisResultModel RHS) {
210 swap(*this, RHS);
211 return *this;
212 }
213
214 /// The model bases invalidation solely on being in the preserved set.
215 //
216 // FIXME: We should actually use two different concepts for analysis results
217 // rather than two different models, and avoid the indirect function call for
218 // ones that use the trivial behavior.
219 bool invalidate(IRUnitT &, const PreservedAnalyses &PA,
220 InvalidatorT &) override {
221 auto PAC = PA.template getChecker<PassT>();
222 return !PAC.preserved() &&
223 !PAC.template preservedSet<AllAnalysesOn<IRUnitT>>();
224 }
225
226 ResultT Result;
227};
228
229/// Specialization of \c AnalysisResultModel which delegates invalidate
230/// handling to \c ResultT.
231template <typename IRUnitT, typename PassT, typename ResultT,
232 typename InvalidatorT>
233struct AnalysisResultModel<IRUnitT, PassT, ResultT, InvalidatorT, true>
234 : AnalysisResultConcept<IRUnitT, InvalidatorT> {
235 explicit AnalysisResultModel(ResultT Result) : Result(std::move(Result)) {}
236 // We have to explicitly define all the special member functions because MSVC
237 // refuses to generate them.
238 AnalysisResultModel(const AnalysisResultModel &Arg) : Result(Arg.Result) {}
239 AnalysisResultModel(AnalysisResultModel &&Arg)
240 : Result(std::move(Arg.Result)) {}
241
242 friend void swap(AnalysisResultModel &LHS, AnalysisResultModel &RHS) {
243 using std::swap;
244 swap(LHS.Result, RHS.Result);
245 }
246
247 AnalysisResultModel &operator=(AnalysisResultModel RHS) {
248 swap(*this, RHS);
249 return *this;
250 }
251
252 /// The model delegates to the \c ResultT method.
253 bool invalidate(IRUnitT &IR, const PreservedAnalyses &PA,
254 InvalidatorT &Inv) override {
255 return Result.invalidate(IR, PA, Inv);
256 }
257
258 ResultT Result;
259};
260
261/// Abstract concept of an analysis pass.
262///
263/// This concept is parameterized over the IR unit that it can run over and
264/// produce an analysis result.
265template <typename IRUnitT, typename InvalidatorT, typename... ExtraArgTs>
266struct AnalysisPassConcept {
267 virtual ~AnalysisPassConcept() = default;
268
269 /// Method to run this analysis over a unit of IR.
270 /// \returns A unique_ptr to the analysis result object to be queried by
271 /// users.
272 virtual std::unique_ptr<AnalysisResultConcept<IRUnitT, InvalidatorT>>
273 run(IRUnitT &IR, AnalysisManager<IRUnitT, ExtraArgTs...> &AM,
274 ExtraArgTs... ExtraArgs) = 0;
275
276 /// Polymorphic method to access the name of a pass.
277 virtual StringRef name() const = 0;
278};
279
280/// Wrapper to model the analysis pass concept.
281///
282/// Can wrap any type which implements a suitable \c run method. The method
283/// must accept an \c IRUnitT& and an \c AnalysisManager<IRUnitT>& as arguments
284/// and produce an object which can be wrapped in a \c AnalysisResultModel.
285template <typename IRUnitT, typename PassT, typename InvalidatorT,
286 typename... ExtraArgTs>
287struct AnalysisPassModel
288 : AnalysisPassConcept<IRUnitT, InvalidatorT, ExtraArgTs...> {
289 explicit AnalysisPassModel(PassT Pass) : Pass(std::move(Pass)) {}
290 // We have to explicitly define all the special member functions because MSVC
291 // refuses to generate them.
292 AnalysisPassModel(const AnalysisPassModel &Arg) : Pass(Arg.Pass) {}
293 AnalysisPassModel(AnalysisPassModel &&Arg) : Pass(std::move(Arg.Pass)) {}
294
295 friend void swap(AnalysisPassModel &LHS, AnalysisPassModel &RHS) {
296 using std::swap;
297 swap(LHS.Pass, RHS.Pass);
298 }
299
300 AnalysisPassModel &operator=(AnalysisPassModel RHS) {
301 swap(*this, RHS);
302 return *this;
303 }
304
305 // FIXME: Replace PassT::Result with type traits when we use C++11.
306 using ResultModelT =
307 AnalysisResultModel<IRUnitT, PassT, typename PassT::Result, InvalidatorT>;
308
309 /// The model delegates to the \c PassT::run method.
310 ///
311 /// The return is wrapped in an \c AnalysisResultModel.
312 std::unique_ptr<AnalysisResultConcept<IRUnitT, InvalidatorT>>
313 run(IRUnitT &IR, AnalysisManager<IRUnitT, ExtraArgTs...> &AM,
314 ExtraArgTs... ExtraArgs) override {
315 return std::make_unique<ResultModelT>(
316 Pass.run(IR, AM, std::forward<ExtraArgTs>(ExtraArgs)...));
317 }
318
319 /// The model delegates to a static \c PassT::name method.
320 ///
321 /// The returned string ref must point to constant immutable data!
322 StringRef name() const override { return PassT::name(); }
323
324 PassT Pass;
325};
326
327} // end namespace detail
328
329} // end namespace llvm
330
331#endif // LLVM_IR_PASSMANAGERINTERNAL_H
332

source code of llvm/include/llvm/IR/PassManagerInternal.h