clang-tools  10.0.0svn
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 "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,
48  std::unique_ptr<PreambleFileStatusCache> StatCache,
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.
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.
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;
65 };
66 
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
PreambleData(PrecompiledPreamble Preamble, std::vector< Diag > Diags, IncludeStructure Includes, MainFileMacros Macros, std::unique_ptr< PreambleFileStatusCache > StatCache, CanonicalIncludes CanonIncludes)
Definition: Preamble.cpp:78
MainFileMacros Macros
Definition: Preamble.h:60
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:23
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
Maps a definition location onto an #include file, based on a set of filename rules.
CanonicalIncludes CanonIncludes
Definition: Preamble.h:64
std::unique_ptr< PreambleFileStatusCache > StatCache
Definition: Preamble.h:63
PathRef FileName
std::function< void(ASTContext &, std::shared_ptr< clang::Preprocessor >, const CanonicalIncludes &)> PreambleParsedCallback
Definition: Preamble.h:69
tooling::CompileCommand CompileCommand
Definition: Preamble.h:51
Information required to run clang, e.g. to parse AST or do code completion.
Definition: Compiler.h:44
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::vector< Diag > Diags
Definition: Preamble.h:53
PrecompiledPreamble Preamble
Definition: Preamble.h:52
IncludeStructure Includes
Definition: Preamble.h:56
The parsed preamble and associated data.
Definition: Preamble.h:45