include/clang/Serialization/Module.h

   1 //===--- Module.h - Module description --------------------------*- 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 //  This file defines the Module class, which describes a module that has
  11 //  been loaded from an AST file.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_CLANG_SERIALIZATION_MODULE_H
  16 #define LLVM_CLANG_SERIALIZATION_MODULE_H
  17
  18 #include "clang/Basic/FileManager.h"
  19 #include "clang/Basic/Module.h"
  20 #include "clang/Basic/SourceLocation.h"
  21 #include "clang/Serialization/ASTBitCodes.h"
  22 #include "clang/Serialization/ContinuousRangeMap.h"
  23 #include "clang/Serialization/ModuleFileExtension.h"
  24 #include "llvm/ADT/SetVector.h"
  25 #include "llvm/Bitcode/BitstreamReader.h"
  26 #include "llvm/Support/Endian.h"
  27 #include <memory>
  28 #include <string>
  29
  30 namespace llvm {
  31 template <typename Info> class OnDiskChainedHashTable;
  32 template <typename Info> class OnDiskIterableChainedHashTable;
  33 }
  34
  35 namespace clang {
  36
  37 class DeclContext;
  38 class Module;
  39
  40 namespace serialization {
  41
  42 namespace reader {
  43   class ASTDeclContextNameLookupTrait;
  44 }
  45
  46 /// \brief Specifies the kind of module that has been loaded.
  47 enum ModuleKind {
  48   MK_ImplicitModule, ///< File is an implicitly-loaded module.
  49   MK_ExplicitModule, ///< File is an explicitly-loaded module.
  50   MK_PCH,            ///< File is a PCH file treated as such.
  51   MK_Preamble,       ///< File is a PCH file treated as the preamble.
  52   MK_MainFile,       ///< File is a PCH file treated as the actual main file.
  53   MK_PrebuiltModule  ///< File is from a prebuilt module path.
  54 };
  55
  56 /// \brief The input file that has been loaded from this AST file, along with
  57 /// bools indicating whether this was an overridden buffer or if it was
  58 /// out-of-date or not-found.
  59 class InputFile {
  60   enum {
  61     Overridden = 1,
  62     OutOfDate = 2,
  63     NotFound = 3
  64   };
  65   llvm::PointerIntPair<const FileEntry *, 2, unsigned> Val;
  66
  67 public:
  68   InputFile() {}
  69   InputFile(const FileEntry *File,
  70             bool isOverridden = false, bool isOutOfDate = false) {
  71     assert(!(isOverridden && isOutOfDate) &&
  72            "an overridden cannot be out-of-date");
  73     unsigned intVal = 0;
  74     if (isOverridden)
  75       intVal = Overridden;
  76     else if (isOutOfDate)
  77       intVal = OutOfDate;
  78     Val.setPointerAndInt(File, intVal);
  79   }
  80
  81   static InputFile getNotFound() {
  82     InputFile File;
  83     File.Val.setInt(NotFound);
  84     return File;
  85   }
  86
  87   const FileEntry *getFile() const { return Val.getPointer(); }
  88   bool isOverridden() const { return Val.getInt() == Overridden; }
  89   bool isOutOfDate() const { return Val.getInt() == OutOfDate; }
  90   bool isNotFound() const { return Val.getInt() == NotFound; }
  91 };
  92
  93 /// \brief Information about a module that has been loaded by the ASTReader.
  94 ///
  95 /// Each instance of the Module class corresponds to a single AST file, which
  96 /// may be a precompiled header, precompiled preamble, a module, or an AST file
  97 /// of some sort loaded as the main file, all of which are specific formulations
  98 /// of the general notion of a "module". A module may depend on any number of
  99 /// other modules.
 100 class ModuleFile {
 101 public:
 102   ModuleFile(ModuleKind Kind, unsigned Generation)
 103       : Kind(Kind), Generation(Generation) {}
 104   ~ModuleFile();
 105
 106   // === General information ===
 107
 108   /// \brief The index of this module in the list of modules.
 109   unsigned Index = 0;
 110
 111   /// \brief The type of this module.
 112   ModuleKind Kind;
 113
 114   /// \brief The file name of the module file.
 115   std::string FileName;
 116
 117   /// \brief The name of the module.
 118   std::string ModuleName;
 119
 120   /// \brief The base directory of the module.
 121   std::string BaseDirectory;
 122
 123   std::string getTimestampFilename() const {
 124     return FileName + ".timestamp";
 125   }
 126
 127   /// \brief The original source file name that was used to build the
 128   /// primary AST file, which may have been modified for
 129   /// relocatable-pch support.
 130   std::string OriginalSourceFileName;
 131
 132   /// \brief The actual original source file name that was used to
 133   /// build this AST file.
 134   std::string ActualOriginalSourceFileName;
 135
 136   /// \brief The file ID for the original source file that was used to
 137   /// build this AST file.
 138   FileID OriginalSourceFileID;
 139
 140   /// \brief The directory that the PCH was originally created in. Used to
 141   /// allow resolving headers even after headers+PCH was moved to a new path.
 142   std::string OriginalDir;
 143
 144   std::string ModuleMapPath;
 145
 146   /// \brief Whether this precompiled header is a relocatable PCH file.
 147   bool RelocatablePCH = false;
 148
 149   /// \brief Whether timestamps are included in this module file.
 150   bool HasTimestamps = false;
 151
 152   /// \brief The file entry for the module file.
 153   const FileEntry *File = nullptr;
 154
 155   /// The signature of the module file, which may be used instead of the size
 156   /// and modification time to identify this particular file.
 157   ASTFileSignature Signature;
 158
 159   /// \brief Whether this module has been directly imported by the
 160   /// user.
 161   bool DirectlyImported = false;
 162
 163   /// \brief The generation of which this module file is a part.
 164   unsigned Generation;
 165
 166   /// The memory buffer that stores the data associated with
 167   /// this AST file, owned by the PCMCache in the ModuleManager.
 168   llvm::MemoryBuffer *Buffer;
 169
 170   /// \brief The size of this file, in bits.
 171   uint64_t SizeInBits = 0;
 172
 173   /// \brief The global bit offset (or base) of this module
 174   uint64_t GlobalBitOffset = 0;
 175
 176   /// \brief The serialized bitstream data for this file.
 177   StringRef Data;
 178
 179   /// \brief The main bitstream cursor for the main block.
 180   llvm::BitstreamCursor Stream;
 181
 182   /// \brief The source location where the module was explicitly or implicitly
 183   /// imported in the local translation unit.
 184   ///
 185   /// If module A depends on and imports module B, both modules will have the
 186   /// same DirectImportLoc, but different ImportLoc (B's ImportLoc will be a
 187   /// source location inside module A).
 188   ///
 189   /// WARNING: This is largely useless. It doesn't tell you when a module was
 190   /// made visible, just when the first submodule of that module was imported.
 191   SourceLocation DirectImportLoc;
 192
 193   /// \brief The source location where this module was first imported.
 194   SourceLocation ImportLoc;
 195
 196   /// \brief The first source location in this module.
 197   SourceLocation FirstLoc;
 198
 199   /// The list of extension readers that are attached to this module
 200   /// file.
 201   std::vector<std::unique_ptr<ModuleFileExtensionReader>> ExtensionReaders;
 202
 203   /// The module offset map data for this file. If non-empty, the various
 204   /// ContinuousRangeMaps described below have not yet been populated.
 205   StringRef ModuleOffsetMap;
 206
 207   // === Input Files ===
 208   /// \brief The cursor to the start of the input-files block.
 209   llvm::BitstreamCursor InputFilesCursor;
 210
 211   /// \brief Offsets for all of the input file entries in the AST file.
 212   const llvm::support::unaligned_uint64_t *InputFileOffsets = nullptr;
 213
 214   /// \brief The input files that have been loaded from this AST file.
 215   std::vector<InputFile> InputFilesLoaded;
 216
 217   // All user input files reside at the index range [0, NumUserInputFiles), and
 218   // system input files reside at [NumUserInputFiles, InputFilesLoaded.size()).
 219   unsigned NumUserInputFiles = 0;
 220
 221   /// \brief If non-zero, specifies the time when we last validated input
 222   /// files.  Zero means we never validated them.
 223   ///
 224   /// The time is specified in seconds since the start of the Epoch.
 225   uint64_t InputFilesValidationTimestamp = 0;
 226
 227   // === Source Locations ===
 228
 229   /// \brief Cursor used to read source location entries.
 230   llvm::BitstreamCursor SLocEntryCursor;
 231
 232   /// \brief The number of source location entries in this AST file.
 233   unsigned LocalNumSLocEntries = 0;
 234
 235   /// \brief The base ID in the source manager's view of this module.
 236   int SLocEntryBaseID = 0;
 237
 238   /// \brief The base offset in the source manager's view of this module.
 239   unsigned SLocEntryBaseOffset = 0;
 240
 241   /// \brief Offsets for all of the source location entries in the
 242   /// AST file.
 243   const uint32_t *SLocEntryOffsets = nullptr;
 244
 245   /// \brief SLocEntries that we're going to preload.
 246   SmallVector<uint64_t, 4> PreloadSLocEntries;
 247
 248   /// \brief Remapping table for source locations in this module.
 249   ContinuousRangeMap<uint32_t, int, 2> SLocRemap;
 250
 251   // === Identifiers ===
 252
 253   /// \brief The number of identifiers in this AST file.
 254   unsigned LocalNumIdentifiers = 0;
 255
 256   /// \brief Offsets into the identifier table data.
 257   ///
 258   /// This array is indexed by the identifier ID (-1), and provides
 259   /// the offset into IdentifierTableData where the string data is
 260   /// stored.
 261   const uint32_t *IdentifierOffsets = nullptr;
 262
 263   /// \brief Base identifier ID for identifiers local to this module.
 264   serialization::IdentID BaseIdentifierID = 0;
 265
 266   /// \brief Remapping table for identifier IDs in this module.
 267   ContinuousRangeMap<uint32_t, int, 2> IdentifierRemap;
 268
 269   /// \brief Actual data for the on-disk hash table of identifiers.
 270   ///
 271   /// This pointer points into a memory buffer, where the on-disk hash
 272   /// table for identifiers actually lives.
 273   const char *IdentifierTableData = nullptr;
 274
 275   /// \brief A pointer to an on-disk hash table of opaque type
 276   /// IdentifierHashTable.
 277   void *IdentifierLookupTable = nullptr;
 278
 279   /// \brief Offsets of identifiers that we're going to preload within
 280   /// IdentifierTableData.
 281   std::vector<unsigned> PreloadIdentifierOffsets;
 282
 283   // === Macros ===
 284
 285   /// \brief The cursor to the start of the preprocessor block, which stores
 286   /// all of the macro definitions.
 287   llvm::BitstreamCursor MacroCursor;
 288
 289   /// \brief The number of macros in this AST file.
 290   unsigned LocalNumMacros = 0;
 291
 292   /// \brief Offsets of macros in the preprocessor block.
 293   ///
 294   /// This array is indexed by the macro ID (-1), and provides
 295   /// the offset into the preprocessor block where macro definitions are
 296   /// stored.
 297   const uint32_t *MacroOffsets = nullptr;
 298
 299   /// \brief Base macro ID for macros local to this module.
 300   serialization::MacroID BaseMacroID = 0;
 301
 302   /// \brief Remapping table for macro IDs in this module.
 303   ContinuousRangeMap<uint32_t, int, 2> MacroRemap;
 304
 305   /// \brief The offset of the start of the set of defined macros.
 306   uint64_t MacroStartOffset = 0;
 307
 308   // === Detailed PreprocessingRecord ===
 309
 310   /// \brief The cursor to the start of the (optional) detailed preprocessing
 311   /// record block.
 312   llvm::BitstreamCursor PreprocessorDetailCursor;
 313
 314   /// \brief The offset of the start of the preprocessor detail cursor.
 315   uint64_t PreprocessorDetailStartOffset = 0;
 316
 317   /// \brief Base preprocessed entity ID for preprocessed entities local to
 318   /// this module.
 319   serialization::PreprocessedEntityID BasePreprocessedEntityID = 0;
 320
 321   /// \brief Remapping table for preprocessed entity IDs in this module.
 322   ContinuousRangeMap<uint32_t, int, 2> PreprocessedEntityRemap;
 323
 324   const PPEntityOffset *PreprocessedEntityOffsets = nullptr;
 325   unsigned NumPreprocessedEntities = 0;
 326
 327   // === Header search information ===
 328
 329   /// \brief The number of local HeaderFileInfo structures.
 330   unsigned LocalNumHeaderFileInfos = 0;
 331
 332   /// \brief Actual data for the on-disk hash table of header file
 333   /// information.
 334   ///
 335   /// This pointer points into a memory buffer, where the on-disk hash
 336   /// table for header file information actually lives.
 337   const char *HeaderFileInfoTableData = nullptr;
 338
 339   /// \brief The on-disk hash table that contains information about each of
 340   /// the header files.
 341   void *HeaderFileInfoTable = nullptr;
 342
 343   // === Submodule information ===
 344   /// \brief The number of submodules in this module.
 345   unsigned LocalNumSubmodules = 0;
 346
 347   /// \brief Base submodule ID for submodules local to this module.
 348   serialization::SubmoduleID BaseSubmoduleID = 0;
 349
 350   /// \brief Remapping table for submodule IDs in this module.
 351   ContinuousRangeMap<uint32_t, int, 2> SubmoduleRemap;
 352
 353   // === Selectors ===
 354
 355   /// \brief The number of selectors new to this file.
 356   ///
 357   /// This is the number of entries in SelectorOffsets.
 358   unsigned LocalNumSelectors = 0;
 359
 360   /// \brief Offsets into the selector lookup table's data array
 361   /// where each selector resides.
 362   const uint32_t *SelectorOffsets = nullptr;
 363
 364   /// \brief Base selector ID for selectors local to this module.
 365   serialization::SelectorID BaseSelectorID = 0;
 366
 367   /// \brief Remapping table for selector IDs in this module.
 368   ContinuousRangeMap<uint32_t, int, 2> SelectorRemap;
 369
 370   /// \brief A pointer to the character data that comprises the selector table
 371   ///
 372   /// The SelectorOffsets table refers into this memory.
 373   const unsigned char *SelectorLookupTableData = nullptr;
 374
 375   /// \brief A pointer to an on-disk hash table of opaque type
 376   /// ASTSelectorLookupTable.
 377   ///
 378   /// This hash table provides the IDs of all selectors, and the associated
 379   /// instance and factory methods.
 380   void *SelectorLookupTable = nullptr;
 381
 382   // === Declarations ===
 383
 384   /// DeclsCursor - This is a cursor to the start of the DECLS_BLOCK block. It
 385   /// has read all the abbreviations at the start of the block and is ready to
 386   /// jump around with these in context.
 387   llvm::BitstreamCursor DeclsCursor;
 388
 389   /// \brief The number of declarations in this AST file.
 390   unsigned LocalNumDecls = 0;
 391
 392   /// \brief Offset of each declaration within the bitstream, indexed
 393   /// by the declaration ID (-1).
 394   const DeclOffset *DeclOffsets = nullptr;
 395
 396   /// \brief Base declaration ID for declarations local to this module.
 397   serialization::DeclID BaseDeclID = 0;
 398
 399   /// \brief Remapping table for declaration IDs in this module.
 400   ContinuousRangeMap<uint32_t, int, 2> DeclRemap;
 401
 402   /// \brief Mapping from the module files that this module file depends on
 403   /// to the base declaration ID for that module as it is understood within this
 404   /// module.
 405   ///
 406   /// This is effectively a reverse global-to-local mapping for declaration
 407   /// IDs, so that we can interpret a true global ID (for this translation unit)
 408   /// as a local ID (for this module file).
 409   llvm::DenseMap<ModuleFile *, serialization::DeclID> GlobalToLocalDeclIDs;
 410
 411   /// \brief Array of file-level DeclIDs sorted by file.
 412   const serialization::DeclID *FileSortedDecls = nullptr;
 413   unsigned NumFileSortedDecls = 0;
 414
 415   /// \brief Array of category list location information within this
 416   /// module file, sorted by the definition ID.
 417   const serialization::ObjCCategoriesInfo *ObjCCategoriesMap = nullptr;
 418
 419   /// \brief The number of redeclaration info entries in ObjCCategoriesMap.
 420   unsigned LocalNumObjCCategoriesInMap = 0;
 421
 422   /// \brief The Objective-C category lists for categories known to this
 423   /// module.
 424   SmallVector<uint64_t, 1> ObjCCategories;
 425
 426   // === Types ===
 427
 428   /// \brief The number of types in this AST file.
 429   unsigned LocalNumTypes = 0;
 430
 431   /// \brief Offset of each type within the bitstream, indexed by the
 432   /// type ID, or the representation of a Type*.
 433   const uint32_t *TypeOffsets = nullptr;
 434
 435   /// \brief Base type ID for types local to this module as represented in
 436   /// the global type ID space.
 437   serialization::TypeID BaseTypeIndex = 0;
 438
 439   /// \brief Remapping table for type IDs in this module.
 440   ContinuousRangeMap<uint32_t, int, 2> TypeRemap;
 441
 442   // === Miscellaneous ===
 443
 444   /// \brief Diagnostic IDs and their mappings that the user changed.
 445   SmallVector<uint64_t, 8> PragmaDiagMappings;
 446
 447   /// \brief List of modules which depend on this module
 448   llvm::SetVector<ModuleFile *> ImportedBy;
 449
 450   /// \brief List of modules which this module depends on
 451   llvm::SetVector<ModuleFile *> Imports;
 452
 453   /// \brief Determine whether this module was directly imported at
 454   /// any point during translation.
 455   bool isDirectlyImported() const { return DirectlyImported; }
 456
 457   /// \brief Is this a module file for a module (rather than a PCH or similar).
 458   bool isModule() const {
 459     return Kind == MK_ImplicitModule || Kind == MK_ExplicitModule ||
 460            Kind == MK_PrebuiltModule;
 461   }
 462
 463   /// \brief Dump debugging output for this module.
 464   void dump();
 465 };
 466
 467 } // end namespace serialization
 468
 469 } // end namespace clang
 470
 471 #endif