clang-tools-extra/clangd/support/Cancellation.h

   1 //===--- Cancellation.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 // Cancellation mechanism for long-running tasks.
   9 //
  10 // This manages interactions between:
  11 //
  12 // 1. Client code that starts some long-running work, and maybe cancels later.
  13 //
  14 //   std::pair<Context, Canceler> Task = cancelableTask();
  15 //   {
  16 //     WithContext Cancelable(std::move(Task.first));
  17 //     Expected
  18 //     deepThoughtAsync([](int answer){ errs() << answer; });
  19 //   }
  20 //   // ...some time later...
  21 //   if (User.fellAsleep())
  22 //     Task.second();
  23 //
  24 //  (This example has an asynchronous computation, but synchronous examples
  25 //  work similarly - the Canceler should be invoked from another thread).
  26 //
  27 // 2. Library code that executes long-running work, and can exit early if the
  28 //   result is not needed.
  29 //
  30 //   void deepThoughtAsync(std::function<void(int)> Callback) {
  31 //     runAsync([Callback]{
  32 //       int A = ponder(6);
  33 //       if (isCancelled())
  34 //         return;
  35 //       int B = ponder(9);
  36 //       if (isCancelled())
  37 //         return;
  38 //       Callback(A * B);
  39 //     });
  40 //   }
  41 //
  42 //   (A real example may invoke the callback with an error on cancellation,
  43 //   the CancelledError is provided for this purpose).
  44 //
  45 // Cancellation has some caveats:
  46 //   - the work will only stop when/if the library code next checks for it.
  47 //     Code outside clangd such as Sema will not do this.
  48 //   - it's inherently racy: client code must be prepared to accept results
  49 //     even after requesting cancellation.
  50 //   - it's Context-based, so async work must be dispatched to threads in
  51 //     ways that preserve the context. (Like runAsync() or TUScheduler).
  52 //
  53 // FIXME: We could add timestamps to isCancelled() and CancelledError.
  54 //        Measuring the start -> cancel -> acknowledge -> finish timeline would
  55 //        help find where libraries' cancellation should be improved.
  56
  57 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_CANCELLATION_H
  58 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_CANCELLATION_H
  59
  60 #include "support/Context.h"
  61 #include "llvm/Support/Error.h"
  62 #include <functional>
  63 #include <system_error>
  64
  65 namespace clang {
  66 namespace clangd {
  67
  68 /// A canceller requests cancellation of a task, when called.
  69 /// Calling it again has no effect.
  70 using Canceler = std::function<void()>;
  71
  72 /// Defines a new task whose cancellation may be requested.
  73 /// The returned Context defines the scope of the task.
  74 /// When the context is active, isCancelled() is 0 until the Canceler is
  75 /// invoked, and equal to Reason afterwards.
  76 /// Conventionally, Reason may be the LSP error code to return.
  77 std::pair<Context, Canceler> cancelableTask(int Reason = 1);
  78
  79 /// If the current context is within a cancelled task, returns the reason.
  80 /// (If the context is within multiple nested tasks, true if any are cancelled).
  81 /// Always zero if there is no active cancelable task.
  82 /// This isn't free (context lookup) - don't call it in a tight loop.
  83 int isCancelled(const Context &Ctx = Context::current());
  84
  85 /// Conventional error when no result is returned due to cancellation.
  86 class CancelledError : public llvm::ErrorInfo<CancelledError> {
  87 public:
  88   static char ID;
  89   const int Reason;
  90
  91   CancelledError(int Reason) : Reason(Reason) {}
  92
  93   void log(llvm::raw_ostream &OS) const override {
  94     OS << "Task was cancelled.";
  95   }
  96   std::error_code convertToErrorCode() const override {
  97     return std::make_error_code(std::errc::operation_canceled);
  98   }
  99 };
 100
 101 } // namespace clangd
 102 } // namespace clang
 103
 104 #endif