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. 54 class GlobalModuleIndex { 55 using ModuleFile = serialization::ModuleFile; 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. 73 ModuleFile *File; 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. 95 llvm::SmallVector<ModuleInfo, 16> Modules; 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: 122 ~GlobalModuleIndex(); 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. 137 IdentifierIterator *createIdentifierIterator() const; 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. 143 void getKnownModules(llvm::SmallVectorImpl<ModuleFile *> &ModuleFiles); 144 145 /// Retrieve the set of module files on which the given module file 146 /// directly depends. 147 void getModuleDependencies(ModuleFile *File, 148 llvm::SmallVectorImpl<ModuleFile *> &Dependencies); 149 150 /// A set of module files in which we found a result. 151 typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet; 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 190