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() = default; |
71 | |
72 | /// The module file, once it has been resolved. |
73 | ModuleFile *File = nullptr; |
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 = 0; |
80 | |
81 | /// Modification time of the module file at the time the global |
82 | /// index was built. |
83 | time_t ModTime = 0; |
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 module files on which the given module file |
140 | /// directly depends. |
141 | void getModuleDependencies(ModuleFile *File, |
142 | llvm::SmallVectorImpl<ModuleFile *> &Dependencies); |
143 | |
144 | /// A set of module files in which we found a result. |
145 | typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet; |
146 | |
147 | /// Look for all of the module files with information about the given |
148 | /// identifier, e.g., a global function, variable, or type with that name. |
149 | /// |
150 | /// \param Name The identifier to look for. |
151 | /// |
152 | /// \param Hits Will be populated with the set of module files that have |
153 | /// information about this name. |
154 | /// |
155 | /// \returns true if the identifier is known to the index, false otherwise. |
156 | bool lookupIdentifier(llvm::StringRef Name, HitSet &Hits); |
157 | |
158 | /// Note that the given module file has been loaded. |
159 | /// |
160 | /// \returns false if the global module index has information about this |
161 | /// module file, and true otherwise. |
162 | bool loadedModuleFile(ModuleFile *File); |
163 | |
164 | /// Print statistics to standard error. |
165 | void printStats(); |
166 | |
167 | /// Print debugging view to standard error. |
168 | void dump(); |
169 | |
170 | /// Write a global index into the given |
171 | /// |
172 | /// \param FileMgr The file manager to use to load module files. |
173 | /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and |
174 | /// creating modules. |
175 | /// \param Path The path to the directory containing module files, into |
176 | /// which the global index will be written. |
177 | static llvm::Error writeIndex(FileManager &FileMgr, |
178 | const PCHContainerReader &PCHContainerRdr, |
179 | llvm::StringRef Path); |
180 | }; |
181 | } |
182 | |
183 | #endif |
184 | |