A FeatureModule contributes a vertical feature to clangd. More...

#include <FeatureModule.h>

Classes
struct	ASTListener
	Extension point that allows modules to observe and modify an AST build. More...

struct	Facilities
	Shared server facilities needed by the module to get its work done. More...

Public Member Functions
virtual	~FeatureModule ()

virtual void	initializeLSP (LSPBinder &Bind, const llvm::json::Object &ClientCaps, llvm::json::Object &ServerCaps)
	Called by the server to connect this feature module to LSP.

void	initialize (const Facilities &F)
	Called by the server to prepare this module for use.

virtual void	stop ()
	Requests that the module cancel background work and go idle soon.

virtual bool	blockUntilIdle (Deadline)
	Waits until the module is idle (no background work) or a deadline expires.

virtual void	contributeTweaks (std::vector< std::unique_ptr< Tweak > > &Out)
	Tweaks implemented by this module.

virtual std::unique_ptr< ASTListener >	astListeners ()
	Can be called asynchronously before building an AST.

Protected Types
template<typename P >
using	OutgoingNotification = llvm::unique_function< void(const P &)>
	Types of function objects that feature modules use for outgoing calls.

template<typename P , typename R >
using	OutgoingMethod = llvm::unique_function< void(const P &, Callback< R >)>

Protected Member Functions
Facilities &	facilities ()
	Accessors for modules to access shared server facilities they depend on.

TUScheduler &	scheduler ()
	The scheduler is used to run tasks on worker threads and access ASTs.

const SymbolIndex *	index ()
	The index is used to get information about the whole codebase.

const ThreadsafeFS &	fs ()
	The filesystem is used to read source files on disk.

Detailed Description

A FeatureModule contributes a vertical feature to clangd.

The lifetime of a module is roughly:

feature modules are created before the LSP server, in ClangdMain.cpp
these modules are then passed to ClangdLSPServer in a FeatureModuleSet
initializeLSP() is called when the editor calls initialize.

module hooks can be called by the server at this point. Server facilities (scheduler etc) are available.

ClangdServer will not be destroyed until all the requests are done. FIXME: Block server shutdown until all the modules are idle.
When shutting down, ClangdServer will wait for all requests to finish, call stop(), and then blockUntilIdle().
feature modules will be destroyed after ClangdLSPServer is destroyed.

FeatureModules are not threadsafe in general. A module's entrypoints are:

method handlers registered in initializeLSP()
public methods called directly via ClangdServer.featureModule<T>()->...
specific overridable "hook" methods inherited from FeatureModule Unless otherwise specified, these are only called on the main thread.

Conventionally, standard feature modules live in the clangd namespace, and other exposed details live in a sub-namespace.

Definition at line 56 of file FeatureModule.h.

Member Typedef Documentation

◆ OutgoingMethod

template<typename P , typename R >

using clang::clangd::FeatureModule::OutgoingMethod = llvm::unique_function<void(const P &, Callback<R>)>

protected

Definition at line 138 of file FeatureModule.h.

◆ OutgoingNotification

template<typename P >

using clang::clangd::FeatureModule::OutgoingNotification = llvm::unique_function<void(const P &)>

protected

Types of function objects that feature modules use for outgoing calls.

(Bound throuh LSPBinder, made available here for convenience).

Definition at line 136 of file FeatureModule.h.

Constructor & Destructor Documentation

◆ ~FeatureModule()

virtual clang::clangd::FeatureModule::~FeatureModule ( )

inlinevirtual

Perform shutdown sequence on destruction in case the ClangdServer was never initialized. Usually redundant, but shutdown is idempotent.

Definition at line 58 of file FeatureModule.h.

References blockUntilIdle(), clang::clangd::Deadline::infinity(), and stop().

Member Function Documentation

◆ astListeners()

virtual std::unique_ptr< ASTListener > clang::clangd::FeatureModule::astListeners ( )

inlinevirtual

Can be called asynchronously before building an AST.

Definition at line 121 of file FeatureModule.h.

◆ blockUntilIdle()

virtual bool clang::clangd::FeatureModule::blockUntilIdle ( Deadline )

inlinevirtual

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). FeatureModules should go idle quickly if stop() has been called. Called by the server when shutting down, and also by tests.

Definition at line 96 of file FeatureModule.h.

Referenced by ~FeatureModule().

◆ contributeTweaks()

virtual void clang::clangd::FeatureModule::contributeTweaks ( std::vector< std::unique_ptr< Tweak > > & Out )

inlinevirtual

Tweaks implemented by this module.

Can be called asynchronously when enumerating or applying code actions.

Definition at line 100 of file FeatureModule.h.

◆ facilities()

FeatureModule::Facilities & clang::clangd::FeatureModule::facilities ( )

protected

Accessors for modules to access shared server facilities they depend on.

Definition at line 20 of file FeatureModule.cpp.

Referenced by fs(), index(), and scheduler().

◆ fs()

const ThreadsafeFS & clang::clangd::FeatureModule::fs ( )

inlineprotected

The filesystem is used to read source files on disk.

Definition at line 131 of file FeatureModule.h.

References facilities(), and clang::clangd::FeatureModule::Facilities::FS.

◆ index()

const SymbolIndex * clang::clangd::FeatureModule::index ( )

inlineprotected

The index is used to get information about the whole codebase.

Definition at line 129 of file FeatureModule.h.

References facilities(), and clang::clangd::FeatureModule::Facilities::Index.

◆ initialize()

void clang::clangd::FeatureModule::initialize ( const Facilities & F )

Called by the server to prepare this module for use.

Definition at line 15 of file FeatureModule.cpp.

◆ initializeLSP()

virtual void clang::clangd::FeatureModule::initializeLSP	(	LSPBinder &	Bind,
		const llvm::json::Object &	ClientCaps,
		llvm::json::Object &	ServerCaps
	)

inlinevirtual

Called by the server to connect this feature module to LSP.

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! FeatureModules with a public interface should work without LSP bindings.

Definition at line 71 of file FeatureModule.h.

◆ scheduler()

TUScheduler & clang::clangd::FeatureModule::scheduler ( )

inlineprotected

The scheduler is used to run tasks on worker threads and access ASTs.

Definition at line 127 of file FeatureModule.h.

References facilities(), and clang::clangd::FeatureModule::Facilities::Scheduler.

◆ stop()

virtual void clang::clangd::FeatureModule::stop ( )

inlinevirtual

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.

Definition at line 89 of file FeatureModule.h.

Referenced by ~FeatureModule().

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ OutgoingMethod

◆ OutgoingNotification

Constructor & Destructor Documentation

◆ ~FeatureModule()

Member Function Documentation

◆ astListeners()

◆ blockUntilIdle()

◆ contributeTweaks()

◆ facilities()

◆ fs()

◆ index()

◆ initialize()

◆ initializeLSP()

◆ scheduler()

◆ stop()