1 | //===--- CrossTranslationUnit.h - -------------------------------*- 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 provides an interface to load binary AST dumps on demand. This |
10 | // feature can be utilized for tools that require cross translation unit |
11 | // support. |
12 | // |
13 | //===----------------------------------------------------------------------===// |
14 | #ifndef LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H |
15 | #define LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H |
16 | |
17 | #include "clang/AST/ASTImporterSharedState.h" |
18 | #include "clang/Basic/LLVM.h" |
19 | #include "llvm/ADT/DenseMap.h" |
20 | #include "llvm/ADT/Optional.h" |
21 | #include "llvm/ADT/SmallPtrSet.h" |
22 | #include "llvm/ADT/StringMap.h" |
23 | #include "llvm/Support/Error.h" |
24 | |
25 | namespace clang { |
26 | class CompilerInstance; |
27 | class ASTContext; |
28 | class ASTImporter; |
29 | class ASTUnit; |
30 | class DeclContext; |
31 | class FunctionDecl; |
32 | class VarDecl; |
33 | class NamedDecl; |
34 | class TranslationUnitDecl; |
35 | |
36 | namespace cross_tu { |
37 | |
38 | enum class index_error_code { |
39 | unspecified = 1, |
40 | missing_index_file, |
41 | invalid_index_format, |
42 | multiple_definitions, |
43 | missing_definition, |
44 | failed_import, |
45 | failed_to_get_external_ast, |
46 | failed_to_generate_usr, |
47 | triple_mismatch, |
48 | lang_mismatch, |
49 | lang_dialect_mismatch, |
50 | load_threshold_reached |
51 | }; |
52 | |
53 | class IndexError : public llvm::ErrorInfo<IndexError> { |
54 | public: |
55 | static char ID; |
56 | IndexError(index_error_code C) : Code(C), LineNo(0) {} |
57 | IndexError(index_error_code C, std::string FileName, int LineNo = 0) |
58 | : Code(C), FileName(std::move(FileName)), LineNo(LineNo) {} |
59 | IndexError(index_error_code C, std::string FileName, std::string TripleToName, |
60 | std::string TripleFromName) |
61 | : Code(C), FileName(std::move(FileName)), |
62 | TripleToName(std::move(TripleToName)), |
63 | TripleFromName(std::move(TripleFromName)) {} |
64 | void log(raw_ostream &OS) const override; |
65 | std::error_code convertToErrorCode() const override; |
66 | index_error_code getCode() const { return Code; } |
67 | int getLineNum() const { return LineNo; } |
68 | std::string getFileName() const { return FileName; } |
69 | std::string getTripleToName() const { return TripleToName; } |
70 | std::string getTripleFromName() const { return TripleFromName; } |
71 | |
72 | private: |
73 | index_error_code Code; |
74 | std::string FileName; |
75 | int LineNo; |
76 | std::string TripleToName; |
77 | std::string TripleFromName; |
78 | }; |
79 | |
80 | /// This function parses an index file that determines which |
81 | /// translation unit contains which definition. |
82 | /// |
83 | /// The index file format is the following: |
84 | /// each line consists of an USR and a filepath separated by a space. |
85 | /// |
86 | /// \return Returns a map where the USR is the key and the filepath is the value |
87 | /// or an error. |
88 | llvm::Expected<llvm::StringMap<std::string>> |
89 | parseCrossTUIndex(StringRef IndexPath, StringRef CrossTUDir); |
90 | |
91 | std::string createCrossTUIndexString(const llvm::StringMap<std::string> &Index); |
92 | |
93 | // Returns true if the variable or any field of a record variable is const. |
94 | bool containsConst(const VarDecl *VD, const ASTContext &ACtx); |
95 | |
96 | /// This class is used for tools that requires cross translation |
97 | /// unit capability. |
98 | /// |
99 | /// This class can load definitions from external AST files. |
100 | /// The loaded definition will be merged back to the original AST using the |
101 | /// AST Importer. |
102 | /// In order to use this class, an index file is required that describes |
103 | /// the locations of the AST files for each definition. |
104 | /// |
105 | /// Note that this class also implements caching. |
106 | class CrossTranslationUnitContext { |
107 | public: |
108 | CrossTranslationUnitContext(CompilerInstance &CI); |
109 | ~CrossTranslationUnitContext(); |
110 | |
111 | /// This function loads a function or variable definition from an |
112 | /// external AST file and merges it into the original AST. |
113 | /// |
114 | /// This method should only be used on functions that have no definitions or |
115 | /// variables that have no initializer in |
116 | /// the current translation unit. A function definition with the same |
117 | /// declaration will be looked up in the index file which should be in the |
118 | /// \p CrossTUDir directory, called \p IndexName. In case the declaration is |
119 | /// found in the index the corresponding AST file will be loaded and the |
120 | /// definition will be merged into the original AST using the AST Importer. |
121 | /// |
122 | /// \return The declaration with the definition will be returned. |
123 | /// If no suitable definition is found in the index file or multiple |
124 | /// definitions found error will be returned. |
125 | /// |
126 | /// Note that the AST files should also be in the \p CrossTUDir. |
127 | llvm::Expected<const FunctionDecl *> |
128 | getCrossTUDefinition(const FunctionDecl *FD, StringRef CrossTUDir, |
129 | StringRef IndexName, bool DisplayCTUProgress = false); |
130 | llvm::Expected<const VarDecl *> |
131 | getCrossTUDefinition(const VarDecl *VD, StringRef CrossTUDir, |
132 | StringRef IndexName, bool DisplayCTUProgress = false); |
133 | |
134 | /// This function loads a definition from an external AST file. |
135 | /// |
136 | /// A definition with the same declaration will be looked up in the |
137 | /// index file which should be in the \p CrossTUDir directory, called |
138 | /// \p IndexName. In case the declaration is found in the index the |
139 | /// corresponding AST file will be loaded. If the number of TUs imported |
140 | /// reaches \p CTULoadTreshold, no loading is performed. |
141 | /// |
142 | /// \return Returns a pointer to the ASTUnit that contains the definition of |
143 | /// the looked up name or an Error. |
144 | /// The returned pointer is never a nullptr. |
145 | /// |
146 | /// Note that the AST files should also be in the \p CrossTUDir. |
147 | llvm::Expected<ASTUnit *> loadExternalAST(StringRef LookupName, |
148 | StringRef CrossTUDir, |
149 | StringRef IndexName, |
150 | bool DisplayCTUProgress = false); |
151 | |
152 | /// This function merges a definition from a separate AST Unit into |
153 | /// the current one which was created by the compiler instance that |
154 | /// was passed to the constructor. |
155 | /// |
156 | /// \return Returns the resulting definition or an error. |
157 | llvm::Expected<const FunctionDecl *> importDefinition(const FunctionDecl *FD, |
158 | ASTUnit *Unit); |
159 | llvm::Expected<const VarDecl *> importDefinition(const VarDecl *VD, |
160 | ASTUnit *Unit); |
161 | |
162 | /// Get a name to identify a named decl. |
163 | static llvm::Optional<std::string> getLookupName(const NamedDecl *ND); |
164 | |
165 | /// Emit diagnostics for the user for potential configuration errors. |
166 | void emitCrossTUDiagnostics(const IndexError &IE); |
167 | |
168 | /// Determine the original source location in the original TU for an |
169 | /// imported source location. |
170 | /// \p ToLoc Source location in the imported-to AST. |
171 | /// \return Source location in the imported-from AST and the corresponding |
172 | /// ASTUnit object (the AST was loaded from a file using an internal ASTUnit |
173 | /// object that is returned here). |
174 | /// If any error happens (ToLoc is a non-imported source location) empty is |
175 | /// returned. |
176 | llvm::Optional<std::pair<SourceLocation /*FromLoc*/, ASTUnit *>> |
177 | getImportedFromSourceLocation(const clang::SourceLocation &ToLoc) const; |
178 | |
179 | private: |
180 | using ImportedFileIDMap = |
181 | llvm::DenseMap<FileID, std::pair<FileID, ASTUnit *>>; |
182 | |
183 | void lazyInitImporterSharedSt(TranslationUnitDecl *ToTU); |
184 | ASTImporter &getOrCreateASTImporter(ASTUnit *Unit); |
185 | template <typename T> |
186 | llvm::Expected<const T *> getCrossTUDefinitionImpl(const T *D, |
187 | StringRef CrossTUDir, |
188 | StringRef IndexName, |
189 | bool DisplayCTUProgress); |
190 | template <typename T> |
191 | const T *findDefInDeclContext(const DeclContext *DC, |
192 | StringRef LookupName); |
193 | template <typename T> |
194 | llvm::Expected<const T *> importDefinitionImpl(const T *D, ASTUnit *Unit); |
195 | |
196 | using ImporterMapTy = |
197 | llvm::DenseMap<TranslationUnitDecl *, std::unique_ptr<ASTImporter>>; |
198 | |
199 | ImporterMapTy ASTUnitImporterMap; |
200 | |
201 | ASTContext &Context; |
202 | std::shared_ptr<ASTImporterSharedState> ImporterSharedSt; |
203 | /// Map of imported FileID's (in "To" context) to FileID in "From" context |
204 | /// and the ASTUnit for the From context. |
205 | /// This map is used by getImportedFromSourceLocation to lookup a FileID and |
206 | /// its Preprocessor when knowing only the FileID in the 'To' context. The |
207 | /// FileID could be imported by any of multiple 'From' ASTImporter objects. |
208 | /// we do not want to loop over all ASTImporter's to find the one that |
209 | /// imported the FileID. |
210 | ImportedFileIDMap ImportedFileIDs; |
211 | |
212 | /// Functor for loading ASTUnits from AST-dump files. |
213 | class ASTFileLoader { |
214 | public: |
215 | ASTFileLoader(const CompilerInstance &CI); |
216 | std::unique_ptr<ASTUnit> operator()(StringRef ASTFilePath); |
217 | |
218 | private: |
219 | const CompilerInstance &CI; |
220 | }; |
221 | |
222 | /// Maintain number of AST loads and check for reaching the load limit. |
223 | class ASTLoadGuard { |
224 | public: |
225 | ASTLoadGuard(unsigned Limit) : Limit(Limit) {} |
226 | |
227 | /// Indicates, whether a new load operation is permitted, it is within the |
228 | /// threshold. |
229 | operator bool() const { return Count < Limit; } |
230 | |
231 | /// Tell that a new AST was loaded successfully. |
232 | void indicateLoadSuccess() { ++Count; } |
233 | |
234 | private: |
235 | /// The number of ASTs actually imported. |
236 | unsigned Count{0u}; |
237 | /// The limit (threshold) value for number of loaded ASTs. |
238 | const unsigned Limit; |
239 | }; |
240 | |
241 | /// Storage and load of ASTUnits, cached access, and providing searchability |
242 | /// are the concerns of ASTUnitStorage class. |
243 | class ASTUnitStorage { |
244 | public: |
245 | ASTUnitStorage(const CompilerInstance &CI); |
246 | /// Loads an ASTUnit for a function. |
247 | /// |
248 | /// \param FunctionName USR name of the function. |
249 | /// \param CrossTUDir Path to the directory used to store CTU related files. |
250 | /// \param IndexName Name of the file inside \p CrossTUDir which maps |
251 | /// function USR names to file paths. These files contain the corresponding |
252 | /// AST-dumps. |
253 | /// \param DisplayCTUProgress Display a message about loading new ASTs. |
254 | /// |
255 | /// \return An Expected instance which contains the ASTUnit pointer or the |
256 | /// error occured during the load. |
257 | llvm::Expected<ASTUnit *> getASTUnitForFunction(StringRef FunctionName, |
258 | StringRef CrossTUDir, |
259 | StringRef IndexName, |
260 | bool DisplayCTUProgress); |
261 | /// Identifies the path of the file which can be used to load the ASTUnit |
262 | /// for a given function. |
263 | /// |
264 | /// \param FunctionName USR name of the function. |
265 | /// \param CrossTUDir Path to the directory used to store CTU related files. |
266 | /// \param IndexName Name of the file inside \p CrossTUDir which maps |
267 | /// function USR names to file paths. These files contain the corresponding |
268 | /// AST-dumps. |
269 | /// |
270 | /// \return An Expected instance containing the filepath. |
271 | llvm::Expected<std::string> getFileForFunction(StringRef FunctionName, |
272 | StringRef CrossTUDir, |
273 | StringRef IndexName); |
274 | |
275 | private: |
276 | llvm::Error ensureCTUIndexLoaded(StringRef CrossTUDir, StringRef IndexName); |
277 | llvm::Expected<ASTUnit *> getASTUnitForFile(StringRef FileName, |
278 | bool DisplayCTUProgress); |
279 | |
280 | template <typename... T> using BaseMapTy = llvm::StringMap<T...>; |
281 | using OwningMapTy = BaseMapTy<std::unique_ptr<clang::ASTUnit>>; |
282 | using NonOwningMapTy = BaseMapTy<clang::ASTUnit *>; |
283 | |
284 | OwningMapTy FileASTUnitMap; |
285 | NonOwningMapTy NameASTUnitMap; |
286 | |
287 | using IndexMapTy = BaseMapTy<std::string>; |
288 | IndexMapTy NameFileMap; |
289 | |
290 | ASTFileLoader FileAccessor; |
291 | |
292 | /// Limit the number of loaded ASTs. Used to limit the memory usage of the |
293 | /// CrossTranslationUnitContext. |
294 | /// The ASTUnitStorage has the knowledge about if the AST to load is |
295 | /// actually loaded or returned from cache. This information is needed to |
296 | /// maintain the counter. |
297 | ASTLoadGuard LoadGuard; |
298 | }; |
299 | |
300 | ASTUnitStorage ASTStorage; |
301 | |
302 | }; |
303 | |
304 | } // namespace cross_tu |
305 | } // namespace clang |
306 | |
307 | #endif // LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H |
308 | |