• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //===--- TUScheduler.h -------------------------------------------*-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_TUSCHEDULER_H
10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TUSCHEDULER_H
11 
12 #include "Compiler.h"
13 #include "Diagnostics.h"
14 #include "GlobalCompilationDatabase.h"
15 #include "index/CanonicalIncludes.h"
16 #include "support/Function.h"
17 #include "support/MemoryTree.h"
18 #include "support/Path.h"
19 #include "support/Threading.h"
20 #include "llvm/ADT/Optional.h"
21 #include "llvm/ADT/STLExtras.h"
22 #include "llvm/ADT/StringMap.h"
23 #include "llvm/ADT/StringRef.h"
24 #include <chrono>
25 
26 namespace clang {
27 namespace clangd {
28 class ParsedAST;
29 struct PreambleData;
30 
31 /// Returns a number of a default async threads to use for TUScheduler.
32 /// Returned value is always >= 1 (i.e. will not cause requests to be processed
33 /// synchronously).
34 unsigned getDefaultAsyncThreadsCount();
35 
36 struct InputsAndAST {
37   const ParseInputs &Inputs;
38   ParsedAST &AST;
39 };
40 
41 struct InputsAndPreamble {
42   llvm::StringRef Contents;
43   const tooling::CompileCommand &Command;
44   // This can be nullptr if no preamble is available.
45   const PreambleData *Preamble;
46 };
47 
48 /// Determines whether diagnostics should be generated for a file snapshot.
49 enum class WantDiagnostics {
50   Yes,  /// Diagnostics must be generated for this snapshot.
51   No,   /// Diagnostics must not be generated for this snapshot.
52   Auto, /// Diagnostics must be generated for this snapshot or a subsequent one,
53         /// within a bounded amount of time.
54 };
55 
56 /// Configuration of the AST retention policy. This only covers retention of
57 /// *idle* ASTs. If queue has operations requiring the AST, they might be
58 /// kept in memory.
59 struct ASTRetentionPolicy {
60   /// Maximum number of ASTs to be retained in memory when there are no pending
61   /// requests for them.
62   unsigned MaxRetainedASTs = 3;
63 };
64 
65 /// Clangd may wait after an update to see if another one comes along.
66 /// This is so we rebuild once the user stops typing, not when they start.
67 /// Debounce may be disabled/interrupted if we must build this version.
68 /// The debounce time is responsive to user preferences and rebuild time.
69 /// In the future, we could also consider different types of edits.
70 struct DebouncePolicy {
71   using clock = std::chrono::steady_clock;
72 
73   /// The minimum time that we always debounce for.
74   clock::duration Min = /*zero*/ {};
75   /// The maximum time we may debounce for.
76   clock::duration Max = /*zero*/ {};
77   /// Target debounce, as a fraction of file rebuild time.
78   /// e.g. RebuildRatio = 2, recent builds took 200ms => debounce for 400ms.
79   float RebuildRatio = 1;
80 
81   /// Compute the time to debounce based on this policy and recent build times.
82   clock::duration compute(llvm::ArrayRef<clock::duration> History) const;
83   /// A policy that always returns the same duration, useful for tests.
84   static DebouncePolicy fixed(clock::duration);
85 };
86 
87 enum class PreambleAction {
88   Idle,
89   Building,
90 };
91 
92 struct ASTAction {
93   enum Kind {
94     Queued,        // The action is pending in the thread task queue to be run.
95     RunningAction, // Started running actions on the TU.
96     Building,      // The AST is being built.
97     Idle, // Indicates the worker thread is idle, and ready to run any upcoming
98           // actions.
99   };
100   ASTAction() = default;
ASTActionASTAction101   ASTAction(Kind K, llvm::StringRef Name) : K(K), Name(Name) {}
102   Kind K = ASTAction::Idle;
103   /// The name of the action currently running, e.g. Update, GoToDef, Hover.
104   /// Empty if we are in the idle state.
105   std::string Name;
106 };
107 
108 // Internal status of the TU in TUScheduler.
109 struct TUStatus {
110   struct BuildDetails {
111     /// Indicates whether clang failed to build the TU.
112     bool BuildFailed = false;
113     /// Indicates whether we reused the prebuilt AST.
114     bool ReuseAST = false;
115   };
116   /// Serialize this to an LSP file status item.
117   FileStatus render(PathRef File) const;
118 
119   PreambleAction PreambleActivity = PreambleAction::Idle;
120   ASTAction ASTActivity;
121   /// Stores status of the last build for the translation unit.
122   BuildDetails Details;
123 };
124 
125 class ParsingCallbacks {
126 public:
127   virtual ~ParsingCallbacks() = default;
128 
129   /// Called on the AST that was built for emitting the preamble. The built AST
130   /// contains only AST nodes from the #include directives at the start of the
131   /// file. AST node in the current file should be observed on onMainAST call.
onPreambleAST(PathRef Path,llvm::StringRef Version,ASTContext & Ctx,std::shared_ptr<clang::Preprocessor> PP,const CanonicalIncludes &)132   virtual void onPreambleAST(PathRef Path, llvm::StringRef Version,
133                              ASTContext &Ctx,
134                              std::shared_ptr<clang::Preprocessor> PP,
135                              const CanonicalIncludes &) {}
136 
137   /// The argument function is run under the critical section guarding against
138   /// races when closing the files.
139   using PublishFn = llvm::function_ref<void(llvm::function_ref<void()>)>;
140   /// Called on the AST built for the file itself. Note that preamble AST nodes
141   /// are not deserialized and should be processed in the onPreambleAST call
142   /// instead.
143   /// The \p AST always contains all AST nodes for the main file itself, and
144   /// only a portion of the AST nodes deserialized from the preamble. Note that
145   /// some nodes from the preamble may have been deserialized and may also be
146   /// accessed from the main file AST, e.g. redecls of functions from preamble,
147   /// etc. Clients are expected to process only the AST nodes from the main file
148   /// in this callback (obtained via ParsedAST::getLocalTopLevelDecls) to obtain
149   /// optimal performance.
150   ///
151   /// When information about the file (diagnostics, syntax highlighting) is
152   /// published to clients, this should be wrapped in Publish, e.g.
153   ///   void onMainAST(...) {
154   ///     Highlights = computeHighlights();
155   ///     Publish([&] { notifyHighlights(Path, Highlights); });
156   ///   }
157   /// This guarantees that clients will see results in the correct sequence if
158   /// the file is concurrently closed and/or reopened. (The lambda passed to
159   /// Publish() may never run in this case).
onMainAST(PathRef Path,ParsedAST & AST,PublishFn Publish)160   virtual void onMainAST(PathRef Path, ParsedAST &AST, PublishFn Publish) {}
161 
162   /// Called whenever the AST fails to build. \p Diags will have the diagnostics
163   /// that led to failure.
onFailedAST(PathRef Path,llvm::StringRef Version,std::vector<Diag> Diags,PublishFn Publish)164   virtual void onFailedAST(PathRef Path, llvm::StringRef Version,
165                            std::vector<Diag> Diags, PublishFn Publish) {}
166 
167   /// Called whenever the TU status is updated.
onFileUpdated(PathRef File,const TUStatus & Status)168   virtual void onFileUpdated(PathRef File, const TUStatus &Status) {}
169 };
170 
171 /// Handles running tasks for ClangdServer and managing the resources (e.g.,
172 /// preambles and ASTs) for opened files.
173 /// TUScheduler is not thread-safe, only one thread should be providing updates
174 /// and scheduling tasks.
175 /// Callbacks are run on a threadpool and it's appropriate to do slow work in
176 /// them. Each task has a name, used for tracing (should be UpperCamelCase).
177 class TUScheduler {
178 public:
179   struct Options {
180     /// Number of concurrent actions.
181     /// Governs per-file worker threads and threads spawned for other tasks.
182     /// (This does not prevent threads being spawned, but rather blocks them).
183     /// If 0, executes actions synchronously on the calling thread.
184     unsigned AsyncThreadsCount = getDefaultAsyncThreadsCount();
185 
186     /// Cache (large) preamble data in RAM rather than temporary files on disk.
187     bool StorePreamblesInMemory = false;
188 
189     /// Time to wait after an update to see if another one comes along.
190     /// This tries to ensure we rebuild once the user stops typing.
191     DebouncePolicy UpdateDebounce;
192 
193     /// Determines when to keep idle ASTs in memory for future use.
194     ASTRetentionPolicy RetentionPolicy;
195 
196     /// Whether to run PreamblePeer asynchronously.
197     /// No-op if AsyncThreadsCount is 0.
198     bool AsyncPreambleBuilds = true;
199 
200     /// Used to create a context that wraps each single operation.
201     /// Typically to inject per-file configuration.
202     /// If the path is empty, context sholud be "generic".
203     std::function<Context(PathRef)> ContextProvider;
204   };
205 
206   TUScheduler(const GlobalCompilationDatabase &CDB, const Options &Opts,
207               std::unique_ptr<ParsingCallbacks> ASTCallbacks = nullptr);
208   ~TUScheduler();
209 
210   struct FileStats {
211     std::size_t UsedBytesAST = 0;
212     std::size_t UsedBytesPreamble = 0;
213     unsigned PreambleBuilds = 0;
214     unsigned ASTBuilds = 0;
215   };
216   /// Returns resources used for each of the currently open files.
217   /// Results are inherently racy as they measure activity of other threads.
218   llvm::StringMap<FileStats> fileStats() const;
219 
220   /// Returns a list of files with ASTs currently stored in memory. This method
221   /// is not very reliable and is only used for test. E.g., the results will not
222   /// contain files that currently run something over their AST.
223   std::vector<Path> getFilesWithCachedAST() const;
224 
225   /// Schedule an update for \p File.
226   /// The compile command in \p Inputs is ignored; worker queries CDB to get
227   /// the actual compile command.
228   /// If diagnostics are requested (Yes), and the context is cancelled
229   /// before they are prepared, they may be skipped if eventual-consistency
230   /// permits it (i.e. WantDiagnostics is downgraded to Auto).
231   /// Returns true if the file was not previously tracked.
232   bool update(PathRef File, ParseInputs Inputs, WantDiagnostics WD);
233 
234   /// Remove \p File from the list of tracked files and schedule removal of its
235   /// resources. Pending diagnostics for closed files may not be delivered, even
236   /// if requested with WantDiags::Auto or WantDiags::Yes.
237   void remove(PathRef File);
238 
239   /// Returns a snapshot of all file buffer contents, per last update().
240   llvm::StringMap<std::string> getAllFileContents() const;
241 
242   /// Schedule an async task with no dependencies.
243   /// Path may be empty (it is used only to set the Context).
244   void run(llvm::StringRef Name, llvm::StringRef Path,
245            llvm::unique_function<void()> Action);
246 
247   /// Defines how a runWithAST action is implicitly cancelled by other actions.
248   enum ASTActionInvalidation {
249     /// The request will run unless explicitly cancelled.
250     NoInvalidation,
251     /// The request will be implicitly cancelled by a subsequent update().
252     /// (Only if the request was not yet cancelled).
253     /// Useful for requests that are generated by clients, without any explicit
254     /// user action. These can otherwise e.g. force every version to be built.
255     InvalidateOnUpdate,
256   };
257 
258   /// Schedule an async read of the AST. \p Action will be called when AST is
259   /// ready. The AST passed to \p Action refers to the version of \p File
260   /// tracked at the time of the call, even if new updates are received before
261   /// \p Action is executed.
262   /// If an error occurs during processing, it is forwarded to the \p Action
263   /// callback.
264   /// If the context is cancelled before the AST is ready, or the invalidation
265   /// policy is triggered, the callback will receive a CancelledError.
266   void runWithAST(llvm::StringRef Name, PathRef File,
267                   Callback<InputsAndAST> Action,
268                   ASTActionInvalidation = NoInvalidation);
269 
270   /// Controls whether preamble reads wait for the preamble to be up-to-date.
271   enum PreambleConsistency {
272     /// The preamble may be generated from an older version of the file.
273     /// Reading from locations in the preamble may cause files to be re-read.
274     /// This gives callers two options:
275     /// - validate that the preamble is still valid, and only use it if so
276     /// - accept that the preamble contents may be outdated, and try to avoid
277     ///   reading source code from headers.
278     /// This is the fastest option, usually a preamble is available immediately.
279     Stale,
280     /// Besides accepting stale preamble, this also allow preamble to be absent
281     /// (not ready or failed to build).
282     StaleOrAbsent,
283   };
284 
285   /// Schedule an async read of the preamble.
286   /// If there's no up-to-date preamble, we follow the PreambleConsistency
287   /// policy.
288   /// If an error occurs, it is forwarded to the \p Action callback.
289   /// Context cancellation is ignored and should be handled by the Action.
290   /// (In practice, the Action is almost always executed immediately).
291   void runWithPreamble(llvm::StringRef Name, PathRef File,
292                        PreambleConsistency Consistency,
293                        Callback<InputsAndPreamble> Action);
294 
295   /// Wait until there are no scheduled or running tasks.
296   /// Mostly useful for synchronizing tests.
297   bool blockUntilIdle(Deadline D) const;
298 
299 private:
300   /// This class stores per-file data in the Files map.
301   struct FileData;
302 
303 public:
304   /// Responsible for retaining and rebuilding idle ASTs. An implementation is
305   /// an LRU cache.
306   class ASTCache;
307 
308   // The file being built/processed in the current thread. This is a hack in
309   // order to get the file name into the index implementations. Do not depend on
310   // this inside clangd.
311   // FIXME: remove this when there is proper index support via build system
312   // integration.
313   // FIXME: move to ClangdServer via createProcessingContext.
314   static llvm::Optional<llvm::StringRef> getFileBeingProcessedInContext();
315 
316   void profile(MemoryTree &MT) const;
317 
318 private:
319   const GlobalCompilationDatabase &CDB;
320   Options Opts;
321   std::unique_ptr<ParsingCallbacks> Callbacks; // not nullptr
322   Semaphore Barrier;
323   llvm::StringMap<std::unique_ptr<FileData>> Files;
324   std::unique_ptr<ASTCache> IdleASTs;
325   // None when running tasks synchronously and non-None when running tasks
326   // asynchronously.
327   llvm::Optional<AsyncTaskRunner> PreambleTasks;
328   llvm::Optional<AsyncTaskRunner> WorkerThreads;
329 };
330 
331 } // namespace clangd
332 } // namespace clang
333 
334 #endif
335