include/llvm/Support/InstVisitor.h

   1 //===- llvm/Support/InstVisitor.h - Define instruction visitors --*- C++ -*--=//
   2 //
   3 // This template class is used to define instruction visitors in a typesafe
   4 // manner without having to use lots of casts and a big switch statement (in
   5 // your code that is).  The win here is that if instructions are added in the
   6 // future, they will be added to the InstVisitor<T> class, allowing you to
   7 // automatically support them (if you handle on of their superclasses).
   8 //
   9 // Note that this library is specifically designed as a template to avoid
  10 // virtual function call overhead.  Defining and using an InstVisitor is just as
  11 // efficient as having your own switch statement over the instruction opcode.
  12 //
  13 // InstVisitor Usage:
  14 //   You define InstVisitors from inheriting from the InstVisitor base class
  15 // and "overriding" functions in your class.  I say "overriding" because this
  16 // class is defined in terms of statically resolved overloading, not virtual
  17 // functions.  As an example, here is a visitor that counts the number of malloc
  18 // instructions processed:
  19 //
  20 //  // Declare the class.  Note that we derive from InstVisitor instantiated
  21 //  // with _our new subclasses_ type.
  22 //  //
  23 //  struct CountMallocVisitor : public InstVisitor<CountMallocVisitor> {
  24 //    unsigned Count;
  25 //    CountMallocVisitor() : Count(0) {}
  26 //
  27 //    void visitMallocInst(MallocInst *MI) { ++Count; }
  28 //  };
  29 //
  30 //  And this class would be used like this:
  31 //    CountMallocVistor CMV;
  32 //    CMV.visit(function);
  33 //    NumMallocs = CMV.Count;
  34 //
  35 // Returning a value from the visitation function:
  36 //   The InstVisitor class takes an optional second template argument that
  37 // specifies what type the instruction visitation functions should return.  If
  38 // you specify this, you *MUST* provide an implementation of visitInstruction
  39 // though!.
  40 //
  41 //===----------------------------------------------------------------------===//
  42
  43 #ifndef LLVM_SUPPORT_INSTVISITOR_H
  44 #define LLVM_SUPPORT_INSTVISITOR_H
  45
  46 #include "llvm/Instruction.h"
  47
  48 // We operate on opaque instruction classes, so forward declare all instruction
  49 // types now...
  50 //
  51 #define HANDLE_INST(NUM, OPCODE, CLASS)   class CLASS;
  52 #include "llvm/Instruction.def"
  53
  54 // Forward declare the intermediate types...
  55 class TerminatorInst; class UnaryOperator; class BinaryOperator;
  56 class AllocationInst; class MemAccessInst;
  57
  58
  59 #define DELEGATE(CLASS_TO_VISIT) \
  60   return ((SubClass*)this)->visit##CLASS_TO_VISIT((CLASS_TO_VISIT*)I)
  61
  62
  63 template<typename SubClass, typename RetTy=void>
  64 struct InstVisitor {
  65   virtual ~InstVisitor() {}           // We are meant to be derived from
  66
  67   //===--------------------------------------------------------------------===//
  68   // Interface code - This is the public interface of the InstVisitor that you
  69   // use to visit instructions...
  70   //
  71
  72   // Generic visit method - Allow visitation to all instructions in a range
  73   template<class Iterator>
  74   void visit(Iterator Start, Iterator End) {
  75     while (Start != End)
  76       ((SubClass*)this)->visit(*Start++);
  77   }
  78
  79   // Define visitors for modules, functions and basic blocks...
  80   //
  81   void visit(Module *M) {
  82     ((SubClass*)this)->visitModule(M);
  83     visit(M->begin(), M->end());
  84   }
  85   void visit(Function *F) {
  86     ((SubClass*)this)->visitFunction(F);
  87     visit(F->begin(), F->end());
  88   }
  89   void visit(BasicBlock *BB) {
  90     ((SubClass*)this)->visitBasicBlock(BB);
  91     visit(BB->begin(), BB->end());
  92   }
  93
  94   // visit - Finally, code to visit an instruction...
  95   //
  96   RetTy visit(Instruction *I) {
  97     switch (I->getOpcode()) {
  98       // Build the switch statement using the Instruction.def file...
  99 #define HANDLE_INST(NUM, OPCODE, CLASS) \
 100     case Instruction::OPCODE:return ((SubClass*)this)->visit##OPCODE((CLASS*)I);
 101 #include "llvm/Instruction.def"
 102
 103     default: assert(0 && "Unknown instruction type encountered!");
 104              abort();
 105     }
 106   }
 107
 108   //===--------------------------------------------------------------------===//
 109   // Visitation functions... these functions provide default fallbacks in case
 110   // the user does not specify what to do for a particular instruction type.
 111   // The default behavior is to generalize the instruction type to its subtype
 112   // and try visiting the subtype.  All of this should be inlined perfectly,
 113   // because there are no virtual functions to get in the way.
 114   //
 115
 116   // When visiting a module, function or basic block directly, these methods get
 117   // called to indicate when transitioning into a new unit.
 118   //
 119   void visitModule    (Module *M) {}
 120   void visitFunction  (Function *F) {}
 121   void visitBasicBlock(BasicBlock *BB) {}
 122
 123
 124   // Define instruction specific visitor functions that can be overridden to
 125   // handle SPECIFIC instructions.  These functions automatically define
 126   // visitMul to proxy to visitBinaryOperator for instance in case the user does
 127   // not need this generality.
 128   //
 129   // The one problem case we have to handle here though is that the PHINode
 130   // class and opcode name are the exact same.  Because of this, we cannot
 131   // define visitPHINode (the inst version) to forward to visitPHINode (the
 132   // generic version) without multiply defined symbols and recursion.  To handle
 133   // this, we do not autoexpand "Other" instructions, we do it manually.
 134   //
 135 #define HANDLE_INST(NUM, OPCODE, CLASS) \
 136     RetTy visit##OPCODE(CLASS *I) { DELEGATE(CLASS); }
 137 #define HANDLE_OTHER_INST(NUM, OPCODE, CLASS)   // Ignore "other" instructions
 138 #include "llvm/Instruction.def"
 139
 140   // Implement all "other" instructions, except for PHINode
 141   RetTy visitCast(CastInst *I)       { DELEGATE(CastInst);    }
 142   RetTy visitCall(CallInst *I)       { DELEGATE(CallInst);    }
 143   RetTy visitShr(ShiftInst *I)       { DELEGATE(ShiftInst);   }
 144   RetTy visitShl(ShiftInst *I)       { DELEGATE(ShiftInst);   }
 145   RetTy visitUserOp1(Instruction *I) { DELEGATE(Instruction); }
 146   RetTy visitUserOp2(Instruction *I) { DELEGATE(Instruction); }
 147
 148
 149   // Specific Instruction type classes... note that all of the casts are
 150   // neccesary because we use the instruction classes as opaque types...
 151   //
 152   RetTy visitReturnInst(ReturnInst *I)              { DELEGATE(TerminatorInst);}
 153   RetTy visitBranchInst(BranchInst *I)              { DELEGATE(TerminatorInst);}
 154   RetTy visitSwitchInst(SwitchInst *I)              { DELEGATE(TerminatorInst);}
 155   RetTy visitInvokeInst(InvokeInst *I)              { DELEGATE(TerminatorInst);}
 156   RetTy visitGenericUnaryInst(GenericUnaryInst *I)  { DELEGATE(UnaryOperator); }
 157   RetTy visitGenericBinaryInst(GenericBinaryInst *I){ DELEGATE(BinaryOperator);}
 158   RetTy visitSetCondInst(SetCondInst *I)            { DELEGATE(BinaryOperator);}
 159   RetTy visitMallocInst(MallocInst *I)              { DELEGATE(AllocationInst);}
 160   RetTy visitAllocaInst(AllocaInst *I)              { DELEGATE(AllocationInst);}
 161   RetTy visitFreeInst(FreeInst   *I)                { DELEGATE(Instruction); }
 162   RetTy visitLoadInst(LoadInst   *I)                { DELEGATE(MemAccessInst); }
 163   RetTy visitStoreInst(StoreInst  *I)               { DELEGATE(MemAccessInst); }
 164   RetTy visitGetElementPtrInst(GetElementPtrInst *I){ DELEGATE(MemAccessInst); }
 165   RetTy visitPHINode(PHINode    *I)                 { DELEGATE(Instruction); }
 166   RetTy visitCastInst(CastInst   *I)                { DELEGATE(Instruction); }
 167   RetTy visitCallInst(CallInst   *I)                { DELEGATE(Instruction); }
 168   RetTy visitShiftInst(ShiftInst  *I)               { DELEGATE(Instruction); }
 169
 170   // Next level propogators... if the user does not overload a specific
 171   // instruction type, they can overload one of these to get the whole class
 172   // of instructions...
 173   //
 174   RetTy visitTerminatorInst(TerminatorInst *I) { DELEGATE(Instruction); }
 175   RetTy visitUnaryOperator (UnaryOperator  *I) { DELEGATE(Instruction); }
 176   RetTy visitBinaryOperator(BinaryOperator *I) { DELEGATE(Instruction); }
 177   RetTy visitAllocationInst(AllocationInst *I) { DELEGATE(Instruction); }
 178   RetTy visitMemAccessInst (MemAccessInst  *I) { DELEGATE(Instruction); }
 179
 180   // If the user wants a 'default' case, they can choose to override this
 181   // function.  If this function is not overloaded in the users subclass, then
 182   // this instruction just gets ignored.
 183   //
 184   // Note that you MUST override this function if your return type is not void.
 185   //
 186   void visitInstruction(Instruction *I) {}  // Ignore unhandled instructions
 187 };
 188
 189 #undef DELEGATE
 190
 191 #endif