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<t> class - This is used by implementations of passes to fill in
 117 // boiler plate code.  SubClass should be a concrete class that is derived from
 118 // ConcretePass.
 119 //
 120 // Deriving from this class is good because if new methods are added in the
 121 // future, code for your pass won't have to change to stub out the unused
 122 // functionality.
 123 //
 124 template<class SubClass>
 125 struct ConcretePass : public Pass {
 126
 127   // doPassInitializationVirt - Default to success.
 128   virtual bool doPassInitializationVirt(Module *M) { return false; }
 129
 130   // doPerMethodWorkVirt - Default to success.
 131   virtual bool doPerMethodWorkVirt(Method *M) { return false; }
 132 };
 133
 134
 135
 136 //===----------------------------------------------------------------------===//
 137 // StatelessPass<t> class - This is used by implementations of passes to fill in
 138 // boiler plate code.  Subclassing this class indicates that a class has no
 139 // state to keep around, so it's safe to invoke static versions of functions.
 140 // This can be more efficient that using virtual function dispatch all of the
 141 // time.
 142 //
 143 // SubClass should be a concrete class that is derived from StatelessPass.
 144 //
 145 template<class SubClass>
 146 struct StatelessPass : public ConcretePass<SubClass> {
 147
 148   //===--------------------------------------------------------------------===//
 149   // The externally useful entry points - These are specialized to avoid the
 150   // overhead of virtual method invokations if
 151   //
 152   // run(Module*) - Run this pass on a module and all of the methods contained
 153   // within it.  Returns false on success.
 154   //
 155   static bool run(Module *M) {
 156     if (doPassInitialization(M->getParent())) return true;
 157
 158     // Loop over methods in the module.  doPerMethodWork could add a method to
 159     // the Module, so we have to keep checking for end of method list condition.
 160     //
 161     for (Module::iterator I = M->begin(); I != M->end(); ++I)
 162       if (doPerMethodWork(*I)) return true;
 163     return false;
 164   }
 165
 166   // run(Method*) - Run this pass on a module and one specific method.  Returns
 167   // false on success.
 168   //
 169   static bool run(Method *M) {
 170     if (doPassInitialization(M->getParent())) return true;
 171     return doPerMethodWork(M);
 172   }
 173
 174   //===--------------------------------------------------------------------===//
 175   // Default static method implementations, these should be defined in SubClass
 176
 177   static bool doPassInitialization(Module *M) { return false; }
 178   static bool doPerMethodWork(Method *M) { return false; }
 179
 180
 181   //===--------------------------------------------------------------------===//
 182   // Virtual method forwarders...
 183
 184   // doPassInitializationVirt - For a StatelessPass, default to implementing in
 185   // terms of the static method.
 186   //
 187   virtual bool doPassInitializationVirt(Module *M) {
 188     return SubClass::doPassInitialization(M);
 189   }
 190
 191   // doPerMethodWorkVirt - For a StatelessPass, default to implementing in
 192   // terms of the static method.
 193   //
 194   virtual bool doPerMethodWorkVirt(Method *M) {
 195     return SubClass::doPerMethodWork(M);
 196   }
 197 };
 198
 199 #endif
 200