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