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