include/llvm/Transforms/Pass.h

   1 //===- llvm/Transforms/Pass.h - Base class for XForm Passes ------*- C++ -*--=//
   2 //
   3 // This file defines a marker class that indicates that a specified class is a
   4 // transformation pass implementation.
   5 //
   6 // Pass's are designed this way so that it is possible to apply N passes to a
   7 // module, by first doing N Pass specific initializations for the module, then
   8 // looping over all of the methods in the module, doing method specific work
   9 // N times for each method.  Like this:
  10 //
  11 // for_each(Passes.begin(), Passes.end(), doPassInitialization(Module));
  12 // for_each(Method *M <- Module->begin(), Module->end())
  13 //   for_each(Passes.begin(), Passes.end(), doPerMethodWork(M));
  14 //
  15 // The other way to do things is like this:
  16 // for_each(Pass *P <- Passes.begin(), Passes.end()) {
  17 //   Passes->doPassInitialization(Module)
  18 //   for_each(Module->begin(), Module->end(), P->doPerMethodWork);
  19 // }
  20 //
  21 // But this can cause thrashing and poor cache performance, so we don't do it
  22 // that way.
  23 //
  24 // Because a transformation does not see all methods consecutively, it should
  25 // be careful about the state that it maintains... another pass may modify a
  26 // method between two invokacations of doPerMethodWork.
  27 //
  28 // Also, implementations of doMethodWork should not remove any methods from the
  29 // module.
  30 //
  31 //===----------------------------------------------------------------------===//
  32
  33 #ifndef LLVM_TRANSFORMS_PASS_H
  34 #define LLVM_TRANSFORMS_PASS_H
  35
  36 #include "llvm/Module.h"
  37 #include "llvm/Method.h"
  38
  39 //===----------------------------------------------------------------------===//
  40 // Pass interface - Implemented by all 'passes'.
  41 //
  42 struct Pass {
  43   //===--------------------------------------------------------------------===//
  44   // The externally useful entry points
  45   //
  46
  47   // runAllPasses - Run a bunch of passes on the specified module, efficiently.
  48   static bool runAllPasses(Module *M, vector<Pass*> &Passes) {
  49     for (unsigned i = 0; i < Passes.size(); ++i)
  50       if (Passes[i]->doPassInitializationVirt(M)) return true;
  51
  52     // Loop over all of the methods, applying all of the passes to them
  53     for (Module::iterator I = M->begin(); I != M->end(); ++I)
  54       for (unsigned i = 0; i < Passes.size(); ++i)
  55         if (Passes[i]->doPerMethodWorkVirt(*I)) return true;
  56     return false;
  57   }
  58
  59   // runAllPassesAndFree - Run a bunch of passes on the specified module,
  60   // efficiently.  When done, delete all of the passes.
  61   //
  62   static bool runAllPassesAndFree(Module *M, vector<Pass*> &Passes) {
  63     // First run all of the passes
  64     bool Result = runAllPasses(M, Passes);
  65
  66     // Free all of the passes.
  67     for (unsigned i = 0; i < Passes.size(); ++i)
  68       delete Passes[i];
  69     return Result;
  70   }
  71
  72
  73   // run(Module*) - Run this pass on a module and all of the methods contained
  74   // within it.  Returns false on success.
  75   //
  76   bool run(Module *M) {
  77     if (doPassInitializationVirt(M)) return true;
  78
  79     // Loop over methods in the module.  doPerMethodWork could add a method to
  80     // the Module, so we have to keep checking for end of method list condition.
  81     //
  82     for (Module::iterator I = M->begin(); I != M->end(); ++I)
  83       if (doPerMethodWorkVirt(*I)) return true;
  84     return false;
  85   }
  86
  87   // run(Method*) - Run this pass on a module and one specific method.  Returns
  88   // false on success.
  89   //
  90   bool run(Method *M) {
  91     if (doPassInitializationVirt(M->getParent())) return true;
  92     return doPerMethodWorkVirt(M);
  93   }
  94
  95
  96   //===--------------------------------------------------------------------===//
  97   // Functions to be implemented by subclasses
  98   //
  99
 100   // Destructor - Virtual so we can be subclassed
 101   inline virtual ~Pass() {}
 102
 103   // doPassInitializationVirt - Virtual method overridden by subclasses to do
 104   // any neccesary per-module initialization.  Returns false on success.
 105   //
 106   virtual bool doPassInitializationVirt(Module *M) = 0;
 107
 108   // doPerMethodWorkVirt - Virtual method overriden by subclasses to do the
 109   // per-method processing of the pass.  Returns false on success.
 110   //
 111   virtual bool doPerMethodWorkVirt(Method *M) = 0;
 112 };
 113
 114
 115 //===----------------------------------------------------------------------===//
 116 // ConcretePass class - This is used by implementations of passes to fill in
 117 // boiler plate code.
 118 //
 119 // Deriving from this class is good because if new methods are added in the
 120 // future, code for your pass won't have to change to stub out the unused
 121 // functionality.
 122 //
 123 struct ConcretePass : public Pass {
 124
 125   // doPassInitializationVirt - Default to success.
 126   virtual bool doPassInitializationVirt(Module *M) { return false; }
 127
 128   // doPerMethodWorkVirt - Default to success.
 129   virtual bool doPerMethodWorkVirt(Method *M) { return false; }
 130 };
 131
 132
 133
 134 //===----------------------------------------------------------------------===//
 135 // StatelessPass<t> class - This is used by implementations of passes to fill in
 136 // boiler plate code.  Subclassing this class indicates that a class has no
 137 // state to keep around, so it's safe to invoke static versions of functions.
 138 // This can be more efficient that using virtual function dispatch all of the
 139 // time.
 140 //
 141 // SubClass should be a concrete class that is derived from StatelessPass.
 142 //
 143 template<class SubClass>
 144 struct StatelessPass : public ConcretePass {
 145
 146   //===--------------------------------------------------------------------===//
 147   // The externally useful entry points - These are specialized to avoid the
 148   // overhead of virtual method invokations if
 149   //
 150   // run(Module*) - Run this pass on a module and all of the methods contained
 151   // within it.  Returns false on success.
 152   //
 153   static bool run(Module *M) {
 154     if (doPassInitialization(M->getParent())) return true;
 155
 156     // Loop over methods in the module.  doPerMethodWork could add a method to
 157     // the Module, so we have to keep checking for end of method list condition.
 158     //
 159     for (Module::iterator I = M->begin(); I != M->end(); ++I)
 160       if (doPerMethodWork(*I)) return true;
 161     return false;
 162   }
 163
 164   // run(Method*) - Run this pass on a module and one specific method.  Returns
 165   // false on success.
 166   //
 167   static bool run(Method *M) {
 168     if (doPassInitialization(M->getParent())) return true;
 169     return doPerMethodWork(M);
 170   }
 171
 172   //===--------------------------------------------------------------------===//
 173   // Default static method implementations, these should be defined in SubClass
 174
 175   static bool doPassInitialization(Module *M) { return false; }
 176   static bool doPerMethodWork(Method *M) { return false; }
 177
 178
 179   //===--------------------------------------------------------------------===//
 180   // Virtual method forwarders...
 181
 182   // doPassInitializationVirt - For a StatelessPass, default to implementing in
 183   // terms of the static method.
 184   //
 185   virtual bool doPassInitializationVirt(Module *M) {
 186     return SubClass::doPassInitialization(M);
 187   }
 188
 189   // doPerMethodWorkVirt - For a StatelessPass, default to implementing in
 190   // terms of the static method.
 191   //
 192   virtual bool doPerMethodWorkVirt(Method *M) {
 193     return SubClass::doPerMethodWork(M);
 194   }
 195 };
 196
 197 #endif
 198