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