clang-tools  16.0.0git
Preamble.h
Go to the documentation of this file.
1 //===--- Preamble.h - Reusing expensive parts of the AST ---------*- 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 // The vast majority of code in a typical translation unit is in the headers
10 // included at the top of the file.
11 //
12 // The preamble optimization says that we can parse this code once, and reuse
13 // the result multiple times. The preamble is invalidated by changes to the
14 // code in the preamble region, to the compile command, or to files on disk.
15 //
16 // This is the most important optimization in clangd: it allows operations like
17 // code-completion to have sub-second latency. It is supported by the
18 // PrecompiledPreamble functionality in clang, which wraps the techniques used
19 // by PCH files, modules etc into a convenient interface.
20 //
21 //===----------------------------------------------------------------------===//
22 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
23 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
24 
25 #include "CollectMacros.h"
26 #include "Compiler.h"
27 #include "Diagnostics.h"
28 #include "FS.h"
29 #include "Headers.h"
31 #include "support/Path.h"
32 #include "clang/Frontend/CompilerInvocation.h"
33 #include "clang/Frontend/PrecompiledPreamble.h"
34 #include "clang/Lex/Lexer.h"
35 #include "clang/Tooling/CompilationDatabase.h"
36 #include "llvm/ADT/StringRef.h"
37 
38 #include <memory>
39 #include <string>
40 #include <vector>
41 
42 namespace clang {
43 namespace clangd {
44 
45 /// The parsed preamble and associated data.
46 ///
47 /// As we must avoid re-parsing the preamble, any information that can only
48 /// be obtained during parsing must be eagerly captured and stored here.
49 struct PreambleData {
50  PreambleData(PrecompiledPreamble Preamble) : Preamble(std::move(Preamble)) {}
51 
52  // Version of the ParseInputs this preamble was built from.
53  std::string Version;
54  tooling::CompileCommand CompileCommand;
55  PrecompiledPreamble Preamble;
56  std::vector<Diag> Diags;
57  // Processes like code completions and go-to-definitions will need #include
58  // information, and their compile action skips preamble range.
60  // Macros defined in the preamble section of the main file.
61  // Users care about headers vs main-file, not preamble vs non-preamble.
62  // These should be treated as main-file entities e.g. for code completion.
64  // Pragma marks defined in the preamble section of the main file.
65  std::vector<PragmaMark> Marks;
66  // Cache of FS operations performed when building the preamble.
67  // When reusing a preamble, this cache can be consumed to save IO.
68  std::unique_ptr<PreambleFileStatusCache> StatCache;
70  // Whether there was a (possibly-incomplete) include-guard on the main file.
71  // We need to propagate this information "by hand" to subsequent parses.
72  bool MainIsIncludeGuarded = false;
73 };
74 
75 using PreambleParsedCallback = std::function<void(ASTContext &, Preprocessor &,
76  const CanonicalIncludes &)>;
77 
78 /// Timings and statistics from the premble build. Unlike PreambleData, these
79 /// do not need to be stored for later, but can be useful for logging, metrics,
80 /// etc.
82  /// Total wall time it took to build preamble, in seconds.
84  /// Time spent in filesystem operations during the build, in seconds.
86 
87  /// Estimate of the memory used while building the preamble.
88  /// This memory has been released when buildPreamble returns.
89  /// For example, this includes the size of the in-memory AST (ASTContext).
90  size_t BuildSize;
91  /// The serialized size of the preamble.
92  /// This storage is needed while the preamble is used (but may be on disk).
94 };
95 
96 /// Build a preamble for the new inputs unless an old one can be reused.
97 /// If \p PreambleCallback is set, it will be run on top of the AST while
98 /// building the preamble.
99 /// If Stats is not non-null, build statistics will be exported there.
100 std::shared_ptr<const PreambleData>
101 buildPreamble(PathRef FileName, CompilerInvocation CI,
102  const ParseInputs &Inputs, bool StoreInMemory,
103  PreambleParsedCallback PreambleCallback,
104  PreambleBuildStats *Stats = nullptr);
105 
106 /// Returns true if \p Preamble is reusable for \p Inputs. Note that it will
107 /// return true when some missing headers are now available.
108 /// FIXME: Should return more information about the delta between \p Preamble
109 /// and \p Inputs, e.g. new headers.
110 bool isPreambleCompatible(const PreambleData &Preamble,
112  const CompilerInvocation &CI);
113 
114 /// Stores information required to parse a TU using a (possibly stale) Baseline
115 /// preamble. Later on this information can be injected into the main file by
116 /// updating compiler invocation with \c apply. This injected section
117 /// approximately reflects additions to the preamble in Modified contents, e.g.
118 /// new include directives.
120 public:
121  enum class PatchType { MacroDirectives, All };
122  /// \p Preamble is used verbatim.
123  static PreamblePatch unmodified(const PreambleData &Preamble);
124  /// Builds a patch that contains new PP directives introduced to the preamble
125  /// section of \p Modified compared to \p Baseline.
126  /// FIXME: This only handles include directives, we should at least handle
127  /// define/undef.
128  static PreamblePatch createFullPatch(llvm::StringRef FileName,
129  const ParseInputs &Modified,
130  const PreambleData &Baseline);
131  static PreamblePatch createMacroPatch(llvm::StringRef FileName,
132  const ParseInputs &Modified,
133  const PreambleData &Baseline);
134 
135  /// Adjusts CI (which compiles the modified inputs) to be used with the
136  /// baseline preamble. This is done by inserting an artifical include to the
137  /// \p CI that contains new directives calculated in create.
138  void apply(CompilerInvocation &CI) const;
139 
140  /// Returns #include directives from the \c Modified preamble that were
141  /// resolved using the \c Baseline preamble. This covers the new locations of
142  /// inclusions that were moved around, but not inclusions of new files. Those
143  /// will be recorded when parsing the main file: the includes in the injected
144  /// section will be resolved back to their spelled positions in the main file
145  /// using the presumed-location mechanism.
146  std::vector<Inclusion> preambleIncludes() const;
147 
148  /// Returns preamble bounds for the Modified.
149  PreambleBounds modifiedBounds() const { return ModifiedBounds; }
150 
151  /// Returns textual patch contents.
152  llvm::StringRef text() const { return PatchContents; }
153 
154  /// Whether diagnostics generated using this patch are trustable.
155  bool preserveDiagnostics() const { return PatchContents.empty(); }
156 
157 private:
158  static PreamblePatch create(llvm::StringRef FileName,
159  const ParseInputs &Modified,
160  const PreambleData &Baseline,
162 
163  PreamblePatch() = default;
164  std::string PatchContents;
165  std::string PatchFileName;
166  /// Includes that are present in both \p Baseline and \p Modified. Used for
167  /// patching includes of baseline preamble.
168  std::vector<Inclusion> PreambleIncludes;
169  PreambleBounds ModifiedBounds = {0, false};
170 };
171 
172 /// Translates locations inside preamble patch to their main-file equivalent
173 /// using presumed locations. Returns \p Loc if it isn't inside preamble patch.
174 SourceLocation translatePreamblePatchLocation(SourceLocation Loc,
175  const SourceManager &SM);
176 
177 } // namespace clangd
178 } // namespace clang
179 
180 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
clang::clangd::buildPreamble
std::shared_ptr< const PreambleData > buildPreamble(PathRef FileName, CompilerInvocation CI, const ParseInputs &Inputs, bool StoreInMemory, PreambleParsedCallback PreambleCallback, PreambleBuildStats *Stats)
Build a preamble for the new inputs unless an old one can be reused.
Definition: Preamble.cpp:466
clang::clangd::PreambleData::MainIsIncludeGuarded
bool MainIsIncludeGuarded
Definition: Preamble.h:72
Loc
SourceLocation Loc
Definition: KernelNameRestrictionCheck.cpp:45
clang::clangd::PreambleData::StatCache
std::unique_ptr< PreambleFileStatusCache > StatCache
Definition: Preamble.h:68
clang::clangd::isPreambleCompatible
bool isPreambleCompatible(const PreambleData &Preamble, const ParseInputs &Inputs, PathRef FileName, const CompilerInvocation &CI)
Returns true if Preamble is reusable for Inputs.
Definition: Preamble.cpp:577
Headers.h
clang::clangd::PreamblePatch::text
llvm::StringRef text() const
Returns textual patch contents.
Definition: Preamble.h:152
Path.h
clang::clangd::PreambleData::Macros
MainFileMacros Macros
Definition: Preamble.h:63
clang::clangd::PreambleData::Preamble
PrecompiledPreamble Preamble
Definition: Preamble.h:55
CI
std::unique_ptr< CompilerInvocation > CI
Definition: TUScheduler.cpp:552
clang::clangd::PreamblePatch::unmodified
static PreamblePatch unmodified(const PreambleData &Preamble)
Preamble is used verbatim.
Definition: Preamble.cpp:741
clang::clangd::PreambleBuildStats::TotalBuildTime
double TotalBuildTime
Total wall time it took to build preamble, in seconds.
Definition: Preamble.h:83
clang::clangd::PreamblePatch
Stores information required to parse a TU using a (possibly stale) Baseline preamble.
Definition: Preamble.h:119
clang::clangd::PreambleBuildStats
Timings and statistics from the premble build.
Definition: Preamble.h:81
clang::clangd::PreambleData::Includes
IncludeStructure Includes
Definition: Preamble.h:59
clang::clangd::PreambleBuildStats::SerializedSize
size_t SerializedSize
The serialized size of the preamble.
Definition: Preamble.h:93
clang::clangd::IncludeStructure
Definition: Headers.h:119
Inputs
ParseInputs Inputs
Definition: TUScheduler.cpp:553
clang::clangd::PreambleData::Version
std::string Version
Definition: Preamble.h:53
clang::clangd::PreamblePatch::apply
void apply(CompilerInvocation &CI) const
Adjusts CI (which compiles the modified inputs) to be used with the baseline preamble.
Definition: Preamble.cpp:721
clang::clangd::ParseInputs
Information required to run clang, e.g. to parse AST or do code completion.
Definition: Compiler.h:46
CanonicalIncludes.h
clang::clangd::PreamblePatch::preserveDiagnostics
bool preserveDiagnostics() const
Whether diagnostics generated using this patch are trustable.
Definition: Preamble.h:155
clang::clangd::PreambleData
The parsed preamble and associated data.
Definition: Preamble.h:49
clang::clangd::CanonicalIncludes
Maps a definition location onto an #include file, based on a set of filename rules.
Definition: CanonicalIncludes.h:37
clang::clangd::PreambleBuildStats::FileSystemTime
double FileSystemTime
Time spent in filesystem operations during the build, in seconds.
Definition: Preamble.h:85
clang::clangd::PreamblePatch::createMacroPatch
static PreamblePatch createMacroPatch(llvm::StringRef FileName, const ParseInputs &Modified, const PreambleData &Baseline)
Definition: Preamble.cpp:715
clang::clangd::PreamblePatch::PatchType::MacroDirectives
@ MacroDirectives
clang::clangd::PreamblePatch::PatchType
PatchType
Definition: Preamble.h:121
CollectMacros.h
clang::clangd::MainFileMacros
Definition: CollectMacros.h:29
clang::clangd::PreambleData::Diags
std::vector< Diag > Diags
Definition: Preamble.h:56
Diagnostics.h
FileName
StringRef FileName
Definition: KernelNameRestrictionCheck.cpp:46
clang::clangd::PreambleData::Marks
std::vector< PragmaMark > Marks
Definition: Preamble.h:65
clang::clangd::PreambleData::CompileCommand
tooling::CompileCommand CompileCommand
Definition: Preamble.h:54
clang::clangd::PreamblePatch::modifiedBounds
PreambleBounds modifiedBounds() const
Returns preamble bounds for the Modified.
Definition: Preamble.h:149
Compiler.h
clang::clangd::PreamblePatch::createFullPatch
static PreamblePatch createFullPatch(llvm::StringRef FileName, const ParseInputs &Modified, const PreambleData &Baseline)
Builds a patch that contains new PP directives introduced to the preamble section of Modified compare...
Definition: Preamble.cpp:709
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:29
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
FS.h
clang::clangd::PreambleBuildStats::BuildSize
size_t BuildSize
Estimate of the memory used while building the preamble.
Definition: Preamble.h:90
clang::clangd::PreambleData::PreambleData
PreambleData(PrecompiledPreamble Preamble)
Definition: Preamble.h:50
clang::clangd::PreambleData::CanonIncludes
CanonicalIncludes CanonIncludes
Definition: Preamble.h:69
clang::clangd::PreambleParsedCallback
std::function< void(ASTContext &, Preprocessor &, const CanonicalIncludes &)> PreambleParsedCallback
Definition: Preamble.h:76
clang::clangd::PreamblePatch::preambleIncludes
std::vector< Inclusion > preambleIncludes() const
Returns #include directives from the Modified preamble that were resolved using the Baseline preamble...
Definition: Preamble.cpp:737
clang::clangd::PreamblePatch::PatchType::All
@ All
clang::clangd::translatePreamblePatchLocation
SourceLocation translatePreamblePatchLocation(SourceLocation Loc, const SourceManager &SM)
Translates locations inside preamble patch to their main-file equivalent using presumed locations.
Definition: Preamble.cpp:748