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