LLVM API Documentation

InstVisitor.h

Go to the documentation of this file.
00001 //===- llvm/Support/InstVisitor.h - Define instruction visitors -*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 
00010 
00011 #ifndef LLVM_SUPPORT_INSTVISITOR_H
00012 #define LLVM_SUPPORT_INSTVISITOR_H
00013 
00014 #include "llvm/Function.h"
00015 #include "llvm/Instructions.h"
00016 #include "llvm/Module.h"
00017 #include "llvm/Support/ErrorHandling.h"
00018 
00019 namespace llvm {
00020 
00021 // We operate on opaque instruction classes, so forward declare all instruction
00022 // types now...
00023 //
00024 #define HANDLE_INST(NUM, OPCODE, CLASS)   class CLASS;
00025 #include "llvm/Instruction.def"
00026 
00027 #define DELEGATE(CLASS_TO_VISIT) \
00028   return static_cast<SubClass*>(this)-> \
00029                visit##CLASS_TO_VISIT(static_cast<CLASS_TO_VISIT&>(I))
00030 
00031 
00032 /// @brief Base class for instruction visitors
00033 ///
00034 /// Instruction visitors are used when you want to perform different actions
00035 /// for different kinds of instructions without having to use lots of casts
00036 /// and a big switch statement (in your code, that is).
00037 ///
00038 /// To define your own visitor, inherit from this class, specifying your
00039 /// new type for the 'SubClass' template parameter, and "override" visitXXX
00040 /// functions in your class. I say "override" because this class is defined
00041 /// in terms of statically resolved overloading, not virtual functions.
00042 ///
00043 /// For example, here is a visitor that counts the number of malloc
00044 /// instructions processed:
00045 ///
00046 ///  /// Declare the class.  Note that we derive from InstVisitor instantiated
00047 ///  /// with _our new subclasses_ type.
00048 ///  ///
00049 ///  struct CountMallocVisitor : public InstVisitor<CountMallocVisitor> {
00050 ///    unsigned Count;
00051 ///    CountMallocVisitor() : Count(0) {}
00052 ///
00053 ///    void visitMallocInst(MallocInst &MI) { ++Count; }
00054 ///  };
00055 ///
00056 ///  And this class would be used like this:
00057 ///    CountMallocVistor CMV;
00058 ///    CMV.visit(function);
00059 ///    NumMallocs = CMV.Count;
00060 ///
00061 /// The defined has 'visit' methods for Instruction, and also for BasicBlock,
00062 /// Function, and Module, which recursively process all contained instructions.
00063 ///
00064 /// Note that if you don't implement visitXXX for some instruction type,
00065 /// the visitXXX method for instruction superclass will be invoked. So
00066 /// if instructions are added in the future, they will be automatically
00067 /// supported, if you handle one of their superclasses.
00068 ///
00069 /// The optional second template argument specifies the type that instruction
00070 /// visitation functions should return. If you specify this, you *MUST* provide
00071 /// an implementation of visitInstruction though!.
00072 ///
00073 /// Note that this class is specifically designed as a template to avoid
00074 /// virtual function call overhead.  Defining and using an InstVisitor is just
00075 /// as efficient as having your own switch statement over the instruction
00076 /// opcode.
00077 template<typename SubClass, typename RetTy=void>
00078 class InstVisitor {
00079   //===--------------------------------------------------------------------===//
00080   // Interface code - This is the public interface of the InstVisitor that you
00081   // use to visit instructions...
00082   //
00083 
00084 public:
00085   // Generic visit method - Allow visitation to all instructions in a range
00086   template<class Iterator>
00087   void visit(Iterator Start, Iterator End) {
00088     while (Start != End)
00089       static_cast<SubClass*>(this)->visit(*Start++);
00090   }
00091 
00092   // Define visitors for functions and basic blocks...
00093   //
00094   void visit(Module &M) {
00095     static_cast<SubClass*>(this)->visitModule(M);
00096     visit(M.begin(), M.end());
00097   }
00098   void visit(Function &F) {
00099     static_cast<SubClass*>(this)->visitFunction(F);
00100     visit(F.begin(), F.end());
00101   }
00102   void visit(BasicBlock &BB) {
00103     static_cast<SubClass*>(this)->visitBasicBlock(BB);
00104     visit(BB.begin(), BB.end());
00105   }
00106 
00107   // Forwarding functions so that the user can visit with pointers AND refs.
00108   void visit(Module       *M)  { visit(*M); }
00109   void visit(Function     *F)  { visit(*F); }
00110   void visit(BasicBlock   *BB) { visit(*BB); }
00111   RetTy visit(Instruction *I)  { return visit(*I); }
00112 
00113   // visit - Finally, code to visit an instruction...
00114   //
00115   RetTy visit(Instruction &I) {
00116     switch (I.getOpcode()) {
00117     default: llvm_unreachable("Unknown instruction type encountered!");
00118       // Build the switch statement using the Instruction.def file...
00119 #define HANDLE_INST(NUM, OPCODE, CLASS) \
00120     case Instruction::OPCODE: return \
00121            static_cast<SubClass*>(this)-> \
00122                       visit##OPCODE(static_cast<CLASS&>(I));
00123 #include "llvm/Instruction.def"
00124     }
00125   }
00126 
00127   //===--------------------------------------------------------------------===//
00128   // Visitation functions... these functions provide default fallbacks in case
00129   // the user does not specify what to do for a particular instruction type.
00130   // The default behavior is to generalize the instruction type to its subtype
00131   // and try visiting the subtype.  All of this should be inlined perfectly,
00132   // because there are no virtual functions to get in the way.
00133   //
00134 
00135   // When visiting a module, function or basic block directly, these methods get
00136   // called to indicate when transitioning into a new unit.
00137   //
00138   void visitModule    (Module &M) {}
00139   void visitFunction  (Function &F) {}
00140   void visitBasicBlock(BasicBlock &BB) {}
00141 
00142   // Define instruction specific visitor functions that can be overridden to
00143   // handle SPECIFIC instructions.  These functions automatically define
00144   // visitMul to proxy to visitBinaryOperator for instance in case the user does
00145   // not need this generality.
00146   //
00147   // The one problem case we have to handle here though is that the PHINode
00148   // class and opcode name are the exact same.  Because of this, we cannot
00149   // define visitPHINode (the inst version) to forward to visitPHINode (the
00150   // generic version) without multiply defined symbols and recursion.  To handle
00151   // this, we do not autoexpand "Other" instructions, we do it manually.
00152   //
00153 #define HANDLE_INST(NUM, OPCODE, CLASS) \
00154     RetTy visit##OPCODE(CLASS &I) { DELEGATE(CLASS); }
00155 #include "llvm/Instruction.def"
00156 
00157   // Specific Instruction type classes... note that all of the casts are
00158   // necessary because we use the instruction classes as opaque types...
00159   //
00160   RetTy visitReturnInst(ReturnInst &I)              { DELEGATE(TerminatorInst);}
00161   RetTy visitBranchInst(BranchInst &I)              { DELEGATE(TerminatorInst);}
00162   RetTy visitSwitchInst(SwitchInst &I)              { DELEGATE(TerminatorInst);}
00163   RetTy visitInvokeInst(InvokeInst &I)              { DELEGATE(TerminatorInst);}
00164   RetTy visitUnwindInst(UnwindInst &I)              { DELEGATE(TerminatorInst);}
00165   RetTy visitUnreachableInst(UnreachableInst &I)    { DELEGATE(TerminatorInst);}
00166   RetTy visitICmpInst(ICmpInst &I)                  { DELEGATE(CmpInst);}
00167   RetTy visitFCmpInst(FCmpInst &I)                  { DELEGATE(CmpInst);}
00168   RetTy visitMallocInst(MallocInst &I)              { DELEGATE(AllocationInst);}
00169   RetTy visitAllocaInst(AllocaInst &I)              { DELEGATE(AllocationInst);}
00170   RetTy visitFreeInst(FreeInst     &I)              { DELEGATE(Instruction); }
00171   RetTy visitLoadInst(LoadInst     &I)              { DELEGATE(Instruction); }
00172   RetTy visitStoreInst(StoreInst   &I)              { DELEGATE(Instruction); }
00173   RetTy visitGetElementPtrInst(GetElementPtrInst &I){ DELEGATE(Instruction); }
00174   RetTy visitPHINode(PHINode       &I)              { DELEGATE(Instruction); }
00175   RetTy visitTruncInst(TruncInst &I)                { DELEGATE(CastInst); }
00176   RetTy visitZExtInst(ZExtInst &I)                  { DELEGATE(CastInst); }
00177   RetTy visitSExtInst(SExtInst &I)                  { DELEGATE(CastInst); }
00178   RetTy visitFPTruncInst(FPTruncInst &I)            { DELEGATE(CastInst); }
00179   RetTy visitFPExtInst(FPExtInst &I)                { DELEGATE(CastInst); }
00180   RetTy visitFPToUIInst(FPToUIInst &I)              { DELEGATE(CastInst); }
00181   RetTy visitFPToSIInst(FPToSIInst &I)              { DELEGATE(CastInst); }
00182   RetTy visitUIToFPInst(UIToFPInst &I)              { DELEGATE(CastInst); }
00183   RetTy visitSIToFPInst(SIToFPInst &I)              { DELEGATE(CastInst); }
00184   RetTy visitPtrToIntInst(PtrToIntInst &I)          { DELEGATE(CastInst); }
00185   RetTy visitIntToPtrInst(IntToPtrInst &I)          { DELEGATE(CastInst); }
00186   RetTy visitBitCastInst(BitCastInst &I)            { DELEGATE(CastInst); }
00187   RetTy visitSelectInst(SelectInst &I)              { DELEGATE(Instruction); }
00188   RetTy visitCallInst(CallInst     &I)              { DELEGATE(Instruction); }
00189   RetTy visitVAArgInst(VAArgInst   &I)              { DELEGATE(Instruction); }
00190   RetTy visitExtractElementInst(ExtractElementInst &I) { DELEGATE(Instruction);}
00191   RetTy visitInsertElementInst(InsertElementInst &I) { DELEGATE(Instruction); }
00192   RetTy visitShuffleVectorInst(ShuffleVectorInst &I) { DELEGATE(Instruction); }
00193   RetTy visitExtractValueInst(ExtractValueInst &I)  { DELEGATE(Instruction);}
00194   RetTy visitInsertValueInst(InsertValueInst &I)    { DELEGATE(Instruction); }
00195 
00196   // Next level propagators: If the user does not overload a specific
00197   // instruction type, they can overload one of these to get the whole class
00198   // of instructions...
00199   //
00200   RetTy visitTerminatorInst(TerminatorInst &I) { DELEGATE(Instruction); }
00201   RetTy visitBinaryOperator(BinaryOperator &I) { DELEGATE(Instruction); }
00202   RetTy visitAllocationInst(AllocationInst &I) { DELEGATE(Instruction); }
00203   RetTy visitCmpInst(CmpInst &I)               { DELEGATE(Instruction); }
00204   RetTy visitCastInst(CastInst &I)             { DELEGATE(Instruction); }
00205 
00206   // If the user wants a 'default' case, they can choose to override this
00207   // function.  If this function is not overloaded in the user's subclass, then
00208   // this instruction just gets ignored.
00209   //
00210   // Note that you MUST override this function if your return type is not void.
00211   //
00212   void visitInstruction(Instruction &I) {}  // Ignore unhandled instructions
00213 };
00214 
00215 #undef DELEGATE
00216 
00217 } // End llvm namespace
00218 
00219 #endif