1 //===--- GlobalModuleIndex.h - Global Module Index --------------*- 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 GlobalModuleIndex class, which manages a global index 11 // containing all of the identifiers known to the various modules within a given 12 // subdirectory of the module cache. It is used to improve the performance of 13 // queries such as "do any modules know about this identifier?" 14 // 15 //===----------------------------------------------------------------------===// 16 #ifndef LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H 17 #define LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H 18 19 #include "llvm/ADT/DenseMap.h" 20 #include "llvm/ADT/SmallPtrSet.h" 21 #include "llvm/ADT/SmallVector.h" 22 #include "llvm/ADT/StringMap.h" 23 #include "llvm/ADT/StringRef.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 DirectoryEntry; 35 class FileEntry; 36 class FileManager; 37 class IdentifierIterator; 38 class PCHContainerOperations; 39 class PCHContainerReader; 40 41 namespace serialization { 42 class ModuleFile; 43 } 44 45 using llvm::SmallVector; 46 using llvm::SmallVectorImpl; 47 using llvm::StringRef; 48 using serialization::ModuleFile; 49 50 /// \brief A global index for a set of module files, providing information about 51 /// the identifiers within those module files. 52 /// 53 /// The global index is an aid for name lookup into modules, offering a central 54 /// place where one can look for identifiers determine which 55 /// module files contain any information about that identifier. This 56 /// allows the client to restrict the search to only those module files known 57 /// to have a information about that identifier, improving performance. Moreover, 58 /// the global module index may know about module files that have not been 59 /// imported, and can be queried to determine which modules the current 60 /// translation could or should load to fix a problem. 61 class GlobalModuleIndex { 62 /// \brief Buffer containing the index file, which is lazily accessed so long 63 /// as the global module index is live. 64 std::unique_ptr<llvm::MemoryBuffer> Buffer; 65 66 /// \brief The hash table. 67 /// 68 /// This pointer actually points to a IdentifierIndexTable object, 69 /// but that type is only accessible within the implementation of 70 /// GlobalModuleIndex. 71 void *IdentifierIndex; 72 73 /// \brief Information about a given module file. 74 struct ModuleInfo { ModuleInfoModuleInfo75 ModuleInfo() : File(), Size(), ModTime() { } 76 77 /// \brief The module file, once it has been resolved. 78 ModuleFile *File; 79 80 /// \brief The module file name. 81 std::string FileName; 82 83 /// \brief Size of the module file at the time the global index was built. 84 off_t Size; 85 86 /// \brief Modification time of the module file at the time the global 87 /// index was built. 88 time_t ModTime; 89 90 /// \brief The module IDs on which this module directly depends. 91 /// FIXME: We don't really need a vector here. 92 llvm::SmallVector<unsigned, 4> Dependencies; 93 }; 94 95 /// \brief A mapping from module IDs to information about each module. 96 /// 97 /// This vector may have gaps, if module files have been removed or have 98 /// been updated since the index was built. A gap is indicated by an empty 99 /// file name. 100 llvm::SmallVector<ModuleInfo, 16> Modules; 101 102 /// \brief Lazily-populated mapping from module files to their 103 /// corresponding index into the \c Modules vector. 104 llvm::DenseMap<ModuleFile *, unsigned> ModulesByFile; 105 106 /// \brief The set of modules that have not yet been resolved. 107 /// 108 /// The string is just the name of the module itself, which maps to the 109 /// module ID. 110 llvm::StringMap<unsigned> UnresolvedModules; 111 112 /// \brief The number of identifier lookups we performed. 113 unsigned NumIdentifierLookups; 114 115 /// \brief The number of identifier lookup hits, where we recognize the 116 /// identifier. 117 unsigned NumIdentifierLookupHits; 118 119 /// \brief Internal constructor. Use \c readIndex() to read an index. 120 explicit GlobalModuleIndex(std::unique_ptr<llvm::MemoryBuffer> Buffer, 121 llvm::BitstreamCursor Cursor); 122 123 GlobalModuleIndex(const GlobalModuleIndex &) = delete; 124 GlobalModuleIndex &operator=(const GlobalModuleIndex &) = delete; 125 126 public: 127 ~GlobalModuleIndex(); 128 129 /// \brief An error code returned when trying to read an index. 130 enum ErrorCode { 131 /// \brief No error occurred. 132 EC_None, 133 /// \brief No index was found. 134 EC_NotFound, 135 /// \brief Some other process is currently building the index; it is not 136 /// available yet. 137 EC_Building, 138 /// \brief There was an unspecified I/O error reading or writing the index. 139 EC_IOError 140 }; 141 142 /// \brief Read a global index file for the given directory. 143 /// 144 /// \param Path The path to the specific module cache where the module files 145 /// for the intended configuration reside. 146 /// 147 /// \returns A pair containing the global module index (if it exists) and 148 /// the error code. 149 static std::pair<GlobalModuleIndex *, ErrorCode> 150 readIndex(StringRef Path); 151 152 /// \brief Returns an iterator for identifiers stored in the index table. 153 /// 154 /// The caller accepts ownership of the returned object. 155 IdentifierIterator *createIdentifierIterator() const; 156 157 /// \brief Retrieve the set of modules that have up-to-date indexes. 158 /// 159 /// \param ModuleFiles Will be populated with the set of module files that 160 /// have been indexed. 161 void getKnownModules(SmallVectorImpl<ModuleFile *> &ModuleFiles); 162 163 /// \brief Retrieve the set of module files on which the given module file 164 /// directly depends. 165 void getModuleDependencies(ModuleFile *File, 166 SmallVectorImpl<ModuleFile *> &Dependencies); 167 168 /// \brief A set of module files in which we found a result. 169 typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet; 170 171 /// \brief Look for all of the module files with information about the given 172 /// identifier, e.g., a global function, variable, or type with that name. 173 /// 174 /// \param Name The identifier to look for. 175 /// 176 /// \param Hits Will be populated with the set of module files that have 177 /// information about this name. 178 /// 179 /// \returns true if the identifier is known to the index, false otherwise. 180 bool lookupIdentifier(StringRef Name, HitSet &Hits); 181 182 /// \brief Note that the given module file has been loaded. 183 /// 184 /// \returns false if the global module index has information about this 185 /// module file, and true otherwise. 186 bool loadedModuleFile(ModuleFile *File); 187 188 /// \brief Print statistics to standard error. 189 void printStats(); 190 191 /// \brief Print debugging view to standard error. 192 void dump(); 193 194 /// \brief Write a global index into the given 195 /// 196 /// \param FileMgr The file manager to use to load module files. 197 /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and 198 /// creating modules. 199 /// \param Path The path to the directory containing module files, into 200 /// which the global index will be written. 201 static ErrorCode writeIndex(FileManager &FileMgr, 202 const PCHContainerReader &PCHContainerRdr, 203 StringRef Path); 204 }; 205 } 206 207 #endif 208