clang-tools
10.0.0
clang-tools-extra
clangd
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
Generated on Tue Mar 24 2020 13:06:33 for clang-tools by
1.8.13