clang-tools-extra/clangd/TUScheduler.h

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