contrib/llvm/include/llvm/IR/Module.h

   1 //===- llvm/Module.h - C++ class to represent a VM module -------*- 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 /// @file
  11 /// Module.h This file contains the declarations for the Module class.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_IR_MODULE_H
  16 #define LLVM_IR_MODULE_H
  17
  18 #include "llvm-c/Types.h"
  19 #include "llvm/ADT/STLExtras.h"
  20 #include "llvm/ADT/StringMap.h"
  21 #include "llvm/ADT/StringRef.h"
  22 #include "llvm/ADT/iterator_range.h"
  23 #include "llvm/IR/Attributes.h"
  24 #include "llvm/IR/Comdat.h"
  25 #include "llvm/IR/DataLayout.h"
  26 #include "llvm/IR/Function.h"
  27 #include "llvm/IR/GlobalAlias.h"
  28 #include "llvm/IR/GlobalIFunc.h"
  29 #include "llvm/IR/GlobalVariable.h"
  30 #include "llvm/IR/Metadata.h"
  31 #include "llvm/IR/SymbolTableListTraits.h"
  32 #include "llvm/Support/CBindingWrapping.h"
  33 #include "llvm/Support/CodeGen.h"
  34 #include <cstddef>
  35 #include <cstdint>
  36 #include <iterator>
  37 #include <memory>
  38 #include <string>
  39 #include <vector>
  40
  41 namespace llvm {
  42
  43 class Error;
  44 class FunctionType;
  45 class GVMaterializer;
  46 class LLVMContext;
  47 class MemoryBuffer;
  48 class RandomNumberGenerator;
  49 template <class PtrType> class SmallPtrSetImpl;
  50 class StructType;
  51
  52 /// A Module instance is used to store all the information related to an
  53 /// LLVM module. Modules are the top level container of all other LLVM
  54 /// Intermediate Representation (IR) objects. Each module directly contains a
  55 /// list of globals variables, a list of functions, a list of libraries (or
  56 /// other modules) this module depends on, a symbol table, and various data
  57 /// about the target's characteristics.
  58 ///
  59 /// A module maintains a GlobalValRefMap object that is used to hold all
  60 /// constant references to global variables in the module.  When a global
  61 /// variable is destroyed, it should have no entries in the GlobalValueRefMap.
  62 /// The main container class for the LLVM Intermediate Representation.
  63 class Module {
  64 /// @name Types And Enumerations
  65 /// @{
  66 public:
  67   /// The type for the list of global variables.
  68   using GlobalListType = SymbolTableList<GlobalVariable>;
  69   /// The type for the list of functions.
  70   using FunctionListType = SymbolTableList<Function>;
  71   /// The type for the list of aliases.
  72   using AliasListType = SymbolTableList<GlobalAlias>;
  73   /// The type for the list of ifuncs.
  74   using IFuncListType = SymbolTableList<GlobalIFunc>;
  75   /// The type for the list of named metadata.
  76   using NamedMDListType = ilist<NamedMDNode>;
  77   /// The type of the comdat "symbol" table.
  78   using ComdatSymTabType = StringMap<Comdat>;
  79
  80   /// The Global Variable iterator.
  81   using global_iterator = GlobalListType::iterator;
  82   /// The Global Variable constant iterator.
  83   using const_global_iterator = GlobalListType::const_iterator;
  84
  85   /// The Function iterators.
  86   using iterator = FunctionListType::iterator;
  87   /// The Function constant iterator
  88   using const_iterator = FunctionListType::const_iterator;
  89
  90   /// The Function reverse iterator.
  91   using reverse_iterator = FunctionListType::reverse_iterator;
  92   /// The Function constant reverse iterator.
  93   using const_reverse_iterator = FunctionListType::const_reverse_iterator;
  94
  95   /// The Global Alias iterators.
  96   using alias_iterator = AliasListType::iterator;
  97   /// The Global Alias constant iterator
  98   using const_alias_iterator = AliasListType::const_iterator;
  99
 100   /// The Global IFunc iterators.
 101   using ifunc_iterator = IFuncListType::iterator;
 102   /// The Global IFunc constant iterator
 103   using const_ifunc_iterator = IFuncListType::const_iterator;
 104
 105   /// The named metadata iterators.
 106   using named_metadata_iterator = NamedMDListType::iterator;
 107   /// The named metadata constant iterators.
 108   using const_named_metadata_iterator = NamedMDListType::const_iterator;
 109
 110   /// This enumeration defines the supported behaviors of module flags.
 111   enum ModFlagBehavior {
 112     /// Emits an error if two values disagree, otherwise the resulting value is
 113     /// that of the operands.
 114     Error = 1,
 115
 116     /// Emits a warning if two values disagree. The result value will be the
 117     /// operand for the flag from the first module being linked.
 118     Warning = 2,
 119
 120     /// Adds a requirement that another module flag be present and have a
 121     /// specified value after linking is performed. The value must be a metadata
 122     /// pair, where the first element of the pair is the ID of the module flag
 123     /// to be restricted, and the second element of the pair is the value the
 124     /// module flag should be restricted to. This behavior can be used to
 125     /// restrict the allowable results (via triggering of an error) of linking
 126     /// IDs with the **Override** behavior.
 127     Require = 3,
 128
 129     /// Uses the specified value, regardless of the behavior or value of the
 130     /// other module. If both modules specify **Override**, but the values
 131     /// differ, an error will be emitted.
 132     Override = 4,
 133
 134     /// Appends the two values, which are required to be metadata nodes.
 135     Append = 5,
 136
 137     /// Appends the two values, which are required to be metadata
 138     /// nodes. However, duplicate entries in the second list are dropped
 139     /// during the append operation.
 140     AppendUnique = 6,
 141
 142     /// Takes the max of the two values, which are required to be integers.
 143     Max = 7,
 144
 145     // Markers:
 146     ModFlagBehaviorFirstVal = Error,
 147     ModFlagBehaviorLastVal = Max
 148   };
 149
 150   /// Checks if Metadata represents a valid ModFlagBehavior, and stores the
 151   /// converted result in MFB.
 152   static bool isValidModFlagBehavior(Metadata *MD, ModFlagBehavior &MFB);
 153
 154   struct ModuleFlagEntry {
 155     ModFlagBehavior Behavior;
 156     MDString *Key;
 157     Metadata *Val;
 158
 159     ModuleFlagEntry(ModFlagBehavior B, MDString *K, Metadata *V)
 160         : Behavior(B), Key(K), Val(V) {}
 161   };
 162
 163 /// @}
 164 /// @name Member Variables
 165 /// @{
 166 private:
 167   LLVMContext &Context;           ///< The LLVMContext from which types and
 168                                   ///< constants are allocated.
 169   GlobalListType GlobalList;      ///< The Global Variables in the module
 170   FunctionListType FunctionList;  ///< The Functions in the module
 171   AliasListType AliasList;        ///< The Aliases in the module
 172   IFuncListType IFuncList;        ///< The IFuncs in the module
 173   NamedMDListType NamedMDList;    ///< The named metadata in the module
 174   std::string GlobalScopeAsm;     ///< Inline Asm at global scope.
 175   ValueSymbolTable *ValSymTab;    ///< Symbol table for values
 176   ComdatSymTabType ComdatSymTab;  ///< Symbol table for COMDATs
 177   std::unique_ptr<MemoryBuffer>
 178   OwnedMemoryBuffer;              ///< Memory buffer directly owned by this
 179                                   ///< module, for legacy clients only.
 180   std::unique_ptr<GVMaterializer>
 181   Materializer;                   ///< Used to materialize GlobalValues
 182   std::string ModuleID;           ///< Human readable identifier for the module
 183   std::string SourceFileName;     ///< Original source file name for module,
 184                                   ///< recorded in bitcode.
 185   std::string TargetTriple;       ///< Platform target triple Module compiled on
 186                                   ///< Format: (arch)(sub)-(vendor)-(sys0-(abi)
 187   void *NamedMDSymTab;            ///< NamedMDNode names.
 188   DataLayout DL;                  ///< DataLayout associated with the module
 189
 190   friend class Constant;
 191
 192 /// @}
 193 /// @name Constructors
 194 /// @{
 195 public:
 196   /// The Module constructor. Note that there is no default constructor. You
 197   /// must provide a name for the module upon construction.
 198   explicit Module(StringRef ModuleID, LLVMContext& C);
 199   /// The module destructor. This will dropAllReferences.
 200   ~Module();
 201
 202 /// @}
 203 /// @name Module Level Accessors
 204 /// @{
 205
 206   /// Get the module identifier which is, essentially, the name of the module.
 207   /// @returns the module identifier as a string
 208   const std::string &getModuleIdentifier() const { return ModuleID; }
 209
 210   /// Returns the number of non-debug IR instructions in the module.
 211   /// This is equivalent to the sum of the IR instruction counts of each
 212   /// function contained in the module.
 213   unsigned getInstructionCount();
 214
 215   /// Get the module's original source file name. When compiling from
 216   /// bitcode, this is taken from a bitcode record where it was recorded.
 217   /// For other compiles it is the same as the ModuleID, which would
 218   /// contain the source file name.
 219   const std::string &getSourceFileName() const { return SourceFileName; }
 220
 221   /// Get a short "name" for the module.
 222   ///
 223   /// This is useful for debugging or logging. It is essentially a convenience
 224   /// wrapper around getModuleIdentifier().
 225   StringRef getName() const { return ModuleID; }
 226
 227   /// Get the data layout string for the module's target platform. This is
 228   /// equivalent to getDataLayout()->getStringRepresentation().
 229   const std::string &getDataLayoutStr() const {
 230     return DL.getStringRepresentation();
 231   }
 232
 233   /// Get the data layout for the module's target platform.
 234   const DataLayout &getDataLayout() const;
 235
 236   /// Get the target triple which is a string describing the target host.
 237   /// @returns a string containing the target triple.
 238   const std::string &getTargetTriple() const { return TargetTriple; }
 239
 240   /// Get the global data context.
 241   /// @returns LLVMContext - a container for LLVM's global information
 242   LLVMContext &getContext() const { return Context; }
 243
 244   /// Get any module-scope inline assembly blocks.
 245   /// @returns a string containing the module-scope inline assembly blocks.
 246   const std::string &getModuleInlineAsm() const { return GlobalScopeAsm; }
 247
 248   /// Get a RandomNumberGenerator salted for use with this module. The
 249   /// RNG can be seeded via -rng-seed=<uint64> and is salted with the
 250   /// ModuleID and the provided pass salt. The returned RNG should not
 251   /// be shared across threads or passes.
 252   ///
 253   /// A unique RNG per pass ensures a reproducible random stream even
 254   /// when other randomness consuming passes are added or removed. In
 255   /// addition, the random stream will be reproducible across LLVM
 256   /// versions when the pass does not change.
 257   std::unique_ptr<RandomNumberGenerator> createRNG(const Pass* P) const;
 258
 259   /// Return true if size-info optimization remark is enabled, false
 260   /// otherwise.
 261   bool shouldEmitInstrCountChangedRemark() {
 262     return getContext().getDiagHandlerPtr()->isAnalysisRemarkEnabled(
 263         "size-info");
 264   }
 265
 266   /// @}
 267   /// @name Module Level Mutators
 268   /// @{
 269
 270   /// Set the module identifier.
 271   void setModuleIdentifier(StringRef ID) { ModuleID = ID; }
 272
 273   /// Set the module's original source file name.
 274   void setSourceFileName(StringRef Name) { SourceFileName = Name; }
 275
 276   /// Set the data layout
 277   void setDataLayout(StringRef Desc);
 278   void setDataLayout(const DataLayout &Other);
 279
 280   /// Set the target triple.
 281   void setTargetTriple(StringRef T) { TargetTriple = T; }
 282
 283   /// Set the module-scope inline assembly blocks.
 284   /// A trailing newline is added if the input doesn't have one.
 285   void setModuleInlineAsm(StringRef Asm) {
 286     GlobalScopeAsm = Asm;
 287     if (!GlobalScopeAsm.empty() && GlobalScopeAsm.back() != '\n')
 288       GlobalScopeAsm += '\n';
 289   }
 290
 291   /// Append to the module-scope inline assembly blocks.
 292   /// A trailing newline is added if the input doesn't have one.
 293   void appendModuleInlineAsm(StringRef Asm) {
 294     GlobalScopeAsm += Asm;
 295     if (!GlobalScopeAsm.empty() && GlobalScopeAsm.back() != '\n')
 296       GlobalScopeAsm += '\n';
 297   }
 298
 299 /// @}
 300 /// @name Generic Value Accessors
 301 /// @{
 302
 303   /// Return the global value in the module with the specified name, of
 304   /// arbitrary type. This method returns null if a global with the specified
 305   /// name is not found.
 306   GlobalValue *getNamedValue(StringRef Name) const;
 307
 308   /// Return a unique non-zero ID for the specified metadata kind. This ID is
 309   /// uniqued across modules in the current LLVMContext.
 310   unsigned getMDKindID(StringRef Name) const;
 311
 312   /// Populate client supplied SmallVector with the name for custom metadata IDs
 313   /// registered in this LLVMContext.
 314   void getMDKindNames(SmallVectorImpl<StringRef> &Result) const;
 315
 316   /// Populate client supplied SmallVector with the bundle tags registered in
 317   /// this LLVMContext.  The bundle tags are ordered by increasing bundle IDs.
 318   /// \see LLVMContext::getOperandBundleTagID
 319   void getOperandBundleTags(SmallVectorImpl<StringRef> &Result) const;
 320
 321   /// Return the type with the specified name, or null if there is none by that
 322   /// name.
 323   StructType *getTypeByName(StringRef Name) const;
 324
 325   std::vector<StructType *> getIdentifiedStructTypes() const;
 326
 327 /// @}
 328 /// @name Function Accessors
 329 /// @{
 330
 331   /// Look up the specified function in the module symbol table. Four
 332   /// possibilities:
 333   ///   1. If it does not exist, add a prototype for the function and return it.
 334   ///   2. If it exists, and has a local linkage, the existing function is
 335   ///      renamed and a new one is inserted.
 336   ///   3. Otherwise, if the existing function has the correct prototype, return
 337   ///      the existing function.
 338   ///   4. Finally, the function exists but has the wrong prototype: return the
 339   ///      function with a constantexpr cast to the right prototype.
 340   Constant *getOrInsertFunction(StringRef Name, FunctionType *T,
 341                                 AttributeList AttributeList);
 342
 343   Constant *getOrInsertFunction(StringRef Name, FunctionType *T);
 344
 345   /// Look up the specified function in the module symbol table. If it does not
 346   /// exist, add a prototype for the function and return it. This function
 347   /// guarantees to return a constant of pointer to the specified function type
 348   /// or a ConstantExpr BitCast of that type if the named function has a
 349   /// different type. This version of the method takes a list of
 350   /// function arguments, which makes it easier for clients to use.
 351   template<typename... ArgsTy>
 352   Constant *getOrInsertFunction(StringRef Name,
 353                                 AttributeList AttributeList,
 354                                 Type *RetTy, ArgsTy... Args)
 355   {
 356     SmallVector<Type*, sizeof...(ArgsTy)> ArgTys{Args...};
 357     return getOrInsertFunction(Name,
 358                                FunctionType::get(RetTy, ArgTys, false),
 359                                AttributeList);
 360   }
 361
 362   /// Same as above, but without the attributes.
 363   template<typename... ArgsTy>
 364   Constant *getOrInsertFunction(StringRef Name, Type *RetTy, ArgsTy... Args) {
 365     return getOrInsertFunction(Name, AttributeList{}, RetTy, Args...);
 366   }
 367
 368   /// Look up the specified function in the module symbol table. If it does not
 369   /// exist, return null.
 370   Function *getFunction(StringRef Name) const;
 371
 372 /// @}
 373 /// @name Global Variable Accessors
 374 /// @{
 375
 376   /// Look up the specified global variable in the module symbol table. If it
 377   /// does not exist, return null. If AllowInternal is set to true, this
 378   /// function will return types that have InternalLinkage. By default, these
 379   /// types are not returned.
 380   GlobalVariable *getGlobalVariable(StringRef Name) const {
 381     return getGlobalVariable(Name, false);
 382   }
 383
 384   GlobalVariable *getGlobalVariable(StringRef Name, bool AllowInternal) const;
 385
 386   GlobalVariable *getGlobalVariable(StringRef Name,
 387                                     bool AllowInternal = false) {
 388     return static_cast<const Module *>(this)->getGlobalVariable(Name,
 389                                                                 AllowInternal);
 390   }
 391
 392   /// Return the global variable in the module with the specified name, of
 393   /// arbitrary type. This method returns null if a global with the specified
 394   /// name is not found.
 395   const GlobalVariable *getNamedGlobal(StringRef Name) const {
 396     return getGlobalVariable(Name, true);
 397   }
 398   GlobalVariable *getNamedGlobal(StringRef Name) {
 399     return const_cast<GlobalVariable *>(
 400                        static_cast<const Module *>(this)->getNamedGlobal(Name));
 401   }
 402
 403   /// Look up the specified global in the module symbol table.
 404   ///   1. If it does not exist, add a declaration of the global and return it.
 405   ///   2. Else, the global exists but has the wrong type: return the function
 406   ///      with a constantexpr cast to the right type.
 407   ///   3. Finally, if the existing global is the correct declaration, return
 408   ///      the existing global.
 409   Constant *getOrInsertGlobal(StringRef Name, Type *Ty);
 410
 411 /// @}
 412 /// @name Global Alias Accessors
 413 /// @{
 414
 415   /// Return the global alias in the module with the specified name, of
 416   /// arbitrary type. This method returns null if a global with the specified
 417   /// name is not found.
 418   GlobalAlias *getNamedAlias(StringRef Name) const;
 419
 420 /// @}
 421 /// @name Global IFunc Accessors
 422 /// @{
 423
 424   /// Return the global ifunc in the module with the specified name, of
 425   /// arbitrary type. This method returns null if a global with the specified
 426   /// name is not found.
 427   GlobalIFunc *getNamedIFunc(StringRef Name) const;
 428
 429 /// @}
 430 /// @name Named Metadata Accessors
 431 /// @{
 432
 433   /// Return the first NamedMDNode in the module with the specified name. This
 434   /// method returns null if a NamedMDNode with the specified name is not found.
 435   NamedMDNode *getNamedMetadata(const Twine &Name) const;
 436
 437   /// Return the named MDNode in the module with the specified name. This method
 438   /// returns a new NamedMDNode if a NamedMDNode with the specified name is not
 439   /// found.
 440   NamedMDNode *getOrInsertNamedMetadata(StringRef Name);
 441
 442   /// Remove the given NamedMDNode from this module and delete it.
 443   void eraseNamedMetadata(NamedMDNode *NMD);
 444
 445 /// @}
 446 /// @name Comdat Accessors
 447 /// @{
 448
 449   /// Return the Comdat in the module with the specified name. It is created
 450   /// if it didn't already exist.
 451   Comdat *getOrInsertComdat(StringRef Name);
 452
 453 /// @}
 454 /// @name Module Flags Accessors
 455 /// @{
 456
 457   /// Returns the module flags in the provided vector.
 458   void getModuleFlagsMetadata(SmallVectorImpl<ModuleFlagEntry> &Flags) const;
 459
 460   /// Return the corresponding value if Key appears in module flags, otherwise
 461   /// return null.
 462   Metadata *getModuleFlag(StringRef Key) const;
 463
 464   /// Returns the NamedMDNode in the module that represents module-level flags.
 465   /// This method returns null if there are no module-level flags.
 466   NamedMDNode *getModuleFlagsMetadata() const;
 467
 468   /// Returns the NamedMDNode in the module that represents module-level flags.
 469   /// If module-level flags aren't found, it creates the named metadata that
 470   /// contains them.
 471   NamedMDNode *getOrInsertModuleFlagsMetadata();
 472
 473   /// Add a module-level flag to the module-level flags metadata. It will create
 474   /// the module-level flags named metadata if it doesn't already exist.
 475   void addModuleFlag(ModFlagBehavior Behavior, StringRef Key, Metadata *Val);
 476   void addModuleFlag(ModFlagBehavior Behavior, StringRef Key, Constant *Val);
 477   void addModuleFlag(ModFlagBehavior Behavior, StringRef Key, uint32_t Val);
 478   void addModuleFlag(MDNode *Node);
 479
 480 /// @}
 481 /// @name Materialization
 482 /// @{
 483
 484   /// Sets the GVMaterializer to GVM. This module must not yet have a
 485   /// Materializer. To reset the materializer for a module that already has one,
 486   /// call materializeAll first. Destroying this module will destroy
 487   /// its materializer without materializing any more GlobalValues. Without
 488   /// destroying the Module, there is no way to detach or destroy a materializer
 489   /// without materializing all the GVs it controls, to avoid leaving orphan
 490   /// unmaterialized GVs.
 491   void setMaterializer(GVMaterializer *GVM);
 492   /// Retrieves the GVMaterializer, if any, for this Module.
 493   GVMaterializer *getMaterializer() const { return Materializer.get(); }
 494   bool isMaterialized() const { return !getMaterializer(); }
 495
 496   /// Make sure the GlobalValue is fully read.
 497   llvm::Error materialize(GlobalValue *GV);
 498
 499   /// Make sure all GlobalValues in this Module are fully read and clear the
 500   /// Materializer.
 501   llvm::Error materializeAll();
 502
 503   llvm::Error materializeMetadata();
 504
 505 /// @}
 506 /// @name Direct access to the globals list, functions list, and symbol table
 507 /// @{
 508
 509   /// Get the Module's list of global variables (constant).
 510   const GlobalListType   &getGlobalList() const       { return GlobalList; }
 511   /// Get the Module's list of global variables.
 512   GlobalListType         &getGlobalList()             { return GlobalList; }
 513
 514   static GlobalListType Module::*getSublistAccess(GlobalVariable*) {
 515     return &Module::GlobalList;
 516   }
 517
 518   /// Get the Module's list of functions (constant).
 519   const FunctionListType &getFunctionList() const     { return FunctionList; }
 520   /// Get the Module's list of functions.
 521   FunctionListType       &getFunctionList()           { return FunctionList; }
 522   static FunctionListType Module::*getSublistAccess(Function*) {
 523     return &Module::FunctionList;
 524   }
 525
 526   /// Get the Module's list of aliases (constant).
 527   const AliasListType    &getAliasList() const        { return AliasList; }
 528   /// Get the Module's list of aliases.
 529   AliasListType          &getAliasList()              { return AliasList; }
 530
 531   static AliasListType Module::*getSublistAccess(GlobalAlias*) {
 532     return &Module::AliasList;
 533   }
 534
 535   /// Get the Module's list of ifuncs (constant).
 536   const IFuncListType    &getIFuncList() const        { return IFuncList; }
 537   /// Get the Module's list of ifuncs.
 538   IFuncListType          &getIFuncList()              { return IFuncList; }
 539
 540   static IFuncListType Module::*getSublistAccess(GlobalIFunc*) {
 541     return &Module::IFuncList;
 542   }
 543
 544   /// Get the Module's list of named metadata (constant).
 545   const NamedMDListType  &getNamedMDList() const      { return NamedMDList; }
 546   /// Get the Module's list of named metadata.
 547   NamedMDListType        &getNamedMDList()            { return NamedMDList; }
 548
 549   static NamedMDListType Module::*getSublistAccess(NamedMDNode*) {
 550     return &Module::NamedMDList;
 551   }
 552
 553   /// Get the symbol table of global variable and function identifiers
 554   const ValueSymbolTable &getValueSymbolTable() const { return *ValSymTab; }
 555   /// Get the Module's symbol table of global variable and function identifiers.
 556   ValueSymbolTable       &getValueSymbolTable()       { return *ValSymTab; }
 557
 558   /// Get the Module's symbol table for COMDATs (constant).
 559   const ComdatSymTabType &getComdatSymbolTable() const { return ComdatSymTab; }
 560   /// Get the Module's symbol table for COMDATs.
 561   ComdatSymTabType &getComdatSymbolTable() { return ComdatSymTab; }
 562
 563 /// @}
 564 /// @name Global Variable Iteration
 565 /// @{
 566
 567   global_iterator       global_begin()       { return GlobalList.begin(); }
 568   const_global_iterator global_begin() const { return GlobalList.begin(); }
 569   global_iterator       global_end  ()       { return GlobalList.end(); }
 570   const_global_iterator global_end  () const { return GlobalList.end(); }
 571   bool                  global_empty() const { return GlobalList.empty(); }
 572
 573   iterator_range<global_iterator> globals() {
 574     return make_range(global_begin(), global_end());
 575   }
 576   iterator_range<const_global_iterator> globals() const {
 577     return make_range(global_begin(), global_end());
 578   }
 579
 580 /// @}
 581 /// @name Function Iteration
 582 /// @{
 583
 584   iterator                begin()       { return FunctionList.begin(); }
 585   const_iterator          begin() const { return FunctionList.begin(); }
 586   iterator                end  ()       { return FunctionList.end();   }
 587   const_iterator          end  () const { return FunctionList.end();   }
 588   reverse_iterator        rbegin()      { return FunctionList.rbegin(); }
 589   const_reverse_iterator  rbegin() const{ return FunctionList.rbegin(); }
 590   reverse_iterator        rend()        { return FunctionList.rend(); }
 591   const_reverse_iterator  rend() const  { return FunctionList.rend(); }
 592   size_t                  size() const  { return FunctionList.size(); }
 593   bool                    empty() const { return FunctionList.empty(); }
 594
 595   iterator_range<iterator> functions() {
 596     return make_range(begin(), end());
 597   }
 598   iterator_range<const_iterator> functions() const {
 599     return make_range(begin(), end());
 600   }
 601
 602 /// @}
 603 /// @name Alias Iteration
 604 /// @{
 605
 606   alias_iterator       alias_begin()            { return AliasList.begin(); }
 607   const_alias_iterator alias_begin() const      { return AliasList.begin(); }
 608   alias_iterator       alias_end  ()            { return AliasList.end();   }
 609   const_alias_iterator alias_end  () const      { return AliasList.end();   }
 610   size_t               alias_size () const      { return AliasList.size();  }
 611   bool                 alias_empty() const      { return AliasList.empty(); }
 612
 613   iterator_range<alias_iterator> aliases() {
 614     return make_range(alias_begin(), alias_end());
 615   }
 616   iterator_range<const_alias_iterator> aliases() const {
 617     return make_range(alias_begin(), alias_end());
 618   }
 619
 620 /// @}
 621 /// @name IFunc Iteration
 622 /// @{
 623
 624   ifunc_iterator       ifunc_begin()            { return IFuncList.begin(); }
 625   const_ifunc_iterator ifunc_begin() const      { return IFuncList.begin(); }
 626   ifunc_iterator       ifunc_end  ()            { return IFuncList.end();   }
 627   const_ifunc_iterator ifunc_end  () const      { return IFuncList.end();   }
 628   size_t               ifunc_size () const      { return IFuncList.size();  }
 629   bool                 ifunc_empty() const      { return IFuncList.empty(); }
 630
 631   iterator_range<ifunc_iterator> ifuncs() {
 632     return make_range(ifunc_begin(), ifunc_end());
 633   }
 634   iterator_range<const_ifunc_iterator> ifuncs() const {
 635     return make_range(ifunc_begin(), ifunc_end());
 636   }
 637
 638   /// @}
 639   /// @name Convenience iterators
 640   /// @{
 641
 642   using global_object_iterator =
 643       concat_iterator<GlobalObject, iterator, global_iterator>;
 644   using const_global_object_iterator =
 645       concat_iterator<const GlobalObject, const_iterator,
 646                       const_global_iterator>;
 647
 648   iterator_range<global_object_iterator> global_objects() {
 649     return concat<GlobalObject>(functions(), globals());
 650   }
 651   iterator_range<const_global_object_iterator> global_objects() const {
 652     return concat<const GlobalObject>(functions(), globals());
 653   }
 654
 655   global_object_iterator global_object_begin() {
 656     return global_objects().begin();
 657   }
 658   global_object_iterator global_object_end() { return global_objects().end(); }
 659
 660   const_global_object_iterator global_object_begin() const {
 661     return global_objects().begin();
 662   }
 663   const_global_object_iterator global_object_end() const {
 664     return global_objects().end();
 665   }
 666
 667   using global_value_iterator =
 668       concat_iterator<GlobalValue, iterator, global_iterator, alias_iterator,
 669                       ifunc_iterator>;
 670   using const_global_value_iterator =
 671       concat_iterator<const GlobalValue, const_iterator, const_global_iterator,
 672                       const_alias_iterator, const_ifunc_iterator>;
 673
 674   iterator_range<global_value_iterator> global_values() {
 675     return concat<GlobalValue>(functions(), globals(), aliases(), ifuncs());
 676   }
 677   iterator_range<const_global_value_iterator> global_values() const {
 678     return concat<const GlobalValue>(functions(), globals(), aliases(),
 679                                      ifuncs());
 680   }
 681
 682   global_value_iterator global_value_begin() { return global_values().begin(); }
 683   global_value_iterator global_value_end() { return global_values().end(); }
 684
 685   const_global_value_iterator global_value_begin() const {
 686     return global_values().begin();
 687   }
 688   const_global_value_iterator global_value_end() const {
 689     return global_values().end();
 690   }
 691
 692   /// @}
 693   /// @name Named Metadata Iteration
 694   /// @{
 695
 696   named_metadata_iterator named_metadata_begin() { return NamedMDList.begin(); }
 697   const_named_metadata_iterator named_metadata_begin() const {
 698     return NamedMDList.begin();
 699   }
 700
 701   named_metadata_iterator named_metadata_end() { return NamedMDList.end(); }
 702   const_named_metadata_iterator named_metadata_end() const {
 703     return NamedMDList.end();
 704   }
 705
 706   size_t named_metadata_size() const { return NamedMDList.size();  }
 707   bool named_metadata_empty() const { return NamedMDList.empty(); }
 708
 709   iterator_range<named_metadata_iterator> named_metadata() {
 710     return make_range(named_metadata_begin(), named_metadata_end());
 711   }
 712   iterator_range<const_named_metadata_iterator> named_metadata() const {
 713     return make_range(named_metadata_begin(), named_metadata_end());
 714   }
 715
 716   /// An iterator for DICompileUnits that skips those marked NoDebug.
 717   class debug_compile_units_iterator
 718       : public std::iterator<std::input_iterator_tag, DICompileUnit *> {
 719     NamedMDNode *CUs;
 720     unsigned Idx;
 721
 722     void SkipNoDebugCUs();
 723
 724   public:
 725     explicit debug_compile_units_iterator(NamedMDNode *CUs, unsigned Idx)
 726         : CUs(CUs), Idx(Idx) {
 727       SkipNoDebugCUs();
 728     }
 729
 730     debug_compile_units_iterator &operator++() {
 731       ++Idx;
 732       SkipNoDebugCUs();
 733       return *this;
 734     }
 735
 736     debug_compile_units_iterator operator++(int) {
 737       debug_compile_units_iterator T(*this);
 738       ++Idx;
 739       return T;
 740     }
 741
 742     bool operator==(const debug_compile_units_iterator &I) const {
 743       return Idx == I.Idx;
 744     }
 745
 746     bool operator!=(const debug_compile_units_iterator &I) const {
 747       return Idx != I.Idx;
 748     }
 749
 750     DICompileUnit *operator*() const;
 751     DICompileUnit *operator->() const;
 752   };
 753
 754   debug_compile_units_iterator debug_compile_units_begin() const {
 755     auto *CUs = getNamedMetadata("llvm.dbg.cu");
 756     return debug_compile_units_iterator(CUs, 0);
 757   }
 758
 759   debug_compile_units_iterator debug_compile_units_end() const {
 760     auto *CUs = getNamedMetadata("llvm.dbg.cu");
 761     return debug_compile_units_iterator(CUs, CUs ? CUs->getNumOperands() : 0);
 762   }
 763
 764   /// Return an iterator for all DICompileUnits listed in this Module's
 765   /// llvm.dbg.cu named metadata node and aren't explicitly marked as
 766   /// NoDebug.
 767   iterator_range<debug_compile_units_iterator> debug_compile_units() const {
 768     auto *CUs = getNamedMetadata("llvm.dbg.cu");
 769     return make_range(
 770         debug_compile_units_iterator(CUs, 0),
 771         debug_compile_units_iterator(CUs, CUs ? CUs->getNumOperands() : 0));
 772   }
 773 /// @}
 774
 775   /// Destroy ConstantArrays in LLVMContext if they are not used.
 776   /// ConstantArrays constructed during linking can cause quadratic memory
 777   /// explosion. Releasing all unused constants can cause a 20% LTO compile-time
 778   /// slowdown for a large application.
 779   ///
 780   /// NOTE: Constants are currently owned by LLVMContext. This can then only
 781   /// be called where all uses of the LLVMContext are understood.
 782   void dropTriviallyDeadConstantArrays();
 783
 784 /// @name Utility functions for printing and dumping Module objects
 785 /// @{
 786
 787   /// Print the module to an output stream with an optional
 788   /// AssemblyAnnotationWriter.  If \c ShouldPreserveUseListOrder, then include
 789   /// uselistorder directives so that use-lists can be recreated when reading
 790   /// the assembly.
 791   void print(raw_ostream &OS, AssemblyAnnotationWriter *AAW,
 792              bool ShouldPreserveUseListOrder = false,
 793              bool IsForDebug = false) const;
 794
 795   /// Dump the module to stderr (for debugging).
 796   void dump() const;
 797
 798   /// This function causes all the subinstructions to "let go" of all references
 799   /// that they are maintaining.  This allows one to 'delete' a whole class at
 800   /// a time, even though there may be circular references... first all
 801   /// references are dropped, and all use counts go to zero.  Then everything
 802   /// is delete'd for real.  Note that no operations are valid on an object
 803   /// that has "dropped all references", except operator delete.
 804   void dropAllReferences();
 805
 806 /// @}
 807 /// @name Utility functions for querying Debug information.
 808 /// @{
 809
 810   /// Returns the Number of Register ParametersDwarf Version by checking
 811   /// module flags.
 812   unsigned getNumberRegisterParameters() const;
 813
 814   /// Returns the Dwarf Version by checking module flags.
 815   unsigned getDwarfVersion() const;
 816
 817   /// Returns the CodeView Version by checking module flags.
 818   /// Returns zero if not present in module.
 819   unsigned getCodeViewFlag() const;
 820
 821 /// @}
 822 /// @name Utility functions for querying and setting PIC level
 823 /// @{
 824
 825   /// Returns the PIC level (small or large model)
 826   PICLevel::Level getPICLevel() const;
 827
 828   /// Set the PIC level (small or large model)
 829   void setPICLevel(PICLevel::Level PL);
 830 /// @}
 831
 832 /// @}
 833 /// @name Utility functions for querying and setting PIE level
 834 /// @{
 835
 836   /// Returns the PIE level (small or large model)
 837   PIELevel::Level getPIELevel() const;
 838
 839   /// Set the PIE level (small or large model)
 840   void setPIELevel(PIELevel::Level PL);
 841 /// @}
 842
 843   /// @name Utility functions for querying and setting PGO summary
 844   /// @{
 845
 846   /// Attach profile summary metadata to this module.
 847   void setProfileSummary(Metadata *M);
 848
 849   /// Returns profile summary metadata
 850   Metadata *getProfileSummary();
 851   /// @}
 852
 853   /// Returns true if PLT should be avoided for RTLib calls.
 854   bool getRtLibUseGOT() const;
 855
 856   /// Set that PLT should be avoid for RTLib calls.
 857   void setRtLibUseGOT();
 858
 859
 860   /// Take ownership of the given memory buffer.
 861   void setOwnedMemoryBuffer(std::unique_ptr<MemoryBuffer> MB);
 862 };
 863
 864 /// Given "llvm.used" or "llvm.compiler.used" as a global name, collect
 865 /// the initializer elements of that global in Set and return the global itself.
 866 GlobalVariable *collectUsedGlobalVariables(const Module &M,
 867                                            SmallPtrSetImpl<GlobalValue *> &Set,
 868                                            bool CompilerUsed);
 869
 870 /// An raw_ostream inserter for modules.
 871 inline raw_ostream &operator<<(raw_ostream &O, const Module &M) {
 872   M.print(O, nullptr);
 873   return O;
 874 }
 875
 876 // Create wrappers for C Binding types (see CBindingWrapping.h).
 877 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(Module, LLVMModuleRef)
 878
 879 /* LLVMModuleProviderRef exists for historical reasons, but now just holds a
 880  * Module.
 881  */
 882 inline Module *unwrap(LLVMModuleProviderRef MP) {
 883   return reinterpret_cast<Module*>(MP);
 884 }
 885
 886 } // end namespace llvm
 887
 888 #endif // LLVM_IR_MODULE_H