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