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