Line data Source code
1 : //===--- TUScheduler.h -------------------------------------------*-C++-*-===//
2 : //
3 : // The LLVM Compiler Infrastructure
4 : //
5 : // This file is distributed under the University of Illinois Open Source
6 : // License. See LICENSE.TXT for details.
7 : //
8 : //===----------------------------------------------------------------------===//
9 :
10 : #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TUSCHEDULER_H
11 : #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TUSCHEDULER_H
12 :
13 : #include "ClangdUnit.h"
14 : #include "Function.h"
15 : #include "Threading.h"
16 : #include "llvm/ADT/StringMap.h"
17 : #include <future>
18 :
19 : namespace clang {
20 : namespace clangd {
21 :
22 : /// Returns a number of a default async threads to use for TUScheduler.
23 : /// Returned value is always >= 1 (i.e. will not cause requests to be processed
24 : /// synchronously).
25 : unsigned getDefaultAsyncThreadsCount();
26 :
27 : struct InputsAndAST {
28 : const ParseInputs &Inputs;
29 : ParsedAST &AST;
30 : };
31 :
32 : struct InputsAndPreamble {
33 : llvm::StringRef Contents;
34 : const tooling::CompileCommand &Command;
35 : const PreambleData *Preamble;
36 : };
37 :
38 : /// Determines whether diagnostics should be generated for a file snapshot.
39 : enum class WantDiagnostics {
40 : Yes, /// Diagnostics must be generated for this snapshot.
41 : No, /// Diagnostics must not be generated for this snapshot.
42 : Auto, /// Diagnostics must be generated for this snapshot or a subsequent one,
43 : /// within a bounded amount of time.
44 : };
45 :
46 : /// Configuration of the AST retention policy. This only covers retention of
47 : /// *idle* ASTs. If queue has operations requiring the AST, they might be
48 : /// kept in memory.
49 0 : struct ASTRetentionPolicy {
50 : /// Maximum number of ASTs to be retained in memory when there are no pending
51 : /// requests for them.
52 : unsigned MaxRetainedASTs = 3;
53 : };
54 :
55 : class ParsingCallbacks {
56 : public:
57 0 : virtual ~ParsingCallbacks() = default;
58 :
59 : /// Called on the AST that was built for emitting the preamble. The built AST
60 : /// contains only AST nodes from the #include directives at the start of the
61 : /// file. AST node in the current file should be observed on onMainAST call.
62 0 : virtual void onPreambleAST(PathRef Path, ASTContext &Ctx,
63 0 : std::shared_ptr<clang::Preprocessor> PP) {}
64 : /// Called on the AST built for the file itself. Note that preamble AST nodes
65 : /// are not deserialized and should be processed in the onPreambleAST call
66 : /// instead.
67 : /// The \p AST always contains all AST nodes for the main file itself, and
68 : /// only a portion of the AST nodes deserialized from the preamble. Note that
69 : /// some nodes from the preamble may have been deserialized and may also be
70 : /// accessed from the main file AST, e.g. redecls of functions from preamble,
71 : /// etc. Clients are expected to process only the AST nodes from the main file
72 : /// in this callback (obtained via ParsedAST::getLocalTopLevelDecls) to obtain
73 : /// optimal performance.
74 0 : virtual void onMainAST(PathRef Path, ParsedAST &AST) {}
75 : };
76 :
77 : /// Handles running tasks for ClangdServer and managing the resources (e.g.,
78 : /// preambles and ASTs) for opened files.
79 : /// TUScheduler is not thread-safe, only one thread should be providing updates
80 : /// and scheduling tasks.
81 : /// Callbacks are run on a threadpool and it's appropriate to do slow work in
82 : /// them. Each task has a name, used for tracing (should be UpperCamelCase).
83 : /// FIXME(sammccall): pull out a scheduler options struct.
84 : class TUScheduler {
85 : public:
86 : TUScheduler(unsigned AsyncThreadsCount, bool StorePreamblesInMemory,
87 : std::unique_ptr<ParsingCallbacks> ASTCallbacks,
88 : std::chrono::steady_clock::duration UpdateDebounce,
89 : ASTRetentionPolicy RetentionPolicy);
90 : ~TUScheduler();
91 :
92 : /// Returns estimated memory usage for each of the currently open files.
93 : /// The order of results is unspecified.
94 : std::vector<std::pair<Path, std::size_t>> getUsedBytesPerFile() const;
95 :
96 : /// Returns a list of files with ASTs currently stored in memory. This method
97 : /// is not very reliable and is only used for test. E.g., the results will not
98 : /// contain files that currently run something over their AST.
99 : std::vector<Path> getFilesWithCachedAST() const;
100 :
101 : /// Schedule an update for \p File. Adds \p File to a list of tracked files if
102 : /// \p File was not part of it before.
103 : /// FIXME(ibiryukov): remove the callback from this function.
104 : void update(PathRef File, ParseInputs Inputs, WantDiagnostics WD,
105 : llvm::unique_function<void(std::vector<Diag>)> OnUpdated);
106 :
107 : /// Remove \p File from the list of tracked files and schedule removal of its
108 : /// resources.
109 : void remove(PathRef File);
110 :
111 : /// Schedule an async read of the AST. \p Action will be called when AST is
112 : /// ready. The AST passed to \p Action refers to the version of \p File
113 : /// tracked at the time of the call, even if new updates are received before
114 : /// \p Action is executed.
115 : /// If an error occurs during processing, it is forwarded to the \p Action
116 : /// callback.
117 : void runWithAST(llvm::StringRef Name, PathRef File,
118 : Callback<InputsAndAST> Action);
119 :
120 : /// Controls whether preamble reads wait for the preamble to be up-to-date.
121 : enum PreambleConsistency {
122 : /// The preamble is generated from the current version of the file.
123 : /// If the content was recently updated, we will wait until we have a
124 : /// preamble that reflects that update.
125 : /// This is the slowest option, and may be delayed by other tasks.
126 : Consistent,
127 : /// The preamble may be generated from an older version of the file.
128 : /// Reading from locations in the preamble may cause files to be re-read.
129 : /// This gives callers two options:
130 : /// - validate that the preamble is still valid, and only use it if so
131 : /// - accept that the preamble contents may be outdated, and try to avoid
132 : /// reading source code from headers.
133 : /// This is the fastest option, usually a preamble is available immediately.
134 : Stale,
135 : };
136 : /// Schedule an async read of the preamble.
137 : /// If there's no preamble yet (because the file was just opened), we'll wait
138 : /// for it to build. The result may be null if it fails to build or is empty.
139 : /// If an error occurs, it is forwarded to the \p Action callback.
140 : void runWithPreamble(llvm::StringRef Name, PathRef File,
141 : PreambleConsistency Consistency,
142 : Callback<InputsAndPreamble> Action);
143 :
144 : /// Wait until there are no scheduled or running tasks.
145 : /// Mostly useful for synchronizing tests.
146 : bool blockUntilIdle(Deadline D) const;
147 :
148 : private:
149 : /// This class stores per-file data in the Files map.
150 : struct FileData;
151 :
152 : public:
153 : /// Responsible for retaining and rebuilding idle ASTs. An implementation is
154 : /// an LRU cache.
155 : class ASTCache;
156 :
157 : // The file being built/processed in the current thread. This is a hack in
158 : // order to get the file name into the index implementations. Do not depend on
159 : // this inside clangd.
160 : // FIXME: remove this when there is proper index support via build system
161 : // integration.
162 : static llvm::Optional<llvm::StringRef> getFileBeingProcessedInContext();
163 :
164 : private:
165 : const bool StorePreamblesInMemory;
166 : const std::shared_ptr<PCHContainerOperations> PCHOps;
167 : std::unique_ptr<ParsingCallbacks> Callbacks; // not nullptr
168 : Semaphore Barrier;
169 : llvm::StringMap<std::unique_ptr<FileData>> Files;
170 : std::unique_ptr<ASTCache> IdleASTs;
171 : // None when running tasks synchronously and non-None when running tasks
172 : // asynchronously.
173 : llvm::Optional<AsyncTaskRunner> PreambleTasks;
174 : llvm::Optional<AsyncTaskRunner> WorkerThreads;
175 : std::chrono::steady_clock::duration UpdateDebounce;
176 : };
177 :
178 : /// Runs \p Action asynchronously with a new std::thread. The context will be
179 : /// propagated.
180 : template <typename T>
181 : std::future<T> runAsync(llvm::unique_function<T()> Action) {
182 : return std::async(std::launch::async,
183 : [](llvm::unique_function<T()> &&Action, Context Ctx) {
184 : WithContext WithCtx(std::move(Ctx));
185 : return Action();
186 : },
187 : std::move(Action), Context::current().clone());
188 : }
189 :
190 : } // namespace clangd
191 : } // namespace clang
192 :
193 : #endif
|
