Debian Codegraph @

llvm-project/clang-tools-extra/clangd/ClangdServer.h

raw
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 "CodeComplete.h"
13 #include "ConfigProvider.h"
14 #include "Diagnostics.h"
15 #include "DraftStore.h"
16 #include "FeatureModule.h"
17 #include "GlobalCompilationDatabase.h"
18 #include "Hover.h"
19 #include "Protocol.h"
20 #include "SemanticHighlighting.h"
21 #include "TUScheduler.h"
22 #include "XRefs.h"
23 #include "index/Background.h"
24 #include "index/FileIndex.h"
25 #include "index/Index.h"
26 #include "refactor/Rename.h"
27 #include "refactor/Tweak.h"
28 #include "support/Function.h"
29 #include "support/MemoryTree.h"
30 #include "support/Path.h"
31 #include "support/ThreadsafeFS.h"
32 #include "clang/Tooling/Core/Replacement.h"
33 #include "llvm/ADT/FunctionExtras.h"
34 #include "llvm/ADT/StringRef.h"
35 #include <functional>
36 #include <memory>
37 #include <optional>
38 #include <string>
39 #include <type_traits>
40 #include <utility>
41 #include <vector>
42
43 namespace clang {
44 namespace clangd {
45 /// Manages a collection of source files and derived data (ASTs, indexes),
46 /// and provides language-aware features such as code completion.
47 ///
48 /// The primary client is ClangdLSPServer which exposes these features via
49 /// the Language Server protocol. ClangdServer may also be embedded directly,
50 /// though its API is not stable over time.
51 ///
52 /// ClangdServer should be used from a single thread. Many potentially-slow
53 /// operations have asynchronous APIs and deliver their results on another
54 /// thread.
55 /// Such operations support cancellation: if the caller sets up a cancelable
56 /// context, many operations will notice cancellation and fail early.
57 /// (ClangdLSPServer uses this to implement $/cancelRequest).
58 class ClangdServer {
59 public:
60 /// Interface with hooks for users of ClangdServer to be notified of events.
61 class Callbacks {
62 public:
63 virtual ~Callbacks() = default;
64
65 /// Called by ClangdServer when \p Diagnostics for \p File are ready.
66 /// These pushed diagnostics might correspond to an older version of the
67 /// file, they do not interfere with "pull-based" ClangdServer::diagnostics.
68 /// May be called concurrently for separate files, not for a single file.
69 virtual void onDiagnosticsReady(PathRef File, llvm::StringRef Version,
70 std::vector<Diag> Diagnostics) {}
71 /// Called whenever the file status is updated.
72 /// May be called concurrently for separate files, not for a single file.
73 virtual void onFileUpdated(PathRef File, const TUStatus &Status) {}
74
75 /// Called when background indexing tasks are enqueued/started/completed.
76 /// Not called concurrently.
77 virtual void
78 onBackgroundIndexProgress(const BackgroundQueue::Stats &Stats) {}
79
80 /// Called when the meaning of a source code may have changed without an
81 /// edit. Usually clients assume that responses to requests are valid until
82 /// they next edit the file. If they're invalidated at other times, we
83 /// should tell the client. In particular, when an asynchronous preamble
84 /// build finishes, we can provide more accurate semantic tokens, so we
85 /// should tell the client to refresh.
86 virtual void onSemanticsMaybeChanged(PathRef File) {}
87 };
88 /// Creates a context provider that loads and installs config.
89 /// Errors in loading config are reported as diagnostics via Callbacks.
90 /// (This is typically used as ClangdServer::Options::ContextProvider).
91 static std::function<Context(PathRef)>
92 createConfiguredContextProvider(const config::Provider *Provider,
93 ClangdServer::Callbacks *);
94
95 struct Options {
96 /// To process requests asynchronously, ClangdServer spawns worker threads.
97 /// If this is zero, no threads are spawned. All work is done on the calling
98 /// thread, and callbacks are invoked before "async" functions return.
99 unsigned AsyncThreadsCount = getDefaultAsyncThreadsCount();
100
101 /// AST caching policy. The default is to keep up to 3 ASTs in memory.
102 ASTRetentionPolicy RetentionPolicy;
103
104 /// Cached preambles are potentially large. If false, store them on disk.
105 bool StorePreamblesInMemory = true;
106
107 /// This throttler controls which preambles may be built at a given time.
108 clangd::PreambleThrottler *PreambleThrottler = nullptr;
109
110 /// If true, ClangdServer builds a dynamic in-memory index for symbols in
111 /// opened files and uses the index to augment code completion results.
112 bool BuildDynamicSymbolIndex = false;
113 /// If true, ClangdServer automatically indexes files in the current project
114 /// on background threads. The index is stored in the project root.
115 bool BackgroundIndex = false;
116 llvm::ThreadPriority BackgroundIndexPriority = llvm::ThreadPriority::Low;
117
118 /// If set, use this index to augment code completion results.
119 SymbolIndex *StaticIndex = nullptr;
120
121 /// If set, queried to derive a processing context for some work.
122 /// Usually used to inject Config (see createConfiguredContextProvider).
123 ///
124 /// When the provider is called, the active context will be that inherited
125 /// from the request (e.g. addDocument()), or from the ClangdServer
126 /// constructor if there is no such request (e.g. background indexing).
127 ///
128 /// The path is an absolute path of the file being processed.
129 /// If there is no particular file (e.g. project loading) then it is empty.
130 std::function<Context(PathRef)> ContextProvider;
131
132 /// The Options provider to use when running clang-tidy. If null, clang-tidy
133 /// checks will be disabled.
134 TidyProviderRef ClangTidyProvider;
135
136 /// Clangd's workspace root. Relevant for "workspace" operations not bound
137 /// to a particular file.
138 /// FIXME: If not set, should use the current working directory.
139 std::optional<std::string> WorkspaceRoot;
140
141 /// The resource directory is used to find internal headers, overriding
142 /// defaults and -resource-dir compiler flag).
143 /// If None, ClangdServer calls CompilerInvocation::GetResourcePath() to
144 /// obtain the standard resource directory.
145 std::optional<std::string> ResourceDir;
146
147 /// Time to wait after a new file version before computing diagnostics.
148 DebouncePolicy UpdateDebounce = DebouncePolicy{
149 /*Min=*/std::chrono::milliseconds(50),
150 /*Max=*/std::chrono::milliseconds(500),
151 /*RebuildRatio=*/1,
152 };
153
154 /// Cancel certain requests if the file changes before they begin running.
155 /// This is useful for "transient" actions like enumerateTweaks that were
156 /// likely implicitly generated, and avoids redundant work if clients forget
157 /// to cancel. Clients that always cancel stale requests should clear this.
158 bool ImplicitCancellation = true;
159
160 /// Clangd will execute compiler drivers matching one of these globs to
161 /// fetch system include path.
162 std::vector<std::string> QueryDriverGlobs;
163
164 // Whether the client supports folding only complete lines.
165 bool LineFoldingOnly = false;
166
167 FeatureModuleSet *FeatureModules = nullptr;
168 /// If true, use the dirty buffer contents when building Preambles.
169 bool UseDirtyHeaders = false;
170
171 // If true, parse emplace-like functions in the preamble.
172 bool PreambleParseForwardingFunctions = false;
173
174 /// Whether include fixer insertions for Objective-C code should use #import
175 /// instead of #include.
176 bool ImportInsertions = false;
177
178 explicit operator TUScheduler::Options() const;
179 };
180 // Sensible default options for use in tests.
181 // Features like indexing must be enabled if desired.
182 static Options optsForTest();
183
184 /// Creates a new ClangdServer instance.
185 ///
186 /// ClangdServer uses \p CDB to obtain compilation arguments for parsing. Note
187 /// that ClangdServer only obtains compilation arguments once for each newly
188 /// added file (i.e., when processing a first call to addDocument) and reuses
189 /// those arguments for subsequent reparses. However, ClangdServer will check
190 /// if compilation arguments changed on calls to forceReparse().
191 ClangdServer(const GlobalCompilationDatabase &CDB, const ThreadsafeFS &TFS,
192 const Options &Opts, Callbacks *Callbacks = nullptr);
193 ~ClangdServer();
194
195 /// Gets the installed feature module of a given type, if any.
196 /// This exposes access the public interface of feature modules that have one.
197 template <typename Mod> Mod *featureModule() {
198 return FeatureModules ? FeatureModules->get<Mod>() : nullptr;
199 }
200 template <typename Mod> const Mod *featureModule() const {
201 return FeatureModules ? FeatureModules->get<Mod>() : nullptr;
202 }
203
204 /// Add a \p File to the list of tracked C++ files or update the contents if
205 /// \p File is already tracked. Also schedules parsing of the AST for it on a
206 /// separate thread. When the parsing is complete, DiagConsumer passed in
207 /// constructor will receive onDiagnosticsReady callback.
208 /// Version identifies this snapshot and is propagated to ASTs, preambles,
209 /// diagnostics etc built from it. If empty, a version number is generated.
210 void addDocument(PathRef File, StringRef Contents,
211 llvm::StringRef Version = "null",
212 WantDiagnostics WD = WantDiagnostics::Auto,
213 bool ForceRebuild = false);
214
215 /// Remove \p File from list of tracked files, schedule a request to free
216 /// resources associated with it. Pending diagnostics for closed files may not
217 /// be delivered, even if requested with WantDiags::Auto or WantDiags::Yes.
218 /// An empty set of diagnostics will be delivered, with Version = "".
219 void removeDocument(PathRef File);
220
221 /// Requests a reparse of currently opened files using their latest source.
222 /// This will typically only rebuild if something other than the source has
223 /// changed (e.g. the CDB yields different flags, or files included in the
224 /// preamble have been modified).
225 void reparseOpenFilesIfNeeded(
226 llvm::function_ref<bool(llvm::StringRef File)> Filter);
227
228 /// Run code completion for \p File at \p Pos.
229 ///
230 /// This method should only be called for currently tracked files.
231 void codeComplete(PathRef File, Position Pos,
232 const clangd::CodeCompleteOptions &Opts,
233 Callback<CodeCompleteResult> CB);
234
235 /// Provide signature help for \p File at \p Pos. This method should only be
236 /// called for tracked files.
237 void signatureHelp(PathRef File, Position Pos, MarkupKind DocumentationFormat,
238 Callback<SignatureHelp> CB);
239
240 /// Find declaration/definition locations of symbol at a specified position.
241 void locateSymbolAt(PathRef File, Position Pos,
242 Callback<std::vector<LocatedSymbol>> CB);
243
244 /// Switch to a corresponding source file when given a header file, and vice
245 /// versa.
246 void switchSourceHeader(PathRef Path,
247 Callback<std::optional<clangd::Path>> CB);
248
249 /// Get document highlights for a given position.
250 void findDocumentHighlights(PathRef File, Position Pos,
251 Callback<std::vector<DocumentHighlight>> CB);
252
253 /// Get code hover for a given position.
254 void findHover(PathRef File, Position Pos,
255 Callback<std::optional<HoverInfo>> CB);
256
257 /// Get information about type hierarchy for a given position.
258 void typeHierarchy(PathRef File, Position Pos, int Resolve,
259 TypeHierarchyDirection Direction,
260 Callback<std::vector<TypeHierarchyItem>> CB);
261 /// Get direct parents of a type hierarchy item.
262 void superTypes(const TypeHierarchyItem &Item,
263 Callback<std::optional<std::vector<TypeHierarchyItem>>> CB);
264 /// Get direct children of a type hierarchy item.
265 void subTypes(const TypeHierarchyItem &Item,
266 Callback<std::vector<TypeHierarchyItem>> CB);
267
268 /// Resolve type hierarchy item in the given direction.
269 void resolveTypeHierarchy(TypeHierarchyItem Item, int Resolve,
270 TypeHierarchyDirection Direction,
271 Callback<std::optional<TypeHierarchyItem>> CB);
272
273 /// Get information about call hierarchy for a given position.
274 void prepareCallHierarchy(PathRef File, Position Pos,
275 Callback<std::vector<CallHierarchyItem>> CB);
276
277 /// Resolve incoming calls for a given call hierarchy item.
278 void incomingCalls(const CallHierarchyItem &Item,
279 Callback<std::vector<CallHierarchyIncomingCall>>);
280
281 /// Resolve inlay hints for a given document.
282 void inlayHints(PathRef File, std::optional<Range> RestrictRange,
283 Callback<std::vector<InlayHint>>);
284
285 /// Retrieve the top symbols from the workspace matching a query.
286 void workspaceSymbols(StringRef Query, int Limit,
287 Callback<std::vector<SymbolInformation>> CB);
288
289 /// Retrieve the symbols within the specified file.
290 void documentSymbols(StringRef File,
291 Callback<std::vector<DocumentSymbol>> CB);
292
293 /// Retrieve ranges that can be used to fold code within the specified file.
294 void foldingRanges(StringRef File, Callback<std::vector<FoldingRange>> CB);
295
296 /// Retrieve implementations for virtual method.
297 void findImplementations(PathRef File, Position Pos,
298 Callback<std::vector<LocatedSymbol>> CB);
299
300 /// Retrieve symbols for types referenced at \p Pos.
301 void findType(PathRef File, Position Pos,
302 Callback<std::vector<LocatedSymbol>> CB);
303
304 /// Retrieve locations for symbol references.
305 void findReferences(PathRef File, Position Pos, uint32_t Limit,
306 bool AddContainer, Callback<ReferencesResult> CB);
307
308 /// Run formatting for the \p File with content \p Code.
309 /// If \p Rng is non-null, formats only that region.
310 void formatFile(PathRef File, std::optional<Range> Rng,
311 Callback<tooling::Replacements> CB);
312
313 /// Run formatting after \p TriggerText was typed at \p Pos in \p File with
314 /// content \p Code.
315 void formatOnType(PathRef File, Position Pos, StringRef TriggerText,
316 Callback<std::vector<TextEdit>> CB);
317
318 /// Test the validity of a rename operation.
319 ///
320 /// If NewName is provided, it performs a name validation.
321 void prepareRename(PathRef File, Position Pos,
322 std::optional<std::string> NewName,
323 const RenameOptions &RenameOpts,
324 Callback<RenameResult> CB);
325
326 /// Rename all occurrences of the symbol at the \p Pos in \p File to
327 /// \p NewName.
328 /// If WantFormat is false, the final TextEdit will be not formatted,
329 /// embedders could use this method to get all occurrences of the symbol (e.g.
330 /// highlighting them in prepare stage).
331 void rename(PathRef File, Position Pos, llvm::StringRef NewName,
332 const RenameOptions &Opts, Callback<RenameResult> CB);
333
334 struct TweakRef {
335 std::string ID; /// ID to pass for applyTweak.
336 std::string Title; /// A single-line message to show in the UI.
337 llvm::StringLiteral Kind;
338 };
339 /// Enumerate the code tweaks available to the user at a specified point.
340 /// Tweaks where Filter returns false will not be checked or included.
341 void enumerateTweaks(PathRef File, Range Sel,
342 llvm::unique_function<bool(const Tweak &)> Filter,
343 Callback<std::vector<TweakRef>> CB);
344
345 /// Apply the code tweak with a specified \p ID.
346 void applyTweak(PathRef File, Range Sel, StringRef ID,
347 Callback<Tweak::Effect> CB);
348
349 /// Called when an event occurs for a watched file in the workspace.
350 void onFileEvent(const DidChangeWatchedFilesParams &Params);
351
352 /// Get symbol info for given position.
353 /// Clangd extension - not part of official LSP.
354 void symbolInfo(PathRef File, Position Pos,
355 Callback<std::vector<SymbolDetails>> CB);
356
357 /// Get semantic ranges around a specified position in a file.
358 void semanticRanges(PathRef File, const std::vector<Position> &Pos,
359 Callback<std::vector<SelectionRange>> CB);
360
361 /// Get all document links in a file.
362 void documentLinks(PathRef File, Callback<std::vector<DocumentLink>> CB);
363
364 void semanticHighlights(PathRef File,
365 Callback<std::vector<HighlightingToken>>);
366
367 /// Describe the AST subtree for a piece of code.
368 void getAST(PathRef File, std::optional<Range> R,
369 Callback<std::optional<ASTNode>> CB);
370
371 /// Runs an arbitrary action that has access to the AST of the specified file.
372 /// The action will execute on one of ClangdServer's internal threads.
373 /// The AST is only valid for the duration of the callback.
374 /// As with other actions, the file must have been opened.
375 void customAction(PathRef File, llvm::StringRef Name,
376 Callback<InputsAndAST> Action);
377
378 /// Fetches diagnostics for current version of the \p File. This might fail if
379 /// server is busy (building a preamble) and would require a long time to
380 /// prepare diagnostics. If it fails, clients should wait for
381 /// onSemanticsMaybeChanged and then retry.
382 /// These 'pulled' diagnostics do not interfere with the diagnostics 'pushed'
383 /// to Callbacks::onDiagnosticsReady, and clients may use either or both.
384 void diagnostics(PathRef File, Callback<std::vector<Diag>> CB);
385
386 /// Returns estimated memory usage and other statistics for each of the
387 /// currently open files.
388 /// Overall memory usage of clangd may be significantly more than reported
389 /// here, as this metric does not account (at least) for:
390 /// - memory occupied by static and dynamic index,
391 /// - memory required for in-flight requests,
392 /// FIXME: those metrics might be useful too, we should add them.
393 llvm::StringMap<TUScheduler::FileStats> fileStats() const;
394
395 /// Gets the contents of a currently tracked file. Returns nullptr if the file
396 /// isn't being tracked.
397 std::shared_ptr<const std::string> getDraft(PathRef File) const;
398
399 // Blocks the main thread until the server is idle. Only for use in tests.
400 // Returns false if the timeout expires.
401 // FIXME: various subcomponents each get the full timeout, so it's more of
402 // an order of magnitude than a hard deadline.
403 [[nodiscard]] bool
404 blockUntilIdleForTest(std::optional<double> TimeoutSeconds = 10);
405
406 /// Builds a nested representation of memory used by components.
407 void profile(MemoryTree &MT) const;
408
409 private:
410 FeatureModuleSet *FeatureModules;
411 const GlobalCompilationDatabase &CDB;
412 const ThreadsafeFS &getHeaderFS() const {
413 return UseDirtyHeaders ? *DirtyFS : TFS;
414 }
415 const ThreadsafeFS &TFS;
416
417 Path ResourceDir;
418 // The index used to look up symbols. This could be:
419 // - null (all index functionality is optional)
420 // - the dynamic index owned by ClangdServer (DynamicIdx)
421 // - the static index passed to the constructor
422 // - a merged view of a static and dynamic index (MergedIndex)
423 const SymbolIndex *Index = nullptr;
424 // If present, an index of symbols in open files. Read via *Index.
425 std::unique_ptr<FileIndex> DynamicIdx;
426 // If present, the new "auto-index" maintained in background threads.
427 std::unique_ptr<BackgroundIndex> BackgroundIdx;
428 // Storage for merged views of the various indexes.
429 std::vector<std::unique_ptr<SymbolIndex>> MergedIdx;
430
431 // When set, provides clang-tidy options for a specific file.
432 TidyProviderRef ClangTidyProvider;
433
434 bool UseDirtyHeaders = false;
435
436 // Whether the client supports folding only complete lines.
437 bool LineFoldingOnly = false;
438
439 bool PreambleParseForwardingFunctions = false;
440
441 bool ImportInsertions = false;
442
443 // GUARDED_BY(CachedCompletionFuzzyFindRequestMutex)
444 llvm::StringMap<std::optional<FuzzyFindRequest>>
445 CachedCompletionFuzzyFindRequestByFile;
446 mutable std::mutex CachedCompletionFuzzyFindRequestMutex;
447
448 std::optional<std::string> WorkspaceRoot;
449 std::optional<AsyncTaskRunner> IndexTasks; // for stdlib indexing.
450 std::optional<TUScheduler> WorkScheduler;
451 // Invalidation policy used for actions that we assume are "transient".
452 TUScheduler::ASTActionInvalidation Transient;
453
454 // Store of the current versions of the open documents.
455 // Only written from the main thread (despite being threadsafe).
456 DraftStore DraftMgr;
457
458 std::unique_ptr<ThreadsafeFS> DirtyFS;
459 };
460
461 } // namespace clangd
462 } // namespace clang
463
464 #endif