clang-tools  12.0.0git
Cancellation.h
Go to the documentation of this file.
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
std::function< void()> Canceler
A canceller requests cancellation of a task, when called.
Definition: Cancellation.h:70
std::error_code convertToErrorCode() const override
Definition: Cancellation.h:96
Context Ctx
std::pair< Context, Canceler > cancelableTask(int Reason)
Defines a new task whose cancellation may be requested.
llvm::raw_string_ostream OS
Definition: TraceTests.cpp:162
Conventional error when no result is returned due to cancellation.
Definition: Cancellation.h:86
static const Context & current()
Returns the context for the current thread, creating it if needed.
Definition: Context.cpp:27
void log(llvm::raw_ostream &OS) const override
Definition: Cancellation.h:93
A context is an immutable container for per-request data that must be propagated through layers that ...
Definition: Context.h:69
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
int isCancelled(const Context &Ctx)
If the current context is within a cancelled task, returns the reason.