1 //===--- GlobalModuleIndex.h - Global Module Index --------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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?"
15 //===----------------------------------------------------------------------===//
16 #ifndef LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
17 #define LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
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"
28 class BitstreamCursor;
37 class IdentifierIterator;
38 class PCHContainerOperations;
40 namespace serialization {
44 using llvm::SmallVector;
45 using llvm::SmallVectorImpl;
46 using llvm::StringRef;
47 using serialization::ModuleFile;
49 /// \brief A global index for a set of module files, providing information about
50 /// the identifiers within those module files.
52 /// The global index is an aid for name lookup into modules, offering a central
53 /// place where one can look for identifiers determine which
54 /// module files contain any information about that identifier. This
55 /// allows the client to restrict the search to only those module files known
56 /// to have a information about that identifier, improving performance. Moreover,
57 /// the global module index may know about module files that have not been
58 /// imported, and can be queried to determine which modules the current
59 /// translation could or should load to fix a problem.
60 class GlobalModuleIndex {
61 /// \brief Buffer containing the index file, which is lazily accessed so long
62 /// as the global module index is live.
63 std::unique_ptr<llvm::MemoryBuffer> Buffer;
65 /// \brief The hash table.
67 /// This pointer actually points to a IdentifierIndexTable object,
68 /// but that type is only accessible within the implementation of
69 /// GlobalModuleIndex.
70 void *IdentifierIndex;
72 /// \brief Information about a given module file.
74 ModuleInfo() : File(), Size(), ModTime() { }
76 /// \brief The module file, once it has been resolved.
79 /// \brief The module file name.
82 /// \brief Size of the module file at the time the global index was built.
85 /// \brief Modification time of the module file at the time the global
89 /// \brief The module IDs on which this module directly depends.
90 /// FIXME: We don't really need a vector here.
91 llvm::SmallVector<unsigned, 4> Dependencies;
94 /// \brief A mapping from module IDs to information about each module.
96 /// This vector may have gaps, if module files have been removed or have
97 /// been updated since the index was built. A gap is indicated by an empty
99 llvm::SmallVector<ModuleInfo, 16> Modules;
101 /// \brief Lazily-populated mapping from module files to their
102 /// corresponding index into the \c Modules vector.
103 llvm::DenseMap<ModuleFile *, unsigned> ModulesByFile;
105 /// \brief The set of modules that have not yet been resolved.
107 /// The string is just the name of the module itself, which maps to the
109 llvm::StringMap<unsigned> UnresolvedModules;
111 /// \brief The number of identifier lookups we performed.
112 unsigned NumIdentifierLookups;
114 /// \brief The number of identifier lookup hits, where we recognize the
116 unsigned NumIdentifierLookupHits;
118 /// \brief Internal constructor. Use \c readIndex() to read an index.
119 explicit GlobalModuleIndex(std::unique_ptr<llvm::MemoryBuffer> Buffer,
120 llvm::BitstreamCursor Cursor);
122 GlobalModuleIndex(const GlobalModuleIndex &) = delete;
123 GlobalModuleIndex &operator=(const GlobalModuleIndex &) = delete;
126 ~GlobalModuleIndex();
128 /// \brief An error code returned when trying to read an index.
130 /// \brief No error occurred.
132 /// \brief No index was found.
134 /// \brief Some other process is currently building the index; it is not
137 /// \brief There was an unspecified I/O error reading or writing the index.
141 /// \brief Read a global index file for the given directory.
143 /// \param Path The path to the specific module cache where the module files
144 /// for the intended configuration reside.
146 /// \returns A pair containing the global module index (if it exists) and
148 static std::pair<GlobalModuleIndex *, ErrorCode>
149 readIndex(StringRef Path);
151 /// \brief Returns an iterator for identifiers stored in the index table.
153 /// The caller accepts ownership of the returned object.
154 IdentifierIterator *createIdentifierIterator() const;
156 /// \brief Retrieve the set of modules that have up-to-date indexes.
158 /// \param ModuleFiles Will be populated with the set of module files that
159 /// have been indexed.
160 void getKnownModules(SmallVectorImpl<ModuleFile *> &ModuleFiles);
162 /// \brief Retrieve the set of module files on which the given module file
163 /// directly depends.
164 void getModuleDependencies(ModuleFile *File,
165 SmallVectorImpl<ModuleFile *> &Dependencies);
167 /// \brief A set of module files in which we found a result.
168 typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet;
170 /// \brief Look for all of the module files with information about the given
171 /// identifier, e.g., a global function, variable, or type with that name.
173 /// \param Name The identifier to look for.
175 /// \param Hits Will be populated with the set of module files that have
176 /// information about this name.
178 /// \returns true if the identifier is known to the index, false otherwise.
179 bool lookupIdentifier(StringRef Name, HitSet &Hits);
181 /// \brief Note that the given module file has been loaded.
183 /// \returns false if the global module index has information about this
184 /// module file, and true otherwise.
185 bool loadedModuleFile(ModuleFile *File);
187 /// \brief Print statistics to standard error.
190 /// \brief Print debugging view to standard error.
193 /// \brief Write a global index into the given
195 /// \param FileMgr The file manager to use to load module files.
196 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
197 /// creating modules.
198 /// \param Path The path to the directory containing module files, into
199 /// which the global index will be written.
200 static ErrorCode writeIndex(FileManager &FileMgr,
201 const PCHContainerReader &PCHContainerRdr,