Coverage Report

Created: 2022-07-16 07:03

/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/CrossTU/CrossTranslationUnit.h
Line
Count
Source (jump to first uncovered line)
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/Analysis/MacroExpansionContext.h"
19
#include "clang/Basic/LLVM.h"
20
#include "llvm/ADT/DenseMap.h"
21
#include "llvm/ADT/Optional.h"
22
#include "llvm/ADT/SmallPtrSet.h"
23
#include "llvm/ADT/StringMap.h"
24
#include "llvm/Support/Error.h"
25
#include "llvm/Support/Path.h"
26
27
namespace clang {
28
class CompilerInstance;
29
class ASTContext;
30
class ASTImporter;
31
class ASTUnit;
32
class DeclContext;
33
class FunctionDecl;
34
class VarDecl;
35
class NamedDecl;
36
class TranslationUnitDecl;
37
38
namespace cross_tu {
39
40
enum class index_error_code {
41
  success = 0,
42
  unspecified = 1,
43
  missing_index_file,
44
  invalid_index_format,
45
  multiple_definitions,
46
  missing_definition,
47
  failed_import,
48
  failed_to_get_external_ast,
49
  failed_to_generate_usr,
50
  triple_mismatch,
51
  lang_mismatch,
52
  lang_dialect_mismatch,
53
  load_threshold_reached,
54
  invocation_list_ambiguous,
55
  invocation_list_file_not_found,
56
  invocation_list_empty,
57
  invocation_list_wrong_format,
58
  invocation_list_lookup_unsuccessful
59
};
60
61
class IndexError : public llvm::ErrorInfo<IndexError> {
62
public:
63
  static char ID;
64
18
  IndexError(index_error_code C) : Code(C), LineNo(0) {}
65
  IndexError(index_error_code C, std::string FileName, int LineNo = 0)
66
0
      : Code(C), FileName(std::move(FileName)), LineNo(LineNo) {}
67
  IndexError(index_error_code C, std::string FileName, std::string TripleToName,
68
             std::string TripleFromName)
69
      : Code(C), FileName(std::move(FileName)),
70
        TripleToName(std::move(TripleToName)),
71
1
        TripleFromName(std::move(TripleFromName)) {}
72
  void log(raw_ostream &OS) const override;
73
  std::error_code convertToErrorCode() const override;
74
18
  index_error_code getCode() const { return Code; }
75
0
  int getLineNum() const { return LineNo; }
76
1
  std::string getFileName() const { return FileName; }
77
1
  std::string getTripleToName() const { return TripleToName; }
78
1
  std::string getTripleFromName() const { return TripleFromName; }
79
80
private:
81
  index_error_code Code;
82
  std::string FileName;
83
  int LineNo;
84
  std::string TripleToName;
85
  std::string TripleFromName;
86
};
87
88
/// This function parses an index file that determines which
89
/// translation unit contains which definition. The IndexPath is not prefixed
90
/// with CTUDir, so an absolute path is expected for consistent results.
91
///
92
/// The index file format is the following:
93
/// each line consists of an USR and a filepath separated by a space.
94
///
95
/// \return Returns a map where the USR is the key and the filepath is the value
96
///         or an error.
97
llvm::Expected<llvm::StringMap<std::string>>
98
parseCrossTUIndex(StringRef IndexPath);
99
100
std::string createCrossTUIndexString(const llvm::StringMap<std::string> &Index);
101
102
using InvocationListTy = llvm::StringMap<llvm::SmallVector<std::string, 32>>;
103
/// Parse the YAML formatted invocation list file content \p FileContent.
104
/// The format is expected to be a mapping from from absolute source file
105
/// paths in the filesystem to a list of command-line parts, which
106
/// constitute the invocation needed to compile that file. That invocation
107
/// will be used to produce the AST of the TU.
108
llvm::Expected<InvocationListTy> parseInvocationList(
109
    StringRef FileContent,
110
    llvm::sys::path::Style PathStyle = llvm::sys::path::Style::posix);
111
112
/// Returns true if it makes sense to import a foreign variable definition.
113
/// For instance, we don't want to import variables that have non-trivial types
114
/// because the constructor might have side-effects.
115
bool shouldImport(const VarDecl *VD, const ASTContext &ACtx);
116
117
/// This class is used for tools that requires cross translation
118
///        unit capability.
119
///
120
/// This class can load definitions from external AST sources.
121
/// The loaded definition will be merged back to the original AST using the
122
/// AST Importer.
123
/// In order to use this class, an index file is required that describes
124
/// the locations of the AST files for each definition.
125
///
126
/// Note that this class also implements caching.
127
class CrossTranslationUnitContext {
128
public:
129
  CrossTranslationUnitContext(CompilerInstance &CI);
130
  ~CrossTranslationUnitContext();
131
132
  /// This function loads a function or variable definition from an
133
  ///        external AST file and merges it into the original AST.
134
  ///
135
  /// This method should only be used on functions that have no definitions or
136
  /// variables that have no initializer in
137
  /// the current translation unit. A function definition with the same
138
  /// declaration will be looked up in the index file which should be in the
139
  /// \p CrossTUDir directory, called \p IndexName. In case the declaration is
140
  /// found in the index the corresponding AST will be loaded and the
141
  /// definition will be merged into the original AST using the AST Importer.
142
  ///
143
  /// \return The declaration with the definition will be returned.
144
  /// If no suitable definition is found in the index file or multiple
145
  /// definitions found error will be returned.
146
  ///
147
  /// Note that the AST files should also be in the \p CrossTUDir.
148
  llvm::Expected<const FunctionDecl *>
149
  getCrossTUDefinition(const FunctionDecl *FD, StringRef CrossTUDir,
150
                       StringRef IndexName, bool DisplayCTUProgress = false);
151
  llvm::Expected<const VarDecl *>
152
  getCrossTUDefinition(const VarDecl *VD, StringRef CrossTUDir,
153
                       StringRef IndexName, bool DisplayCTUProgress = false);
154
155
  /// This function loads a definition from an external AST file.
156
  ///
157
  /// A definition with the same declaration will be looked up in the
158
  /// index file which should be in the \p CrossTUDir directory, called
159
  /// \p IndexName. In case the declaration is found in the index the
160
  /// corresponding AST will be loaded. If the number of TUs imported
161
  /// reaches \p CTULoadTreshold, no loading is performed.
162
  ///
163
  /// \return Returns a pointer to the ASTUnit that contains the definition of
164
  /// the looked up name or an Error.
165
  /// The returned pointer is never a nullptr.
166
  ///
167
  /// Note that the AST files should also be in the \p CrossTUDir.
168
  llvm::Expected<ASTUnit *> loadExternalAST(StringRef LookupName,
169
                                            StringRef CrossTUDir,
170
                                            StringRef IndexName,
171
                                            bool DisplayCTUProgress = false);
172
173
  /// This function merges a definition from a separate AST Unit into
174
  ///        the current one which was created by the compiler instance that
175
  ///        was passed to the constructor.
176
  ///
177
  /// \return Returns the resulting definition or an error.
178
  llvm::Expected<const FunctionDecl *> importDefinition(const FunctionDecl *FD,
179
                                                        ASTUnit *Unit);
180
  llvm::Expected<const VarDecl *> importDefinition(const VarDecl *VD,
181
                                                   ASTUnit *Unit);
182
183
  /// Get a name to identify a named decl.
184
  static llvm::Optional<std::string> getLookupName(const NamedDecl *ND);
185
186
  /// Emit diagnostics for the user for potential configuration errors.
187
  void emitCrossTUDiagnostics(const IndexError &IE);
188
189
  /// Returns the MacroExpansionContext for the imported TU to which the given
190
  /// source-location corresponds.
191
  /// \p ToLoc Source location in the imported-to AST.
192
  /// \note If any error happens such as \p ToLoc is a non-imported
193
  ///       source-location, empty is returned.
194
  /// \note Macro expansion tracking for imported TUs is not implemented yet.
195
  ///       It returns empty unconditionally.
196
  llvm::Optional<clang::MacroExpansionContext>
197
  getMacroExpansionContextForSourceLocation(
198
      const clang::SourceLocation &ToLoc) const;
199
200
  /// Returns true if the given Decl is newly created during the import.
201
  bool isImportedAsNew(const Decl *ToDecl) const;
202
203
  /// Returns true if the given Decl is mapped (or created) during an import
204
  /// but there was an unrecoverable error (the AST node cannot be erased, it
205
  /// is marked with an Error object in this case).
206
  bool hasError(const Decl *ToDecl) const;
207
208
private:
209
  void lazyInitImporterSharedSt(TranslationUnitDecl *ToTU);
210
  ASTImporter &getOrCreateASTImporter(ASTUnit *Unit);
211
  template <typename T>
212
  llvm::Expected<const T *> getCrossTUDefinitionImpl(const T *D,
213
                                                     StringRef CrossTUDir,
214
                                                     StringRef IndexName,
215
                                                     bool DisplayCTUProgress);
216
  template <typename T>
217
  const T *findDefInDeclContext(const DeclContext *DC,
218
                                StringRef LookupName);
219
  template <typename T>
220
  llvm::Expected<const T *> importDefinitionImpl(const T *D, ASTUnit *Unit);
221
222
  using ImporterMapTy =
223
      llvm::DenseMap<TranslationUnitDecl *, std::unique_ptr<ASTImporter>>;
224
225
  ImporterMapTy ASTUnitImporterMap;
226
227
  ASTContext &Context;
228
  std::shared_ptr<ASTImporterSharedState> ImporterSharedSt;
229
230
  using LoadResultTy = llvm::Expected<std::unique_ptr<ASTUnit>>;
231
232
  /// Loads ASTUnits from AST-dumps or source-files.
233
  class ASTLoader {
234
  public:
235
    ASTLoader(CompilerInstance &CI, StringRef CTUDir,
236
              StringRef InvocationListFilePath);
237
238
    /// Load the ASTUnit by its identifier found in the index file. If the
239
    /// identifier is suffixed with '.ast' it is considered a dump. Otherwise
240
    /// it is treated as source-file, and on-demand parsed. Relative paths are
241
    /// prefixed with CTUDir.
242
    LoadResultTy load(StringRef Identifier);
243
244
    /// Lazily initialize the invocation list information, which is needed for
245
    /// on-demand parsing.
246
    llvm::Error lazyInitInvocationList();
247
248
  private:
249
    /// The style used for storage and lookup of filesystem paths.
250
    /// Defaults to posix.
251
    const llvm::sys::path::Style PathStyle = llvm::sys::path::Style::posix;
252
253
    /// Loads an AST from a pch-dump.
254
    LoadResultTy loadFromDump(StringRef Identifier);
255
    /// Loads an AST from a source-file.
256
    LoadResultTy loadFromSource(StringRef Identifier);
257
258
    CompilerInstance &CI;
259
    StringRef CTUDir;
260
    /// The path to the file containing the invocation list, which is in YAML
261
    /// format, and contains a mapping from source files to compiler invocations
262
    /// that produce the AST used for analysis.
263
    StringRef InvocationListFilePath;
264
    /// In case of on-demand parsing, the invocations for parsing the source
265
    /// files is stored.
266
    llvm::Optional<InvocationListTy> InvocationList;
267
    index_error_code PreviousParsingResult = index_error_code::success;
268
  };
269
270
  /// Maintain number of AST loads and check for reaching the load limit.
271
  class ASTLoadGuard {
272
  public:
273
1.74k
    ASTLoadGuard(unsigned Limit) : Limit(Limit) {}
274
275
    /// Indicates, whether a new load operation is permitted, it is within the
276
    /// threshold.
277
27
    operator bool() const { return Count < Limit; }
278
279
    /// Tell that a new AST was loaded successfully.
280
26
    void indicateLoadSuccess() { ++Count; }
281
282
  private:
283
    /// The number of ASTs actually imported.
284
    unsigned Count{0u};
285
    /// The limit (threshold) value for number of loaded ASTs.
286
    const unsigned Limit;
287
  };
288
289
  /// Storage and load of ASTUnits, cached access, and providing searchability
290
  /// are the concerns of ASTUnitStorage class.
291
  class ASTUnitStorage {
292
  public:
293
    ASTUnitStorage(CompilerInstance &CI);
294
    /// Loads an ASTUnit for a function.
295
    ///
296
    /// \param FunctionName USR name of the function.
297
    /// \param CrossTUDir Path to the directory used to store CTU related files.
298
    /// \param IndexName Name of the file inside \p CrossTUDir which maps
299
    /// function USR names to file paths. These files contain the corresponding
300
    /// AST-dumps.
301
    /// \param DisplayCTUProgress Display a message about loading new ASTs.
302
    ///
303
    /// \return An Expected instance which contains the ASTUnit pointer or the
304
    /// error occurred during the load.
305
    llvm::Expected<ASTUnit *> getASTUnitForFunction(StringRef FunctionName,
306
                                                    StringRef CrossTUDir,
307
                                                    StringRef IndexName,
308
                                                    bool DisplayCTUProgress);
309
    /// Identifies the path of the file which can be used to load the ASTUnit
310
    /// for a given function.
311
    ///
312
    /// \param FunctionName USR name of the function.
313
    /// \param CrossTUDir Path to the directory used to store CTU related files.
314
    /// \param IndexName Name of the file inside \p CrossTUDir which maps
315
    /// function USR names to file paths. These files contain the corresponding
316
    /// AST-dumps.
317
    ///
318
    /// \return An Expected instance containing the filepath.
319
    llvm::Expected<std::string> getFileForFunction(StringRef FunctionName,
320
                                                   StringRef CrossTUDir,
321
                                                   StringRef IndexName);
322
323
  private:
324
    llvm::Error ensureCTUIndexLoaded(StringRef CrossTUDir, StringRef IndexName);
325
    llvm::Expected<ASTUnit *> getASTUnitForFile(StringRef FileName,
326
                                                bool DisplayCTUProgress);
327
328
    template <typename... T> using BaseMapTy = llvm::StringMap<T...>;
329
    using OwningMapTy = BaseMapTy<std::unique_ptr<clang::ASTUnit>>;
330
    using NonOwningMapTy = BaseMapTy<clang::ASTUnit *>;
331
332
    OwningMapTy FileASTUnitMap;
333
    NonOwningMapTy NameASTUnitMap;
334
335
    using IndexMapTy = BaseMapTy<std::string>;
336
    IndexMapTy NameFileMap;
337
338
    /// Loads the AST based on the identifier found in the index.
339
    ASTLoader Loader;
340
341
    /// Limit the number of loaded ASTs. It is used to limit the  memory usage
342
    /// of the CrossTranslationUnitContext. The ASTUnitStorage has the
343
    /// information whether the AST to load is actually loaded or returned from
344
    /// cache. This information is needed to maintain the counter.
345
    ASTLoadGuard LoadGuard;
346
  };
347
348
  ASTUnitStorage ASTStorage;
349
};
350
351
} // namespace cross_tu
352
} // namespace clang
353
354
#endif // LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H