include/llvm/IR/InstVisitor.h

   1 //===- InstVisitor.h - Instruction visitor templates ------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10
  11 #ifndef LLVM_IR_INSTVISITOR_H
  12 #define LLVM_IR_INSTVISITOR_H
  13
  14 #include "llvm/IR/CallSite.h"
  15 #include "llvm/IR/Function.h"
  16 #include "llvm/IR/Instructions.h"
  17 #include "llvm/IR/IntrinsicInst.h"
  18 #include "llvm/IR/Intrinsics.h"
  19 #include "llvm/IR/Module.h"
  20 #include "llvm/Support/ErrorHandling.h"
  21
  22 namespace llvm {
  23
  24 // We operate on opaque instruction classes, so forward declare all instruction
  25 // types now...
  26 //
  27 #define HANDLE_INST(NUM, OPCODE, CLASS)   class CLASS;
  28 #include "llvm/IR/Instruction.def"
  29
  30 #define DELEGATE(CLASS_TO_VISIT) \
  31   return static_cast<SubClass*>(this)-> \
  32                visit##CLASS_TO_VISIT(static_cast<CLASS_TO_VISIT&>(I))
  33
  34
  35 /// @brief Base class for instruction visitors
  36 ///
  37 /// Instruction visitors are used when you want to perform different actions
  38 /// for different kinds of instructions without having to use lots of casts
  39 /// and a big switch statement (in your code, that is).
  40 ///
  41 /// To define your own visitor, inherit from this class, specifying your
  42 /// new type for the 'SubClass' template parameter, and "override" visitXXX
  43 /// functions in your class. I say "override" because this class is defined
  44 /// in terms of statically resolved overloading, not virtual functions.
  45 ///
  46 /// For example, here is a visitor that counts the number of malloc
  47 /// instructions processed:
  48 ///
  49 ///  /// Declare the class.  Note that we derive from InstVisitor instantiated
  50 ///  /// with _our new subclasses_ type.
  51 ///  ///
  52 ///  struct CountAllocaVisitor : public InstVisitor<CountAllocaVisitor> {
  53 ///    unsigned Count;
  54 ///    CountAllocaVisitor() : Count(0) {}
  55 ///
  56 ///    void visitAllocaInst(AllocaInst &AI) { ++Count; }
  57 ///  };
  58 ///
  59 ///  And this class would be used like this:
  60 ///    CountAllocaVisitor CAV;
  61 ///    CAV.visit(function);
  62 ///    NumAllocas = CAV.Count;
  63 ///
  64 /// The defined has 'visit' methods for Instruction, and also for BasicBlock,
  65 /// Function, and Module, which recursively process all contained instructions.
  66 ///
  67 /// Note that if you don't implement visitXXX for some instruction type,
  68 /// the visitXXX method for instruction superclass will be invoked. So
  69 /// if instructions are added in the future, they will be automatically
  70 /// supported, if you handle one of their superclasses.
  71 ///
  72 /// The optional second template argument specifies the type that instruction
  73 /// visitation functions should return. If you specify this, you *MUST* provide
  74 /// an implementation of visitInstruction though!.
  75 ///
  76 /// Note that this class is specifically designed as a template to avoid
  77 /// virtual function call overhead.  Defining and using an InstVisitor is just
  78 /// as efficient as having your own switch statement over the instruction
  79 /// opcode.
  80 template<typename SubClass, typename RetTy=void>
  81 class InstVisitor {
  82   //===--------------------------------------------------------------------===//
  83   // Interface code - This is the public interface of the InstVisitor that you
  84   // use to visit instructions...
  85   //
  86
  87 public:
  88   // Generic visit method - Allow visitation to all instructions in a range
  89   template<class Iterator>
  90   void visit(Iterator Start, Iterator End) {
  91     while (Start != End)
  92       static_cast<SubClass*>(this)->visit(*Start++);
  93   }
  94
  95   // Define visitors for functions and basic blocks...
  96   //
  97   void visit(Module &M) {
  98     static_cast<SubClass*>(this)->visitModule(M);
  99     visit(M.begin(), M.end());
 100   }
 101   void visit(Function &F) {
 102     static_cast<SubClass*>(this)->visitFunction(F);
 103     visit(F.begin(), F.end());
 104   }
 105   void visit(BasicBlock &BB) {
 106     static_cast<SubClass*>(this)->visitBasicBlock(BB);
 107     visit(BB.begin(), BB.end());
 108   }
 109
 110   // Forwarding functions so that the user can visit with pointers AND refs.
 111   void visit(Module       *M)  { visit(*M); }
 112   void visit(Function     *F)  { visit(*F); }
 113   void visit(BasicBlock   *BB) { visit(*BB); }
 114   RetTy visit(Instruction *I)  { return visit(*I); }
 115
 116   // visit - Finally, code to visit an instruction...
 117   //
 118   RetTy visit(Instruction &I) {
 119     switch (I.getOpcode()) {
 120     default: llvm_unreachable("Unknown instruction type encountered!");
 121       // Build the switch statement using the Instruction.def file...
 122 #define HANDLE_INST(NUM, OPCODE, CLASS) \
 123     case Instruction::OPCODE: return \
 124            static_cast<SubClass*>(this)-> \
 125                       visit##OPCODE(static_cast<CLASS&>(I));
 126 #include "llvm/IR/Instruction.def"
 127     }
 128   }
 129
 130   //===--------------------------------------------------------------------===//
 131   // Visitation functions... these functions provide default fallbacks in case
 132   // the user does not specify what to do for a particular instruction type.
 133   // The default behavior is to generalize the instruction type to its subtype
 134   // and try visiting the subtype.  All of this should be inlined perfectly,
 135   // because there are no virtual functions to get in the way.
 136   //
 137
 138   // When visiting a module, function or basic block directly, these methods get
 139   // called to indicate when transitioning into a new unit.
 140   //
 141   void visitModule    (Module &M) {}
 142   void visitFunction  (Function &F) {}
 143   void visitBasicBlock(BasicBlock &BB) {}
 144
 145   // Define instruction specific visitor functions that can be overridden to
 146   // handle SPECIFIC instructions.  These functions automatically define
 147   // visitMul to proxy to visitBinaryOperator for instance in case the user does
 148   // not need this generality.
 149   //
 150   // These functions can also implement fan-out, when a single opcode and
 151   // instruction have multiple more specific Instruction subclasses. The Call
 152   // instruction currently supports this. We implement that by redirecting that
 153   // instruction to a special delegation helper.
 154 #define HANDLE_INST(NUM, OPCODE, CLASS) \
 155     RetTy visit##OPCODE(CLASS &I) { \
 156       if (NUM == Instruction::Call) \
 157         return delegateCallInst(I); \
 158       else \
 159         DELEGATE(CLASS); \
 160     }
 161 #include "llvm/IR/Instruction.def"
 162
 163   // Specific Instruction type classes... note that all of the casts are
 164   // necessary because we use the instruction classes as opaque types...
 165   //
 166   RetTy visitReturnInst(ReturnInst &I)            { DELEGATE(TerminatorInst);}
 167   RetTy visitBranchInst(BranchInst &I)            { DELEGATE(TerminatorInst);}
 168   RetTy visitSwitchInst(SwitchInst &I)            { DELEGATE(TerminatorInst);}
 169   RetTy visitIndirectBrInst(IndirectBrInst &I)    { DELEGATE(TerminatorInst);}
 170   RetTy visitResumeInst(ResumeInst &I)            { DELEGATE(TerminatorInst);}
 171   RetTy visitUnreachableInst(UnreachableInst &I)  { DELEGATE(TerminatorInst);}
 172   RetTy visitCleanupReturnInst(CleanupReturnInst &I) { DELEGATE(TerminatorInst);}
 173   RetTy visitCatchReturnInst(CatchReturnInst &I)  { DELEGATE(TerminatorInst);}
 174   RetTy visitCatchPadInst(CatchPadInst &I)    { DELEGATE(TerminatorInst);}
 175   RetTy visitCatchEndPadInst(CatchEndPadInst &I) { DELEGATE(TerminatorInst); }
 176   RetTy visitTerminatePadInst(TerminatePadInst &I) { DELEGATE(TerminatorInst);}
 177   RetTy visitICmpInst(ICmpInst &I)                { DELEGATE(CmpInst);}
 178   RetTy visitFCmpInst(FCmpInst &I)                { DELEGATE(CmpInst);}
 179   RetTy visitAllocaInst(AllocaInst &I)            { DELEGATE(UnaryInstruction);}
 180   RetTy visitLoadInst(LoadInst     &I)            { DELEGATE(UnaryInstruction);}
 181   RetTy visitStoreInst(StoreInst   &I)            { DELEGATE(Instruction);}
 182   RetTy visitAtomicCmpXchgInst(AtomicCmpXchgInst &I) { DELEGATE(Instruction);}
 183   RetTy visitAtomicRMWInst(AtomicRMWInst &I)      { DELEGATE(Instruction);}
 184   RetTy visitFenceInst(FenceInst   &I)            { DELEGATE(Instruction);}
 185   RetTy visitGetElementPtrInst(GetElementPtrInst &I){ DELEGATE(Instruction);}
 186   RetTy visitPHINode(PHINode       &I)            { DELEGATE(Instruction);}
 187   RetTy visitTruncInst(TruncInst &I)              { DELEGATE(CastInst);}
 188   RetTy visitZExtInst(ZExtInst &I)                { DELEGATE(CastInst);}
 189   RetTy visitSExtInst(SExtInst &I)                { DELEGATE(CastInst);}
 190   RetTy visitFPTruncInst(FPTruncInst &I)          { DELEGATE(CastInst);}
 191   RetTy visitFPExtInst(FPExtInst &I)              { DELEGATE(CastInst);}
 192   RetTy visitFPToUIInst(FPToUIInst &I)            { DELEGATE(CastInst);}
 193   RetTy visitFPToSIInst(FPToSIInst &I)            { DELEGATE(CastInst);}
 194   RetTy visitUIToFPInst(UIToFPInst &I)            { DELEGATE(CastInst);}
 195   RetTy visitSIToFPInst(SIToFPInst &I)            { DELEGATE(CastInst);}
 196   RetTy visitPtrToIntInst(PtrToIntInst &I)        { DELEGATE(CastInst);}
 197   RetTy visitIntToPtrInst(IntToPtrInst &I)        { DELEGATE(CastInst);}
 198   RetTy visitBitCastInst(BitCastInst &I)          { DELEGATE(CastInst);}
 199   RetTy visitAddrSpaceCastInst(AddrSpaceCastInst &I) { DELEGATE(CastInst);}
 200   RetTy visitSelectInst(SelectInst &I)            { DELEGATE(Instruction);}
 201   RetTy visitVAArgInst(VAArgInst   &I)            { DELEGATE(UnaryInstruction);}
 202   RetTy visitExtractElementInst(ExtractElementInst &I) { DELEGATE(Instruction);}
 203   RetTy visitInsertElementInst(InsertElementInst &I) { DELEGATE(Instruction);}
 204   RetTy visitShuffleVectorInst(ShuffleVectorInst &I) { DELEGATE(Instruction);}
 205   RetTy visitExtractValueInst(ExtractValueInst &I){ DELEGATE(UnaryInstruction);}
 206   RetTy visitInsertValueInst(InsertValueInst &I)  { DELEGATE(Instruction); }
 207   RetTy visitLandingPadInst(LandingPadInst &I)    { DELEGATE(Instruction); }
 208   RetTy visitCleanupPadInst(CleanupPadInst &I) { DELEGATE(Instruction); }
 209
 210   // Handle the special instrinsic instruction classes.
 211   RetTy visitDbgDeclareInst(DbgDeclareInst &I)    { DELEGATE(DbgInfoIntrinsic);}
 212   RetTy visitDbgValueInst(DbgValueInst &I)        { DELEGATE(DbgInfoIntrinsic);}
 213   RetTy visitDbgInfoIntrinsic(DbgInfoIntrinsic &I) { DELEGATE(IntrinsicInst); }
 214   RetTy visitMemSetInst(MemSetInst &I)            { DELEGATE(MemIntrinsic); }
 215   RetTy visitMemCpyInst(MemCpyInst &I)            { DELEGATE(MemTransferInst); }
 216   RetTy visitMemMoveInst(MemMoveInst &I)          { DELEGATE(MemTransferInst); }
 217   RetTy visitMemTransferInst(MemTransferInst &I)  { DELEGATE(MemIntrinsic); }
 218   RetTy visitMemIntrinsic(MemIntrinsic &I)        { DELEGATE(IntrinsicInst); }
 219   RetTy visitVAStartInst(VAStartInst &I)          { DELEGATE(IntrinsicInst); }
 220   RetTy visitVAEndInst(VAEndInst &I)              { DELEGATE(IntrinsicInst); }
 221   RetTy visitVACopyInst(VACopyInst &I)            { DELEGATE(IntrinsicInst); }
 222   RetTy visitIntrinsicInst(IntrinsicInst &I)      { DELEGATE(CallInst); }
 223
 224   // Call and Invoke are slightly different as they delegate first through
 225   // a generic CallSite visitor.
 226   RetTy visitCallInst(CallInst &I) {
 227     return static_cast<SubClass*>(this)->visitCallSite(&I);
 228   }
 229   RetTy visitInvokeInst(InvokeInst &I) {
 230     return static_cast<SubClass*>(this)->visitCallSite(&I);
 231   }
 232
 233   // Next level propagators: If the user does not overload a specific
 234   // instruction type, they can overload one of these to get the whole class
 235   // of instructions...
 236   //
 237   RetTy visitCastInst(CastInst &I)                { DELEGATE(UnaryInstruction);}
 238   RetTy visitBinaryOperator(BinaryOperator &I)    { DELEGATE(Instruction);}
 239   RetTy visitCmpInst(CmpInst &I)                  { DELEGATE(Instruction);}
 240   RetTy visitTerminatorInst(TerminatorInst &I)    { DELEGATE(Instruction);}
 241   RetTy visitUnaryInstruction(UnaryInstruction &I){ DELEGATE(Instruction);}
 242
 243   // Provide a special visitor for a 'callsite' that visits both calls and
 244   // invokes. When unimplemented, properly delegates to either the terminator or
 245   // regular instruction visitor.
 246   RetTy visitCallSite(CallSite CS) {
 247     assert(CS);
 248     Instruction &I = *CS.getInstruction();
 249     if (CS.isCall())
 250       DELEGATE(Instruction);
 251
 252     assert(CS.isInvoke());
 253     DELEGATE(TerminatorInst);
 254   }
 255
 256   // If the user wants a 'default' case, they can choose to override this
 257   // function.  If this function is not overloaded in the user's subclass, then
 258   // this instruction just gets ignored.
 259   //
 260   // Note that you MUST override this function if your return type is not void.
 261   //
 262   void visitInstruction(Instruction &I) {}  // Ignore unhandled instructions
 263
 264 private:
 265   // Special helper function to delegate to CallInst subclass visitors.
 266   RetTy delegateCallInst(CallInst &I) {
 267     if (const Function *F = I.getCalledFunction()) {
 268       switch (F->getIntrinsicID()) {
 269       default:                     DELEGATE(IntrinsicInst);
 270       case Intrinsic::dbg_declare: DELEGATE(DbgDeclareInst);
 271       case Intrinsic::dbg_value:   DELEGATE(DbgValueInst);
 272       case Intrinsic::memcpy:      DELEGATE(MemCpyInst);
 273       case Intrinsic::memmove:     DELEGATE(MemMoveInst);
 274       case Intrinsic::memset:      DELEGATE(MemSetInst);
 275       case Intrinsic::vastart:     DELEGATE(VAStartInst);
 276       case Intrinsic::vaend:       DELEGATE(VAEndInst);
 277       case Intrinsic::vacopy:      DELEGATE(VACopyInst);
 278       case Intrinsic::not_intrinsic: break;
 279       }
 280     }
 281     DELEGATE(CallInst);
 282   }
 283
 284   // An overload that will never actually be called, it is used only from dead
 285   // code in the dispatching from opcodes to instruction subclasses.
 286   RetTy delegateCallInst(Instruction &I) {
 287     llvm_unreachable("delegateCallInst called for non-CallInst");
 288   }
 289 };
 290
 291 #undef DELEGATE
 292
 293 } // End llvm namespace
 294
 295 #endif