clang-tools 10.0.0

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"
30 #include "index/CanonicalIncludes.h"
31 #include "clang/Frontend/PrecompiledPreamble.h"
32 #include "clang/Tooling/CompilationDatabase.h"
33
34 #include <memory>
35 #include <string>
36 #include <vector>
37
38 namespace clang {
39 namespace clangd {
40
41 /// The parsed preamble and associated data.
42 ///
43 /// As we must avoid re-parsing the preamble, any information that can only
44 /// be obtained during parsing must be eagerly captured and stored here.
45 struct PreambleData {
46 PreambleData(PrecompiledPreamble Preamble, std::vector<Diag> Diags,
47 IncludeStructure Includes, MainFileMacros Macros,
48 std::unique_ptr<PreambleFileStatusCache> StatCache,
49 CanonicalIncludes CanonIncludes);
50
51 tooling::CompileCommand CompileCommand;
52 PrecompiledPreamble Preamble;
53 std::vector<Diag> Diags;
54 // Processes like code completions and go-to-definitions will need #include
55 // information, and their compile action skips preamble range.
56 IncludeStructure Includes;
57 // Macros defined in the preamble section of the main file.
58 // Users care about headers vs main-file, not preamble vs non-preamble.
59 // These should be treated as main-file entities e.g. for code completion.
60 MainFileMacros Macros;
61 // Cache of FS operations performed when building the preamble.
62 // When reusing a preamble, this cache can be consumed to save IO.
63 std::unique_ptr<PreambleFileStatusCache> StatCache;
64 CanonicalIncludes CanonIncludes;
65 };
66
67 using PreambleParsedCallback =
68 std::function<void(ASTContext &, std::shared_ptr<clang::Preprocessor>,
69 const CanonicalIncludes &)>;
70
71 /// Build a preamble for the new inputs unless an old one can be reused.
72 /// If \p OldPreamble can be reused, it is returned unchanged.
73 /// If \p OldPreamble is null, always builds the preamble.
74 /// If \p PreambleCallback is set, it will be run on top of the AST while
75 /// building the preamble. Note that if the old preamble was reused, no AST is
76 /// built and, therefore, the callback will not be executed.
77 std::shared_ptr<const PreambleData>
78 buildPreamble(PathRef FileName, CompilerInvocation &CI,
79 std::shared_ptr<const PreambleData> OldPreamble,
80 const tooling::CompileCommand &OldCompileCommand,
81 const ParseInputs &Inputs, bool StoreInMemory,
82 PreambleParsedCallback PreambleCallback);
83
84
85 } // namespace clangd
86 } // namespace clang
87
88 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
clang::clangd::PreambleData::PreambleData
PreambleData(PrecompiledPreamble Preamble, std::vector< Diag > Diags, IncludeStructure Includes, MainFileMacros Macros, std::unique_ptr< PreambleFileStatusCache > StatCache, CanonicalIncludes CanonIncludes)
Definition: Preamble.cpp:78
clang::clangd::PreambleData::Macros
MainFileMacros Macros
Definition: Preamble.h:60
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:23
clang::clangd::IncludeStructure
Definition: Headers.h:109
clang::clangd::MainFileMacros
Definition: CollectMacros.h:24
Headers.h
CanonicalIncludes.h
clang::clangd::buildPreamble
std::shared_ptr< const PreambleData > buildPreamble(PathRef FileName, CompilerInvocation &CI, std::shared_ptr< const PreambleData > OldPreamble, const tooling::CompileCommand &OldCompileCommand, const ParseInputs &Inputs, bool StoreInMemory, PreambleParsedCallback PreambleCallback)
Build a preamble for the new inputs unless an old one can be reused.
Definition: Preamble.cpp:89
clang::clangd::CanonicalIncludes
Maps a definition location onto an #include file, based on a set of filename rules.
Definition: CanonicalIncludes.h:36
clang::clangd::PreambleData::CanonIncludes
CanonicalIncludes CanonIncludes
Definition: Preamble.h:64
clang::clangd::PreambleData::StatCache
std::unique_ptr< PreambleFileStatusCache > StatCache
Definition: Preamble.h:63
Compiler.h
Diagnostics.h
FileName
PathRef FileName
Definition: CodeComplete.cpp:1018
clang::clangd::PreambleParsedCallback
std::function< void(ASTContext &, std::shared_ptr< clang::Preprocessor >, const CanonicalIncludes &)> PreambleParsedCallback
Definition: Preamble.h:69
clang::clangd::PreambleData::CompileCommand
tooling::CompileCommand CompileCommand
Definition: Preamble.h:51
clang::clangd::ParseInputs
Information required to run clang, e.g. to parse AST or do code completion.
Definition: Compiler.h:44
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
CollectMacros.h
clang::clangd::PreambleData::Diags
std::vector< Diag > Diags
Definition: Preamble.h:53
clang::clangd::PreambleData::Preamble
PrecompiledPreamble Preamble
Definition: Preamble.h:52
clang::clangd::PreambleData::Includes
IncludeStructure Includes
Definition: Preamble.h:56
clang::clangd::PreambleData
The parsed preamble and associated data.
Definition: Preamble.h:45
FS.h