clang  15.0.0git
GlobalModuleIndex.h
Go to the documentation of this file.
1 //===--- GlobalModuleIndex.h - Global Module Index --------------*- 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 GlobalModuleIndex class, which manages a global index
10 // containing all of the identifiers known to the various modules within a given
11 // subdirectory of the module cache. It is used to improve the performance of
12 // queries such as "do any modules know about this identifier?"
13 //
14 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
16 #define LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
17 
18 #include "llvm/ADT/DenseMap.h"
19 #include "llvm/ADT/SmallPtrSet.h"
20 #include "llvm/ADT/SmallVector.h"
21 #include "llvm/ADT/StringMap.h"
22 #include "llvm/ADT/StringRef.h"
23 #include "llvm/Support/Error.h"
24 #include <memory>
25 #include <utility>
26 
27 namespace llvm {
28 class BitstreamCursor;
29 class MemoryBuffer;
30 }
31 
32 namespace clang {
33 
34 class FileManager;
35 class IdentifierIterator;
36 class PCHContainerOperations;
37 class PCHContainerReader;
38 
39 namespace serialization {
40  class ModuleFile;
41 }
42 
43 /// A global index for a set of module files, providing information about
44 /// the identifiers within those module files.
45 ///
46 /// The global index is an aid for name lookup into modules, offering a central
47 /// place where one can look for identifiers determine which
48 /// module files contain any information about that identifier. This
49 /// allows the client to restrict the search to only those module files known
50 /// to have a information about that identifier, improving performance. Moreover,
51 /// the global module index may know about module files that have not been
52 /// imported, and can be queried to determine which modules the current
53 /// translation could or should load to fix a problem.
56 
57  /// Buffer containing the index file, which is lazily accessed so long
58  /// as the global module index is live.
59  std::unique_ptr<llvm::MemoryBuffer> Buffer;
60 
61  /// The hash table.
62  ///
63  /// This pointer actually points to a IdentifierIndexTable object,
64  /// but that type is only accessible within the implementation of
65  /// GlobalModuleIndex.
66  void *IdentifierIndex;
67 
68  /// Information about a given module file.
69  struct ModuleInfo {
70  ModuleInfo() : File(), Size(), ModTime() { }
71 
72  /// The module file, once it has been resolved.
74 
75  /// The module file name.
76  std::string FileName;
77 
78  /// Size of the module file at the time the global index was built.
79  off_t Size;
80 
81  /// Modification time of the module file at the time the global
82  /// index was built.
83  time_t ModTime;
84 
85  /// The module IDs on which this module directly depends.
86  /// FIXME: We don't really need a vector here.
87  llvm::SmallVector<unsigned, 4> Dependencies;
88  };
89 
90  /// A mapping from module IDs to information about each module.
91  ///
92  /// This vector may have gaps, if module files have been removed or have
93  /// been updated since the index was built. A gap is indicated by an empty
94  /// file name.
96 
97  /// Lazily-populated mapping from module files to their
98  /// corresponding index into the \c Modules vector.
99  llvm::DenseMap<ModuleFile *, unsigned> ModulesByFile;
100 
101  /// The set of modules that have not yet been resolved.
102  ///
103  /// The string is just the name of the module itself, which maps to the
104  /// module ID.
105  llvm::StringMap<unsigned> UnresolvedModules;
106 
107  /// The number of identifier lookups we performed.
108  unsigned NumIdentifierLookups;
109 
110  /// The number of identifier lookup hits, where we recognize the
111  /// identifier.
112  unsigned NumIdentifierLookupHits;
113 
114  /// Internal constructor. Use \c readIndex() to read an index.
115  explicit GlobalModuleIndex(std::unique_ptr<llvm::MemoryBuffer> Buffer,
116  llvm::BitstreamCursor Cursor);
117 
118  GlobalModuleIndex(const GlobalModuleIndex &) = delete;
119  GlobalModuleIndex &operator=(const GlobalModuleIndex &) = delete;
120 
121 public:
123 
124  /// Read a global index file for the given directory.
125  ///
126  /// \param Path The path to the specific module cache where the module files
127  /// for the intended configuration reside.
128  ///
129  /// \returns A pair containing the global module index (if it exists) and
130  /// the error.
131  static std::pair<GlobalModuleIndex *, llvm::Error>
132  readIndex(llvm::StringRef Path);
133 
134  /// Returns an iterator for identifiers stored in the index table.
135  ///
136  /// The caller accepts ownership of the returned object.
138 
139  /// Retrieve the set of modules that have up-to-date indexes.
140  ///
141  /// \param ModuleFiles Will be populated with the set of module files that
142  /// have been indexed.
144 
145  /// Retrieve the set of module files on which the given module file
146  /// directly depends.
149 
150  /// A set of module files in which we found a result.
152 
153  /// Look for all of the module files with information about the given
154  /// identifier, e.g., a global function, variable, or type with that name.
155  ///
156  /// \param Name The identifier to look for.
157  ///
158  /// \param Hits Will be populated with the set of module files that have
159  /// information about this name.
160  ///
161  /// \returns true if the identifier is known to the index, false otherwise.
162  bool lookupIdentifier(llvm::StringRef Name, HitSet &Hits);
163 
164  /// Note that the given module file has been loaded.
165  ///
166  /// \returns false if the global module index has information about this
167  /// module file, and true otherwise.
168  bool loadedModuleFile(ModuleFile *File);
169 
170  /// Print statistics to standard error.
171  void printStats();
172 
173  /// Print debugging view to standard error.
174  void dump();
175 
176  /// Write a global index into the given
177  ///
178  /// \param FileMgr The file manager to use to load module files.
179  /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and
180  /// creating modules.
181  /// \param Path The path to the directory containing module files, into
182  /// which the global index will be written.
183  static llvm::Error writeIndex(FileManager &FileMgr,
184  const PCHContainerReader &PCHContainerRdr,
185  llvm::StringRef Path);
186 };
187 }
188 
189 #endif
clang::GlobalModuleIndex::getModuleDependencies
void getModuleDependencies(ModuleFile *File, llvm::SmallVectorImpl< ModuleFile * > &Dependencies)
Retrieve the set of module files on which the given module file directly depends.
Definition: GlobalModuleIndex.cpp:293
clang::GlobalModuleIndex
A global index for a set of module files, providing information about the identifiers within those mo...
Definition: GlobalModuleIndex.h:54
llvm
YAML serialization mapping.
Definition: Dominators.h:30
clang::GlobalModuleIndex::writeIndex
static llvm::Error writeIndex(FileManager &FileMgr, const PCHContainerReader &PCHContainerRdr, llvm::StringRef Path)
Write a global index into the given.
Definition: GlobalModuleIndex.cpp:852
clang::DeclaratorContext::File
@ File
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition: CMakeLists.txt:22
clang::GlobalModuleIndex::dump
void dump()
Print debugging view to standard error.
Definition: GlobalModuleIndex.cpp:374
llvm::SmallVector< unsigned, 4 >
clang::GlobalModuleIndex::printStats
void printStats()
Print statistics to standard error.
Definition: GlobalModuleIndex.cpp:364
Cursor
Cursor
Definition: SerializedDiagnosticReader.cpp:109
clang::GlobalModuleIndex::HitSet
llvm::SmallPtrSet< ModuleFile *, 4 > HitSet
A set of module files in which we found a result.
Definition: GlobalModuleIndex.h:151
clang::GlobalModuleIndex::getKnownModules
void getKnownModules(llvm::SmallVectorImpl< ModuleFile * > &ModuleFiles)
Retrieve the set of modules that have up-to-date indexes.
Definition: GlobalModuleIndex.cpp:285
llvm::SmallPtrSet
Definition: ASTContext.h:82
clang::PCHContainerReader
This abstract interface provides operations for unwrapping containers for serialized ASTs (precompile...
Definition: PCHContainerOperations.h:55
clang::IdentifierIterator
An iterator that walks over all of the known identifiers in the lookup table.
Definition: IdentifierTable.h:515
clang::GlobalModuleIndex::lookupIdentifier
bool lookupIdentifier(llvm::StringRef Name, HitSet &Hits)
Look for all of the module files with information about the given identifier, e.g....
Definition: GlobalModuleIndex.cpp:311
clang::GlobalModuleIndex::loadedModuleFile
bool loadedModuleFile(ModuleFile *File)
Note that the given module file has been loaded.
Definition: GlobalModuleIndex.cpp:337
clang
Definition: CalledOnceCheck.h:17
clang::FileManager
Implements support for file system lookup, file system caching, and directory search management.
Definition: FileManager.h:53
clang::GlobalModuleIndex::~GlobalModuleIndex
~GlobalModuleIndex()
Definition: GlobalModuleIndex.cpp:248
llvm::SmallVectorImpl
Definition: Randstruct.h:18
clang::GlobalModuleIndex::readIndex
static std::pair< GlobalModuleIndex *, llvm::Error > readIndex(llvm::StringRef Path)
Read a global index file for the given directory.
Definition: GlobalModuleIndex.cpp:253
clang::serialization::ModuleFile
Information about a module that has been loaded by the ASTReader.
Definition: ModuleFile.h:111
clang::GlobalModuleIndex::createIdentifierIterator
IdentifierIterator * createIdentifierIterator() const
Returns an iterator for identifiers stored in the index table.
Definition: GlobalModuleIndex.cpp:945