LLVM API Documentation
00001 //===-- llvm/Module.h - C++ class to represent a VM module ------*- 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 /// @file This file contains the declarations for the Module class. 00011 // 00012 //===----------------------------------------------------------------------===// 00013 00014 #ifndef LLVM_MODULE_H 00015 #define LLVM_MODULE_H 00016 00017 #include "llvm/Function.h" 00018 #include "llvm/GlobalVariable.h" 00019 #include "llvm/ADT/SetVector.h" 00020 #include "llvm/Support/DataTypes.h" 00021 00022 namespace llvm { 00023 00024 class GlobalVariable; 00025 class GlobalValueRefMap; // Used by ConstantVals.cpp 00026 class FunctionType; 00027 class SymbolTable; 00028 00029 template<> struct ilist_traits<Function> 00030 : public SymbolTableListTraits<Function, Module, Module> { 00031 // createSentinel is used to create a node that marks the end of the list. 00032 static Function *createSentinel(); 00033 static void destroySentinel(Function *F) { delete F; } 00034 static iplist<Function> &getList(Module *M); 00035 }; 00036 template<> struct ilist_traits<GlobalVariable> 00037 : public SymbolTableListTraits<GlobalVariable, Module, Module> { 00038 // createSentinel is used to create a node that marks the end of the list. 00039 static GlobalVariable *createSentinel(); 00040 static void destroySentinel(GlobalVariable *GV) { delete GV; } 00041 static iplist<GlobalVariable> &getList(Module *M); 00042 }; 00043 00044 /// A Module instance is used to store all the information related to an 00045 /// LLVM module. Modules are the top level container of all other LLVM 00046 /// Intermediate Representation (IR) objects. Each module directly contains a 00047 /// list of globals variables, a list of functions, a list of libraries (or 00048 /// other modules) this module depends on, a symbol table, and various data 00049 /// about the target's characteristics. 00050 /// 00051 /// A module maintains a GlobalValRefMap object that is used to hold all 00052 /// constant references to global variables in the module. When a global 00053 /// variable is destroyed, it should have no entries in the GlobalValueRefMap. 00054 /// @brief The main container class for the LLVM Intermediate Representation. 00055 class Module { 00056 /// @name Types And Enumerations 00057 /// @{ 00058 public: 00059 /// The type for the list of global variables. 00060 typedef iplist<GlobalVariable> GlobalListType; 00061 /// The type for the list of functions. 00062 typedef iplist<Function> FunctionListType; 00063 00064 /// The type for the list of dependent libraries. 00065 typedef SetVector<std::string> LibraryListType; 00066 00067 /// The Global Variable iterator. 00068 typedef GlobalListType::iterator global_iterator; 00069 /// The Global Variable constant iterator. 00070 typedef GlobalListType::const_iterator const_global_iterator; 00071 00072 /// The Function iterators. 00073 typedef FunctionListType::iterator iterator; 00074 /// The Function constant iterator 00075 typedef FunctionListType::const_iterator const_iterator; 00076 00077 /// The Library list iterator. 00078 typedef LibraryListType::const_iterator lib_iterator; 00079 00080 /// An enumeration for describing the endianess of the target machine. 00081 enum Endianness { AnyEndianness, LittleEndian, BigEndian }; 00082 00083 /// An enumeration for describing the size of a pointer on the target machine. 00084 enum PointerSize { AnyPointerSize, Pointer32, Pointer64 }; 00085 00086 /// @} 00087 /// @name Member Variables 00088 /// @{ 00089 private: 00090 GlobalListType GlobalList; ///< The Global Variables in the module 00091 FunctionListType FunctionList; ///< The Functions in the module 00092 LibraryListType LibraryList; ///< The Libraries needed by the module 00093 std::string GlobalScopeAsm; ///< Inline Asm at global scope. 00094 SymbolTable *SymTab; ///< Symbol Table for the module 00095 std::string ModuleID; ///< Human readable identifier for the module 00096 std::string TargetTriple; ///< Platform target triple Module compiled on 00097 std::string DataLayout; ///< Target data description 00098 00099 friend class Constant; 00100 00101 /// @} 00102 /// @name Constructors 00103 /// @{ 00104 public: 00105 /// The Module constructor. Note that there is no default constructor. You 00106 /// must provide a name for the module upon construction. 00107 Module(const std::string &ModuleID); 00108 /// The module destructor. This will dropAllReferences. 00109 ~Module(); 00110 00111 /// @} 00112 /// @name Module Level Accessors 00113 /// @{ 00114 public: 00115 /// Get the module identifier which is, essentially, the name of the module. 00116 /// @returns the module identifier as a string 00117 const std::string &getModuleIdentifier() const { return ModuleID; } 00118 00119 /// Get the target triple which is a string describing the target host. 00120 /// @returns a string containing the target triple. 00121 const std::string &getTargetTriple() const { return TargetTriple; } 00122 00123 /// Get the target endian information. 00124 /// @returns Endianess - an enumeration for the endianess of the target 00125 Endianness getEndianness() const; 00126 00127 /// Get the target pointer size. 00128 /// @returns PointerSize - an enumeration for the size of the target's pointer 00129 PointerSize getPointerSize() const; 00130 00131 /// Get any module-scope inline assembly blocks. 00132 /// @returns a string containing the module-scope inline assembly blocks. 00133 const std::string &getModuleInlineAsm() const { return GlobalScopeAsm; } 00134 /// @} 00135 /// @name Module Level Mutators 00136 /// @{ 00137 public: 00138 00139 /// Set the module identifier. 00140 void setModuleIdentifier(const std::string &ID) { ModuleID = ID; } 00141 00142 /// Set the target triple. 00143 void setTargetTriple(const std::string &T) { TargetTriple = T; } 00144 00145 /// Set the target endian information. 00146 void setEndianness(Endianness E); 00147 00148 /// Set the target pointer size. 00149 void setPointerSize(PointerSize PS); 00150 00151 /// Set the module-scope inline assembly blocks. 00152 void setModuleInlineAsm(const std::string &Asm) { GlobalScopeAsm = Asm; } 00153 00154 /// @} 00155 /// @name Function Accessors 00156 /// @{ 00157 public: 00158 /// getOrInsertFunction - Look up the specified function in the module symbol 00159 /// table. If it does not exist, add a prototype for the function and return 00160 /// it. 00161 Function *getOrInsertFunction(const std::string &Name, const FunctionType *T); 00162 00163 /// getOrInsertFunction - Look up the specified function in the module symbol 00164 /// table. If it does not exist, add a prototype for the function and return 00165 /// it. This version of the method takes a null terminated list of function 00166 /// arguments, which makes it easier for clients to use. 00167 Function *getOrInsertFunction(const std::string &Name, const Type *RetTy,...) 00168 END_WITH_NULL; 00169 00170 /// getFunction - Look up the specified function in the module symbol table. 00171 /// If it does not exist, return null. 00172 Function *getFunction(const std::string &Name, const FunctionType *Ty); 00173 00174 /// getMainFunction - This function looks up main efficiently. This is such a 00175 /// common case, that it is a method in Module. If main cannot be found, a 00176 /// null pointer is returned. 00177 Function *getMainFunction(); 00178 00179 /// getNamedFunction - Return the first function in the module with the 00180 /// specified name, of arbitrary type. This method returns null if a function 00181 /// with the specified name is not found. 00182 Function *getNamedFunction(const std::string &Name) const; 00183 00184 /// @} 00185 /// @name Global Variable Accessors 00186 /// @{ 00187 public: 00188 /// getGlobalVariable - Look up the specified global variable in the module 00189 /// symbol table. If it does not exist, return null. The type argument 00190 /// should be the underlying type of the global, i.e., it should not have 00191 /// the top-level PointerType, which represents the address of the global. 00192 /// If AllowInternal is set to true, this function will return types that 00193 /// have InternalLinkage. By default, these types are not returned. 00194 GlobalVariable *getGlobalVariable(const std::string &Name, const Type *Ty, 00195 bool AllowInternal = false); 00196 00197 /// getNamedGlobal - Return the first global variable in the module with the 00198 /// specified name, of arbitrary type. This method returns null if a global 00199 /// with the specified name is not found. 00200 GlobalVariable *getNamedGlobal(const std::string &Name) const; 00201 00202 /// @} 00203 /// @name Type Accessors 00204 /// @{ 00205 public: 00206 /// addTypeName - Insert an entry in the symbol table mapping Str to Type. If 00207 /// there is already an entry for this name, true is returned and the symbol 00208 /// table is not modified. 00209 bool addTypeName(const std::string &Name, const Type *Ty); 00210 00211 /// getTypeName - If there is at least one entry in the symbol table for the 00212 /// specified type, return it. 00213 std::string getTypeName(const Type *Ty) const; 00214 00215 /// getTypeByName - Return the type with the specified name in this module, or 00216 /// null if there is none by that name. 00217 const Type *getTypeByName(const std::string &Name) const; 00218 00219 /// @} 00220 /// @name Direct access to the globals list, functions list, and symbol table 00221 /// @{ 00222 public: 00223 /// Get the Module's list of global variables (constant). 00224 const GlobalListType &getGlobalList() const { return GlobalList; } 00225 /// Get the Module's list of global variables. 00226 GlobalListType &getGlobalList() { return GlobalList; } 00227 /// Get the Module's list of functions (constant). 00228 const FunctionListType &getFunctionList() const { return FunctionList; } 00229 /// Get the Module's list of functions. 00230 FunctionListType &getFunctionList() { return FunctionList; } 00231 /// Get the symbol table of global variable and function identifiers 00232 const SymbolTable &getSymbolTable() const { return *SymTab; } 00233 /// Get the Module's symbol table of global variable and function identifiers. 00234 SymbolTable &getSymbolTable() { return *SymTab; } 00235 00236 /// @} 00237 /// @name Global Variable Iteration 00238 /// @{ 00239 public: 00240 /// Get an iterator to the first global variable 00241 global_iterator global_begin() { return GlobalList.begin(); } 00242 /// Get a constant iterator to the first global variable 00243 const_global_iterator global_begin() const { return GlobalList.begin(); } 00244 /// Get an iterator to the last global variable 00245 global_iterator global_end () { return GlobalList.end(); } 00246 /// Get a constant iterator to the last global variable 00247 const_global_iterator global_end () const { return GlobalList.end(); } 00248 /// Determine if the list of globals is empty. 00249 bool global_empty() const { return GlobalList.empty(); } 00250 00251 /// @} 00252 /// @name Function Iteration 00253 /// @{ 00254 public: 00255 /// Get an iterator to the first function. 00256 iterator begin() { return FunctionList.begin(); } 00257 /// Get a constant iterator to the first function. 00258 const_iterator begin() const { return FunctionList.begin(); } 00259 /// Get an iterator to the last function. 00260 iterator end () { return FunctionList.end(); } 00261 /// Get a constant iterator to the last function. 00262 const_iterator end () const { return FunctionList.end(); } 00263 /// Determine how many functions are in the Module's list of functions. 00264 size_t size() const { return FunctionList.size(); } 00265 /// Determine if the list of functions is empty. 00266 bool empty() const { return FunctionList.empty(); } 00267 00268 /// @} 00269 /// @name Dependent Library Iteration 00270 /// @{ 00271 public: 00272 /// @brief Get a constant iterator to beginning of dependent library list. 00273 inline lib_iterator lib_begin() const { return LibraryList.begin(); } 00274 /// @brief Get a constant iterator to end of dependent library list. 00275 inline lib_iterator lib_end() const { return LibraryList.end(); } 00276 /// @brief Returns the number of items in the list of libraries. 00277 inline size_t lib_size() const { return LibraryList.size(); } 00278 /// @brief Add a library to the list of dependent libraries 00279 inline void addLibrary(const std::string& Lib){ LibraryList.insert(Lib); } 00280 /// @brief Remove a library from the list of dependent libraries 00281 inline void removeLibrary(const std::string& Lib) { LibraryList.remove(Lib); } 00282 /// @brief Get all the libraries 00283 inline const LibraryListType& getLibraries() const { return LibraryList; } 00284 00285 /// @} 00286 /// @name Utility functions for printing and dumping Module objects 00287 /// @{ 00288 public: 00289 /// Print the module to an output stream 00290 void print(std::ostream &OS) const { print(OS, 0); } 00291 /// Print the module to an output stream with AssemblyAnnotationWriter. 00292 void print(std::ostream &OS, AssemblyAnnotationWriter *AAW) const; 00293 /// Dump the module to std::cerr (for debugging). 00294 void dump() const; 00295 /// This function causes all the subinstructions to "let go" of all references 00296 /// that they are maintaining. This allows one to 'delete' a whole class at 00297 /// a time, even though there may be circular references... first all 00298 /// references are dropped, and all use counts go to zero. Then everything 00299 /// is delete'd for real. Note that no operations are valid on an object 00300 /// that has "dropped all references", except operator delete. 00301 void dropAllReferences(); 00302 /// @} 00303 }; 00304 00305 /// An iostream inserter for modules. 00306 inline std::ostream &operator<<(std::ostream &O, const Module &M) { 00307 M.print(O); 00308 return O; 00309 } 00310 00311 } // End llvm namespace 00312 00313 #endif