include/llvm/Support/InstVisitor.h

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