2021-03-04 23:21:01 +08:00
|
|
|
//===--- FeatureModule.h - Plugging features into clangd ----------*-C++-*-===//
|
2021-02-16 03:26:48 +08:00
|
|
|
//
|
|
|
|
// 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
|
|
|
|
//
|
|
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_FEATUREMODULE_H
|
|
|
|
#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_FEATUREMODULE_H
|
2021-02-07 02:11:00 +08:00
|
|
|
|
2021-02-15 17:41:38 +08:00
|
|
|
#include "support/Function.h"
|
2021-02-16 16:16:10 +08:00
|
|
|
#include "support/Threading.h"
|
2021-03-12 21:23:45 +08:00
|
|
|
#include "clang/Basic/Diagnostic.h"
|
2021-02-15 17:41:38 +08:00
|
|
|
#include "llvm/ADT/FunctionExtras.h"
|
2021-02-07 02:11:00 +08:00
|
|
|
#include "llvm/ADT/StringRef.h"
|
2021-02-16 04:43:11 +08:00
|
|
|
#include "llvm/Support/Compiler.h"
|
2021-02-13 04:16:41 +08:00
|
|
|
#include "llvm/Support/JSON.h"
|
2021-02-07 02:11:00 +08:00
|
|
|
#include <memory>
|
2021-02-16 04:43:11 +08:00
|
|
|
#include <type_traits>
|
2021-02-07 02:11:00 +08:00
|
|
|
#include <vector>
|
|
|
|
|
|
|
|
namespace clang {
|
|
|
|
namespace clangd {
|
2021-03-12 21:23:45 +08:00
|
|
|
struct Diag;
|
2021-02-16 03:26:48 +08:00
|
|
|
class LSPBinder;
|
|
|
|
class SymbolIndex;
|
|
|
|
class ThreadsafeFS;
|
|
|
|
class TUScheduler;
|
2021-03-12 19:27:19 +08:00
|
|
|
class Tweak;
|
2021-02-07 02:11:00 +08:00
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
/// A FeatureModule contributes a vertical feature to clangd.
|
2021-02-07 02:11:00 +08:00
|
|
|
///
|
|
|
|
/// The lifetime of a module is roughly:
|
2021-03-04 23:21:01 +08:00
|
|
|
/// - feature modules are created before the LSP server, in ClangdMain.cpp
|
|
|
|
/// - these modules are then passed to ClangdLSPServer in a FeatureModuleSet
|
2021-02-16 03:26:48 +08:00
|
|
|
/// - initializeLSP() is called when the editor calls initialize.
|
|
|
|
// - initialize() is then called by ClangdServer as it is constructed.
|
|
|
|
/// - module hooks can be called by the server at this point.
|
|
|
|
/// Server facilities (scheduler etc) are available.
|
2021-02-07 02:11:00 +08:00
|
|
|
/// - ClangdServer will not be destroyed until all the requests are done.
|
|
|
|
/// FIXME: Block server shutdown until all the modules are idle.
|
2021-02-16 16:16:10 +08:00
|
|
|
/// - When shutting down, ClangdServer will wait for all requests to
|
|
|
|
/// finish, call stop(), and then blockUntilIdle().
|
2021-03-04 23:21:01 +08:00
|
|
|
/// - feature modules will be destroyed after ClangdLSPServer is destroyed.
|
2021-02-07 02:11:00 +08:00
|
|
|
///
|
2021-03-04 23:21:01 +08:00
|
|
|
/// FeatureModules are not threadsafe in general. A module's entrypoints are:
|
2021-02-16 16:16:10 +08:00
|
|
|
/// - method handlers registered in initializeLSP()
|
2021-03-04 23:21:01 +08:00
|
|
|
/// - public methods called directly via ClangdServer.featureModule<T>()->...
|
|
|
|
/// - specific overridable "hook" methods inherited from FeatureModule
|
2021-02-16 16:16:10 +08:00
|
|
|
/// Unless otherwise specified, these are only called on the main thread.
|
|
|
|
///
|
2021-03-04 23:21:01 +08:00
|
|
|
/// Conventionally, standard feature modules live in the `clangd` namespace,
|
|
|
|
/// and other exposed details live in a sub-namespace.
|
|
|
|
class FeatureModule {
|
2021-02-07 02:11:00 +08:00
|
|
|
public:
|
2021-03-04 23:21:01 +08:00
|
|
|
virtual ~FeatureModule() {
|
2021-02-16 16:16:10 +08:00
|
|
|
/// Perform shutdown sequence on destruction in case the ClangdServer was
|
|
|
|
/// never initialized. Usually redundant, but shutdown is idempotent.
|
|
|
|
stop();
|
|
|
|
blockUntilIdle(Deadline::infinity());
|
|
|
|
}
|
2021-02-13 04:16:41 +08:00
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
/// Called by the server to connect this feature module to LSP.
|
2021-02-13 04:16:41 +08:00
|
|
|
/// The module should register the methods/notifications/commands it handles,
|
|
|
|
/// and update the server capabilities to advertise them.
|
|
|
|
///
|
|
|
|
/// This is only called if the module is running in ClangdLSPServer!
|
2021-03-04 23:21:01 +08:00
|
|
|
/// FeatureModules with a public interface should work without LSP bindings.
|
2021-02-13 04:16:41 +08:00
|
|
|
virtual void initializeLSP(LSPBinder &Bind,
|
2021-02-16 03:56:57 +08:00
|
|
|
const llvm::json::Object &ClientCaps,
|
2021-02-13 04:16:41 +08:00
|
|
|
llvm::json::Object &ServerCaps) {}
|
2021-02-16 03:26:48 +08:00
|
|
|
|
|
|
|
/// Shared server facilities needed by the module to get its work done.
|
|
|
|
struct Facilities {
|
|
|
|
TUScheduler &Scheduler;
|
|
|
|
const SymbolIndex *Index;
|
|
|
|
const ThreadsafeFS &FS;
|
|
|
|
};
|
|
|
|
/// Called by the server to prepare this module for use.
|
|
|
|
void initialize(const Facilities &F);
|
|
|
|
|
2021-02-16 16:16:10 +08:00
|
|
|
/// Requests that the module cancel background work and go idle soon.
|
|
|
|
/// Does not block, the caller will call blockUntilIdle() instead.
|
|
|
|
/// After a module is stop()ed, it should not receive any more requests.
|
|
|
|
/// Called by the server when shutting down.
|
|
|
|
/// May be called multiple times, should be idempotent.
|
|
|
|
virtual void stop() {}
|
|
|
|
|
|
|
|
/// Waits until the module is idle (no background work) or a deadline expires.
|
|
|
|
/// In general all modules should eventually go idle, though it may take a
|
|
|
|
/// long time (e.g. background indexing).
|
2021-03-04 23:21:01 +08:00
|
|
|
/// FeatureModules should go idle quickly if stop() has been called.
|
2021-02-16 16:16:10 +08:00
|
|
|
/// Called by the server when shutting down, and also by tests.
|
|
|
|
virtual bool blockUntilIdle(Deadline) { return true; }
|
|
|
|
|
2021-03-12 19:27:19 +08:00
|
|
|
/// Tweaks implemented by this module. Can be called asynchronously when
|
|
|
|
/// enumerating or applying code actions.
|
|
|
|
virtual void contributeTweaks(std::vector<std::unique_ptr<Tweak>> &Out) {}
|
|
|
|
|
2021-03-12 21:23:45 +08:00
|
|
|
/// Extension point that allows modules to observe and modify an AST build.
|
|
|
|
/// One instance is created each time clangd produces a ParsedAST or
|
|
|
|
/// PrecompiledPreamble. For a given instance, lifecycle methods are always
|
|
|
|
/// called on a single thread.
|
|
|
|
struct ASTListener {
|
|
|
|
/// Listeners are destroyed once the AST is built.
|
|
|
|
virtual ~ASTListener() = default;
|
|
|
|
|
|
|
|
/// Called everytime a diagnostic is encountered. Modules can use this
|
|
|
|
/// modify the final diagnostic, or store some information to surface code
|
|
|
|
/// actions later on.
|
|
|
|
virtual void sawDiagnostic(const clang::Diagnostic &, clangd::Diag &) {}
|
|
|
|
};
|
|
|
|
/// Can be called asynchronously before building an AST.
|
|
|
|
virtual std::unique_ptr<ASTListener> astListeners() { return nullptr; }
|
|
|
|
|
2021-02-16 03:26:48 +08:00
|
|
|
protected:
|
|
|
|
/// Accessors for modules to access shared server facilities they depend on.
|
|
|
|
Facilities &facilities();
|
|
|
|
/// The scheduler is used to run tasks on worker threads and access ASTs.
|
|
|
|
TUScheduler &scheduler() { return facilities().Scheduler; }
|
|
|
|
/// The index is used to get information about the whole codebase.
|
|
|
|
const SymbolIndex *index() { return facilities().Index; }
|
|
|
|
/// The filesystem is used to read source files on disk.
|
|
|
|
const ThreadsafeFS &fs() { return facilities().FS; }
|
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
/// Types of function objects that feature modules use for outgoing calls.
|
2021-02-15 17:41:38 +08:00
|
|
|
/// (Bound throuh LSPBinder, made available here for convenience).
|
|
|
|
template <typename P>
|
|
|
|
using OutgoingNotification = llvm::unique_function<void(const P &)>;
|
|
|
|
template <typename P, typename R>
|
|
|
|
using OutgoingMethod = llvm::unique_function<void(const P &, Callback<R>)>;
|
|
|
|
|
2021-02-16 03:26:48 +08:00
|
|
|
private:
|
|
|
|
llvm::Optional<Facilities> Fac;
|
2021-02-07 02:11:00 +08:00
|
|
|
};
|
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
/// A FeatureModuleSet is a collection of feature modules installed in clangd.
|
2021-02-16 04:43:11 +08:00
|
|
|
///
|
2021-03-04 23:21:01 +08:00
|
|
|
/// Modules can be looked up by type, or used via the FeatureModule interface.
|
2021-02-16 04:43:11 +08:00
|
|
|
/// This allows individual modules to expose a public API.
|
2021-03-04 23:21:01 +08:00
|
|
|
/// For this reason, there can be only one feature module of each type.
|
2021-02-16 04:43:11 +08:00
|
|
|
///
|
2021-03-04 23:21:01 +08:00
|
|
|
/// The set owns the modules. It is itself owned by main, not ClangdServer.
|
|
|
|
class FeatureModuleSet {
|
|
|
|
std::vector<std::unique_ptr<FeatureModule>> Modules;
|
|
|
|
llvm::DenseMap<void *, FeatureModule *> Map;
|
2021-02-16 04:43:11 +08:00
|
|
|
|
|
|
|
template <typename Mod> struct ID {
|
2021-03-04 23:21:01 +08:00
|
|
|
static_assert(std::is_base_of<FeatureModule, Mod>::value &&
|
2021-02-16 04:43:11 +08:00
|
|
|
std::is_final<Mod>::value,
|
|
|
|
"Modules must be final classes derived from clangd::Module");
|
|
|
|
static int Key;
|
|
|
|
};
|
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
bool addImpl(void *Key, std::unique_ptr<FeatureModule>, const char *Source);
|
2021-02-07 02:11:00 +08:00
|
|
|
|
|
|
|
public:
|
2021-03-04 23:21:01 +08:00
|
|
|
FeatureModuleSet() = default;
|
2021-02-07 02:11:00 +08:00
|
|
|
|
|
|
|
using iterator = llvm::pointee_iterator<decltype(Modules)::iterator>;
|
|
|
|
using const_iterator =
|
|
|
|
llvm::pointee_iterator<decltype(Modules)::const_iterator>;
|
|
|
|
iterator begin() { return iterator(Modules.begin()); }
|
|
|
|
iterator end() { return iterator(Modules.end()); }
|
|
|
|
const_iterator begin() const { return const_iterator(Modules.begin()); }
|
|
|
|
const_iterator end() const { return const_iterator(Modules.end()); }
|
2021-02-16 04:43:11 +08:00
|
|
|
|
|
|
|
template <typename Mod> bool add(std::unique_ptr<Mod> M) {
|
|
|
|
return addImpl(&ID<Mod>::Key, std::move(M), LLVM_PRETTY_FUNCTION);
|
|
|
|
}
|
|
|
|
template <typename Mod> Mod *get() {
|
|
|
|
return static_cast<Mod *>(Map.lookup(&ID<Mod>::Key));
|
|
|
|
}
|
|
|
|
template <typename Mod> const Mod *get() const {
|
2021-03-04 23:21:01 +08:00
|
|
|
return const_cast<FeatureModuleSet *>(this)->get<Mod>();
|
2021-02-16 04:43:11 +08:00
|
|
|
}
|
2021-02-07 02:11:00 +08:00
|
|
|
};
|
2021-02-16 04:43:11 +08:00
|
|
|
|
2021-03-04 23:21:01 +08:00
|
|
|
template <typename Mod> int FeatureModuleSet::ID<Mod>::Key;
|
2021-02-16 04:43:11 +08:00
|
|
|
|
2021-02-07 02:11:00 +08:00
|
|
|
} // namespace clangd
|
|
|
|
} // namespace clang
|
|
|
|
#endif
|