clang-tools 10.0.0

ClangdServer.h
Go to the documentation of this file.
1 //===--- ClangdServer.h - Main clangd server code ----------------*- 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 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDSERVER_H
10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDSERVER_H
11
12 #include "../clang-tidy/ClangTidyOptions.h"
13 #include "Cancellation.h"
14 #include "CodeComplete.h"
15 #include "FSProvider.h"
16 #include "FormattedString.h"
17 #include "Function.h"
18 #include "GlobalCompilationDatabase.h"
19 #include "Hover.h"
20 #include "Protocol.h"
21 #include "SemanticHighlighting.h"
22 #include "TUScheduler.h"
23 #include "XRefs.h"
24 #include "index/Background.h"
25 #include "index/FileIndex.h"
26 #include "index/Index.h"
27 #include "refactor/Rename.h"
28 #include "refactor/Tweak.h"
29 #include "clang/Tooling/CompilationDatabase.h"
30 #include "clang/Tooling/Core/Replacement.h"
31 #include "llvm/ADT/FunctionExtras.h"
32 #include "llvm/ADT/IntrusiveRefCntPtr.h"
33 #include "llvm/ADT/Optional.h"
34 #include "llvm/ADT/StringRef.h"
35 #include <functional>
36 #include <future>
37 #include <string>
38 #include <type_traits>
39 #include <utility>
40
41 namespace clang {
42 namespace clangd {
43
44 // FIXME: find a better name.
45 class DiagnosticsConsumer {
46 public:
47 virtual ~DiagnosticsConsumer() = default;
48
49 /// Called by ClangdServer when \p Diagnostics for \p File are ready.
50 virtual void onDiagnosticsReady(PathRef File,
51 std::vector<Diag> Diagnostics) = 0;
52 /// Called whenever the file status is updated.
53 virtual void onFileUpdated(PathRef File, const TUStatus &Status){};
54
55 /// Called by ClangdServer when some \p Highlightings for \p File are ready.
56 virtual void
57 onHighlightingsReady(PathRef File,
58 std::vector<HighlightingToken> Highlightings) {}
59 };
60
61 /// When set, used by ClangdServer to get clang-tidy options for each particular
62 /// file. Must be thread-safe. We use this instead of ClangTidyOptionsProvider
63 /// to allow reading tidy configs from the VFS used for parsing.
64 using ClangTidyOptionsBuilder = std::function<tidy::ClangTidyOptions(
65 llvm::vfs::FileSystem &, llvm::StringRef /*File*/)>;
66
67 /// Manages a collection of source files and derived data (ASTs, indexes),
68 /// and provides language-aware features such as code completion.
69 ///
70 /// The primary client is ClangdLSPServer which exposes these features via
71 /// the Language Server protocol. ClangdServer may also be embedded directly,
72 /// though its API is not stable over time.
73 ///
74 /// ClangdServer should be used from a single thread. Many potentially-slow
75 /// operations have asynchronous APIs and deliver their results on another
76 /// thread.
77 /// Such operations support cancellation: if the caller sets up a cancelable
78 /// context, many operations will notice cancellation and fail early.
79 /// (ClangdLSPServer uses this to implement $/cancelRequest).
80 class ClangdServer {
81 public:
82 struct Options {
83 /// To process requests asynchronously, ClangdServer spawns worker threads.
84 /// If this is zero, no threads are spawned. All work is done on the calling
85 /// thread, and callbacks are invoked before "async" functions return.
86 unsigned AsyncThreadsCount = getDefaultAsyncThreadsCount();
87
88 /// AST caching policy. The default is to keep up to 3 ASTs in memory.
89 ASTRetentionPolicy RetentionPolicy;
90
91 /// Cached preambles are potentially large. If false, store them on disk.
92 bool StorePreamblesInMemory = true;
93
94 /// If true, ClangdServer builds a dynamic in-memory index for symbols in
95 /// opened files and uses the index to augment code completion results.
96 bool BuildDynamicSymbolIndex = false;
97 /// Use a heavier and faster in-memory index implementation.
98 bool HeavyweightDynamicSymbolIndex = true;
99 /// If true, ClangdServer automatically indexes files in the current project
100 /// on background threads. The index is stored in the project root.
101 bool BackgroundIndex = false;
102
103 /// If set, use this index to augment code completion results.
104 SymbolIndex *StaticIndex = nullptr;
105
106 /// If set, enable clang-tidy in clangd and use to it get clang-tidy
107 /// configurations for a particular file.
108 /// Clangd supports only a small subset of ClangTidyOptions, these options
109 /// (Checks, CheckOptions) are about which clang-tidy checks will be
110 /// enabled.
111 ClangTidyOptionsBuilder GetClangTidyOptions;
112
113 /// Clangd's workspace root. Relevant for "workspace" operations not bound
114 /// to a particular file.
115 /// FIXME: If not set, should use the current working directory.
116 llvm::Optional<std::string> WorkspaceRoot;
117
118 /// The resource directory is used to find internal headers, overriding
119 /// defaults and -resource-dir compiler flag).
120 /// If None, ClangdServer calls CompilerInvocation::GetResourcePath() to
121 /// obtain the standard resource directory.
122 llvm::Optional<std::string> ResourceDir = llvm::None;
123
124 /// Time to wait after a new file version before computing diagnostics.
125 std::chrono::steady_clock::duration UpdateDebounce =
126 std::chrono::milliseconds(500);
127
128 bool SuggestMissingIncludes = false;
129
130 /// Clangd will execute compiler drivers matching one of these globs to
131 /// fetch system include path.
132 std::vector<std::string> QueryDriverGlobs;
133
134 /// Enable semantic highlighting features.
135 bool SemanticHighlighting = false;
136
137 /// Enable cross-file rename feature.
138 bool CrossFileRename = false;
139
140 /// Returns true if the tweak should be enabled.
141 std::function<bool(const Tweak &)> TweakFilter = [](const Tweak &T) {
142 return !T.hidden(); // only enable non-hidden tweaks.
143 };
144 };
145 // Sensible default options for use in tests.
146 // Features like indexing must be enabled if desired.
147 static Options optsForTest();
148
149 /// Creates a new ClangdServer instance.
150 ///
151 /// ClangdServer uses \p CDB to obtain compilation arguments for parsing. Note
152 /// that ClangdServer only obtains compilation arguments once for each newly
153 /// added file (i.e., when processing a first call to addDocument) and reuses
154 /// those arguments for subsequent reparses. However, ClangdServer will check
155 /// if compilation arguments changed on calls to forceReparse().
156 ///
157 /// After each parsing request finishes, ClangdServer reports diagnostics to
158 /// \p DiagConsumer. Note that a callback to \p DiagConsumer happens on a
159 /// worker thread. Therefore, instances of \p DiagConsumer must properly
160 /// synchronize access to shared state.
161 ClangdServer(const GlobalCompilationDatabase &CDB,
162 const FileSystemProvider &FSProvider,
163 DiagnosticsConsumer &DiagConsumer, const Options &Opts);
164
165 /// Add a \p File to the list of tracked C++ files or update the contents if
166 /// \p File is already tracked. Also schedules parsing of the AST for it on a
167 /// separate thread. When the parsing is complete, DiagConsumer passed in
168 /// constructor will receive onDiagnosticsReady callback.
169 void addDocument(PathRef File, StringRef Contents,
170 WantDiagnostics WD = WantDiagnostics::Auto);
171
172 /// Get the contents of \p File, which should have been added.
173 llvm::StringRef getDocument(PathRef File) const;
174
175 /// Remove \p File from list of tracked files, schedule a request to free
176 /// resources associated with it. Pending diagnostics for closed files may not
177 /// be delivered, even if requested with WantDiags::Auto or WantDiags::Yes.
178 void removeDocument(PathRef File);
179
180 /// Run code completion for \p File at \p Pos.
181 /// Request is processed asynchronously.
182 ///
183 /// This method should only be called for currently tracked files. However, it
184 /// is safe to call removeDocument for \p File after this method returns, even
185 /// while returned future is not yet ready.
186 /// A version of `codeComplete` that runs \p Callback on the processing thread
187 /// when codeComplete results become available.
188 void codeComplete(PathRef File, Position Pos,
189 const clangd::CodeCompleteOptions &Opts,
190 Callback<CodeCompleteResult> CB);
191
192 /// Provide signature help for \p File at \p Pos. This method should only be
193 /// called for tracked files.
194 void signatureHelp(PathRef File, Position Pos, Callback<SignatureHelp> CB);
195
196 /// Find declaration/definition locations of symbol at a specified position.
197 void locateSymbolAt(PathRef File, Position Pos,
198 Callback<std::vector<LocatedSymbol>> CB);
199
200 /// Switch to a corresponding source file when given a header file, and vice
201 /// versa.
202 void switchSourceHeader(PathRef Path,
203 Callback<llvm::Optional<clangd::Path>> CB);
204
205 /// Get document highlights for a given position.
206 void findDocumentHighlights(PathRef File, Position Pos,
207 Callback<std::vector<DocumentHighlight>> CB);
208
209 /// Get code hover for a given position.
210 void findHover(PathRef File, Position Pos,
211 Callback<llvm::Optional<HoverInfo>> CB);
212
213 /// Get information about type hierarchy for a given position.
214 void typeHierarchy(PathRef File, Position Pos, int Resolve,
215 TypeHierarchyDirection Direction,
216 Callback<llvm::Optional<TypeHierarchyItem>> CB);
217
218 /// Resolve type hierarchy item in the given direction.
219 void resolveTypeHierarchy(TypeHierarchyItem Item, int Resolve,
220 TypeHierarchyDirection Direction,
221 Callback<llvm::Optional<TypeHierarchyItem>> CB);
222
223 /// Retrieve the top symbols from the workspace matching a query.
224 void workspaceSymbols(StringRef Query, int Limit,
225 Callback<std::vector<SymbolInformation>> CB);
226
227 /// Retrieve the symbols within the specified file.
228 void documentSymbols(StringRef File,
229 Callback<std::vector<DocumentSymbol>> CB);
230
231 /// Retrieve locations for symbol references.
232 void findReferences(PathRef File, Position Pos, uint32_t Limit,
233 Callback<ReferencesResult> CB);
234
235 /// Run formatting for \p Rng inside \p File with content \p Code.
236 llvm::Expected<tooling::Replacements> formatRange(StringRef Code,
237 PathRef File, Range Rng);
238
239 /// Run formatting for the whole \p File with content \p Code.
240 llvm::Expected<tooling::Replacements> formatFile(StringRef Code,
241 PathRef File);
242
243 /// Run formatting after \p TriggerText was typed at \p Pos in \p File with
244 /// content \p Code.
245 llvm::Expected<std::vector<TextEdit>> formatOnType(StringRef Code,
246 PathRef File, Position Pos,
247 StringRef TriggerText);
248
249 /// Test the validity of a rename operation.
250 void prepareRename(PathRef File, Position Pos,
251 Callback<llvm::Optional<Range>> CB);
252
253 /// Rename all occurrences of the symbol at the \p Pos in \p File to
254 /// \p NewName.
255 /// If WantFormat is false, the final TextEdit will be not formatted,
256 /// embedders could use this method to get all occurrences of the symbol (e.g.
257 /// highlighting them in prepare stage).
258 void rename(PathRef File, Position Pos, llvm::StringRef NewName,
259 bool WantFormat, Callback<FileEdits> CB);
260
261 struct TweakRef {
262 std::string ID; /// ID to pass for applyTweak.
263 std::string Title; /// A single-line message to show in the UI.
264 Tweak::Intent Intent;
265 };
266 /// Enumerate the code tweaks available to the user at a specified point.
267 void enumerateTweaks(PathRef File, Range Sel,
268 Callback<std::vector<TweakRef>> CB);
269
270 /// Apply the code tweak with a specified \p ID.
271 void applyTweak(PathRef File, Range Sel, StringRef ID,
272 Callback<Tweak::Effect> CB);
273
274 /// Only for testing purposes.
275 /// Waits until all requests to worker thread are finished and dumps AST for
276 /// \p File. \p File must be in the list of added documents.
277 void dumpAST(PathRef File, llvm::unique_function<void(std::string)> Callback);
278 /// Called when an event occurs for a watched file in the workspace.
279 void onFileEvent(const DidChangeWatchedFilesParams &Params);
280
281 /// Get symbol info for given position.
282 /// Clangd extension - not part of official LSP.
283 void symbolInfo(PathRef File, Position Pos,
284 Callback<std::vector<SymbolDetails>> CB);
285
286 /// Get semantic ranges around a specified position in a file.
287 void semanticRanges(PathRef File, Position Pos,
288 Callback<std::vector<Range>> CB);
289
290 /// Get all document links in a file.
291 void documentLinks(PathRef File, Callback<std::vector<DocumentLink>> CB);
292
293 /// Returns estimated memory usage for each of the currently open files.
294 /// The order of results is unspecified.
295 /// Overall memory usage of clangd may be significantly more than reported
296 /// here, as this metric does not account (at least) for:
297 /// - memory occupied by static and dynamic index,
298 /// - memory required for in-flight requests,
299 /// FIXME: those metrics might be useful too, we should add them.
300 std::vector<std::pair<Path, std::size_t>> getUsedBytesPerFile() const;
301
302 // Blocks the main thread until the server is idle. Only for use in tests.
303 // Returns false if the timeout expires.
304 LLVM_NODISCARD bool
305 blockUntilIdleForTest(llvm::Optional<double> TimeoutSeconds = 10);
306
307 private:
308 /// FIXME: This stats several files to find a .clang-format file. I/O can be
309 /// slow. Think of a way to cache this.
310 llvm::Expected<tooling::Replacements>
311 formatCode(llvm::StringRef Code, PathRef File,
312 ArrayRef<tooling::Range> Ranges);
313
314 const FileSystemProvider &FSProvider;
315
316 Path ResourceDir;
317 // The index used to look up symbols. This could be:
318 // - null (all index functionality is optional)
319 // - the dynamic index owned by ClangdServer (DynamicIdx)
320 // - the static index passed to the constructor
321 // - a merged view of a static and dynamic index (MergedIndex)
322 const SymbolIndex *Index = nullptr;
323 // If present, an index of symbols in open files. Read via *Index.
324 std::unique_ptr<FileIndex> DynamicIdx;
325 // If present, the new "auto-index" maintained in background threads.
326 std::unique_ptr<BackgroundIndex> BackgroundIdx;
327 // Storage for merged views of the various indexes.
328 std::vector<std::unique_ptr<SymbolIndex>> MergedIdx;
329
330 // When set, provides clang-tidy options for a specific file.
331 ClangTidyOptionsBuilder GetClangTidyOptions;
332
333 // If this is true, suggest include insertion fixes for diagnostic errors that
334 // can be caused by missing includes (e.g. member access in incomplete type).
335 bool SuggestMissingIncludes = false;
336
337 bool CrossFileRename = false;
338
339 std::function<bool(const Tweak &)> TweakFilter;
340
341 // GUARDED_BY(CachedCompletionFuzzyFindRequestMutex)
342 llvm::StringMap<llvm::Optional<FuzzyFindRequest>>
343 CachedCompletionFuzzyFindRequestByFile;
344 mutable std::mutex CachedCompletionFuzzyFindRequestMutex;
345
346 llvm::Optional<std::string> WorkspaceRoot;
347 // WorkScheduler has to be the last member, because its destructor has to be
348 // called before all other members to stop the worker thread that references
349 // ClangdServer.
350 TUScheduler WorkScheduler;
351 };
352
353 } // namespace clangd
354 } // namespace clang
355
356 #endif
Limit
int Limit
Definition: FindSymbolsTests.cpp:71
FormattedString.h
Code
std::string Code
Definition: FindTargetTests.cpp:67
clang::clangd::WantDiagnostics
WantDiagnostics
Determines whether diagnostics should be generated for a file snapshot.
Definition: TUScheduler.h:47
Contents
llvm::StringRef Contents
Definition: CodeComplete.cpp:1021
Index.h
SemanticHighlighting.h
clang::clangd::dumpAST
void dumpAST(ParsedAST &AST, llvm::raw_ostream &OS)
For testing/debugging purposes.
Definition: ParsedAST.cpp:213
clang::clangd::resolveTypeHierarchy
void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels, TypeHierarchyDirection Direction, const SymbolIndex *Index)
Definition: XRefs.cpp:807
clang::clangd::DidChangeWatchedFilesParams
Definition: Protocol.h:583
clang::clangd::Tweak::Intent
Intent
Output of a tweak.
Definition: Tweak.h:71
clang::clangd::ClangdServer::TweakRef
Definition: ClangdServer.h:261
clang::clangd::SymbolIndex
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:85
Hover.h
Protocol.h
clang::clangd::Position
Definition: Protocol.h:127
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:23
clang::clangd::Callback
llvm::unique_function< void(llvm::Expected< T >)> Callback
A Callback<T> is a void function that accepts Expected<T>.
Definition: Function.h:28
clang::tidy::ClangTidyOptions
Contains options for clang-tidy.
Definition: ClangTidyOptions.h:50
clang::clangd::findReferences
ReferencesResult findReferences(ParsedAST &AST, Position Pos, uint32_t Limit, const SymbolIndex *Index)
Returns references of the symbol at a specified Pos.
Definition: XRefs.cpp:423
clang::clangd::ClangdServer::TweakRef::Intent
Tweak::Intent Intent
A single-line message to show in the UI.
Definition: ClangdServer.h:264
clang::clangd::TextDocumentSyncKind::None
Documents should not be synced at all.
clang::clangd::ClangdServer::Options::RetentionPolicy
ASTRetentionPolicy RetentionPolicy
AST caching policy. The default is to keep up to 3 ASTs in memory.
Definition: ClangdServer.h:89
clang::clangd::FileSystemProvider
Definition: FSProvider.h:20
GlobalCompilationDatabase.h
FSProvider
MockFSProvider FSProvider
Definition: FindSymbolsTests.cpp:67
clang::clangd::ASTRetentionPolicy
Configuration of the AST retention policy.
Definition: TUScheduler.h:57
clang::clangd::ClangdServer::TweakRef::Title
std::string Title
ID to pass for applyTweak.
Definition: ClangdServer.h:263
clang::clangd::signatureHelp
SignatureHelp signatureHelp(PathRef FileName, const tooling::CompileCommand &Command, const PreambleData *Preamble, llvm::StringRef Contents, Position Pos, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, const SymbolIndex *Index)
Definition: CodeComplete.cpp:1749
Cancellation.h
Tweak.h
clang::clangd::GlobalCompilationDatabase
Provides compilation arguments used for parsing C and C++ files.
Definition: GlobalCompilationDatabase.h:35
clang::clangd::Range
Definition: Protocol.h:156
clang::clangd::BackgroundIndex
Definition: Background.h:115
CodeComplete.h
clang::clangd::Path
std::string Path
A typedef to represent a file path.
Definition: Path.h:20
clang::clangd::DiagnosticsConsumer::onDiagnosticsReady
virtual void onDiagnosticsReady(PathRef File, std::vector< Diag > Diagnostics)=0
Called by ClangdServer when Diagnostics for File are ready.
clang::clangd::DiagnosticsConsumer::~DiagnosticsConsumer
virtual ~DiagnosticsConsumer()=default
clang::clangd::CodeCompleteOptions
Definition: CodeComplete.h:39
clang::clangd::ClangTidyOptionsBuilder
std::function< tidy::ClangTidyOptions(llvm::vfs::FileSystem &, llvm::StringRef)> ClangTidyOptionsBuilder
When set, used by ClangdServer to get clang-tidy options for each particular file.
Definition: ClangdServer.h:65
clang::clangd::TUStatus
Definition: TUScheduler.h:81
Pos
Position Pos
Definition: SourceCode.cpp:772
clang::clangd::findDocumentHighlights
std::vector< DocumentHighlight > findDocumentHighlights(ParsedAST &AST, Position Pos)
Returns highlights for all usages of a symbol at Pos.
Definition: XRefs.cpp:390
clang::clangd::ClangdServer::Options::WorkspaceRoot
llvm::Optional< std::string > WorkspaceRoot
Clangd&#39;s workspace root.
Definition: ClangdServer.h:116
clang::clangd::codeComplete
CodeCompleteResult codeComplete(PathRef FileName, const tooling::CompileCommand &Command, const PreambleData *Preamble, llvm::StringRef Contents, Position Pos, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, CodeCompleteOptions Opts, SpeculativeFuzzyFind *SpecFuzzyFind)
Definition: CodeComplete.cpp:1731
clang::clangd::getDefaultAsyncThreadsCount
unsigned getDefaultAsyncThreadsCount()
Returns a number of a default async threads to use for TUScheduler.
Definition: TUScheduler.cpp:826
clang::clangd::DiagnosticsConsumer
Definition: ClangdServer.h:45
Background.h
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
Function.h
clang::clangd::ClangdServer::Options::QueryDriverGlobs
std::vector< std::string > QueryDriverGlobs
Clangd will execute compiler drivers matching one of these globs to fetch system include path...
Definition: ClangdServer.h:132
FSProvider.h
clang::clangd::Tweak
An interface base for small context-sensitive refactoring actions.
Definition: Tweak.h:46
DiagConsumer
IgnoreDiagnostics DiagConsumer
Definition: FindSymbolsTests.cpp:69
clang::clangd::ClangdServer
Manages a collection of source files and derived data (ASTs, indexes), and provides language-aware fe...
Definition: ClangdServer.h:80
clang::clangd::locateSymbolAt
std::vector< LocatedSymbol > locateSymbolAt(ParsedAST &AST, Position Pos, const SymbolIndex *Index)
Get definition of symbol at a specified Pos.
Definition: XRefs.cpp:190
clang::clangd::ClangdServer::Options::GetClangTidyOptions
ClangTidyOptionsBuilder GetClangTidyOptions
If set, enable clang-tidy in clangd and use to it get clang-tidy configurations for a particular file...
Definition: ClangdServer.h:111
clang::clangd::TUScheduler
Handles running tasks for ClangdServer and managing the resources (e.g., preambles and ASTs) for open...
Definition: TUScheduler.h:147
FileIndex.h
Rename.h
clang::clangd::rename
llvm::Expected< FileEdits > rename(const RenameInputs &RInputs)
Renames all occurrences of the symbol.
Definition: Rename.cpp:427
clang::clangd::ClangdServer::Options
Definition: ClangdServer.h:82
clang::clangd::ClangdServer::TweakRef::ID
std::string ID
Definition: ClangdServer.h:262
clang::clangd::CompletionItemKind::File
clang::clangd::WantDiagnostics::Auto
Diagnostics must not be generated for this snapshot.
TUScheduler.h
clang::clangd::DiagnosticsConsumer::onHighlightingsReady
virtual void onHighlightingsReady(PathRef File, std::vector< HighlightingToken > Highlightings)
Called by ClangdServer when some Highlightings for File are ready.
Definition: ClangdServer.h:57
XRefs.h
clang::clangd::TypeHierarchyDirection
TypeHierarchyDirection
Definition: Protocol.h:1121
clang::clangd::DiagnosticsConsumer::onFileUpdated
virtual void onFileUpdated(PathRef File, const TUStatus &Status)
Called whenever the file status is updated.
Definition: ClangdServer.h:53
Index
const SymbolIndex * Index
Definition: Dexp.cpp:84
clang::clangd::TypeHierarchyItem
Definition: Protocol.h:1136