clang-tools 10.0.0

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_CANCELLATION_H
58 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CANCELLATION_H
59
60 #include "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 false until the Canceler is
75 /// invoked, and true afterwards.
76 std::pair<Context, Canceler> cancelableTask();
77
78 /// True if the current context is within a cancelable task which was cancelled.
79 /// Always false if there is no active cancelable task.
80 /// This isn't free (context lookup) - don't call it in a tight loop.
81 bool isCancelled(const Context &Ctx = Context::current());
82
83 /// Conventional error when no result is returned due to cancellation.
84 class CancelledError : public llvm::ErrorInfo<CancelledError> {
85 public:
86 static char ID;
87
88 void log(llvm::raw_ostream &OS) const override {
89 OS << "Task was cancelled.";
90 }
91 std::error_code convertToErrorCode() const override {
92 return std::make_error_code(std::errc::operation_canceled);
93 }
94 };
95
96 } // namespace clangd
97 } // namespace clang
98
99 #endif
clang::clangd::CancelledError::ID
static char ID
Definition: Cancellation.h:86
clang::clangd::Canceler
std::function< void()> Canceler
A canceller requests cancellation of a task, when called.
Definition: Cancellation.h:70
clang::clangd::CancelledError::convertToErrorCode
std::error_code convertToErrorCode() const override
Definition: Cancellation.h:91
Context.h
clang::clangd::isCancelled
bool isCancelled(const Context &Ctx)
True if the current context is within a cancelable task which was cancelled.
Definition: Cancellation.cpp:26
Ctx
Context Ctx
Definition: TUScheduler.cpp:237
clang::clangd::CancelledError
Conventional error when no result is returned due to cancellation.
Definition: Cancellation.h:84
clang::clangd::Context::current
static const Context & current()
Returns the context for the current thread, creating it if needed.
Definition: Context.cpp:27
clang::clangd::CancelledError::log
void log(llvm::raw_ostream &OS) const override
Definition: Cancellation.h:88
clang::clangd::cancelableTask
std::pair< Context, Canceler > cancelableTask()
Defines a new task whose cancellation may be requested.
Definition: Cancellation.cpp:18
clang::clangd::Context
A context is an immutable container for per-request data that must be propagated through layers that ...
Definition: Context.h:69
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27