Handles running tasks for ClangdServer and managing the resources (e.g., preambles and ASTs) for opened files. More...

#include <TUScheduler.h>

Classes
class	ASTCache
	An LRU cache of idle ASTs. More...

struct	FileData

struct	FileStats

class	HeaderIncluderCache
	A map from header files to an opened "proxy" file that includes them. More...

struct	Options

Public Types
enum	ASTActionInvalidation { NoInvalidation , InvalidateOnUpdate }
	Defines how a runWithAST action is implicitly cancelled by other actions. More...

enum	PreambleConsistency { Stale , StaleOrAbsent }
	Controls whether preamble reads wait for the preamble to be up-to-date. More...

Public Member Functions
	TUScheduler (const GlobalCompilationDatabase &CDB, const Options &Opts, std::unique_ptr< ParsingCallbacks > ASTCallbacks=nullptr)

	~TUScheduler ()

	TUScheduler (const TUScheduler &other)=delete

TUScheduler &	operator= (const TUScheduler &other)=delete

llvm::StringMap< FileStats >	fileStats () const
	Returns resources used for each of the currently open files.

std::vector< Path >	getFilesWithCachedAST () const
	Returns a list of files with ASTs currently stored in memory.

bool	update (PathRef File, ParseInputs Inputs, WantDiagnostics WD)
	Schedule an update for `File`.

void	remove (PathRef File)
	Remove `File` from the list of tracked files and schedule removal of its resources.

void	run (llvm::StringRef Name, llvm::StringRef Path, llvm::unique_function< void()> Action)
	Schedule an async task with no dependencies.

void	runQuick (llvm::StringRef Name, llvm::StringRef Path, llvm::unique_function< void()> Action)
	Similar to run, except the task is expected to be quick.

void	runWithAST (llvm::StringRef Name, PathRef File, Callback< InputsAndAST > Action, ASTActionInvalidation=NoInvalidation)
	Schedule an async read of the AST.

void	runWithPreamble (llvm::StringRef Name, PathRef File, PreambleConsistency Consistency, Callback< InputsAndPreamble > Action)
	Schedule an async read of the preamble.

bool	blockUntilIdle (Deadline D) const
	Wait until there are no scheduled or running tasks.

void	profile (MemoryTree &MT) const

Static Public Member Functions
static std::optional< llvm::StringRef >	getFileBeingProcessedInContext ()

Detailed Description

Handles running tasks for ClangdServer and managing the resources (e.g., preambles and ASTs) for opened files.

TUScheduler is not thread-safe, only one thread should be providing updates and scheduling tasks. Callbacks are run on a threadpool and it's appropriate to do slow work in them. Each task has a name, used for tracing (should be UpperCamelCase).

Definition at line 213 of file TUScheduler.h.

Member Enumeration Documentation

◆ ASTActionInvalidation

enum clang::clangd::TUScheduler::ASTActionInvalidation

Defines how a runWithAST action is implicitly cancelled by other actions.

Enumerator

NoInvalidation

The request will run unless explicitly cancelled.

InvalidateOnUpdate

The request will be implicitly cancelled by a subsequent update().

(Only if the request was not yet cancelled). Useful for requests that are generated by clients, without any explicit user action. These can otherwise e.g. force every version to be built.

Definition at line 290 of file TUScheduler.h.

◆ PreambleConsistency

enum clang::clangd::TUScheduler::PreambleConsistency

Controls whether preamble reads wait for the preamble to be up-to-date.

Enumerator

Stale

The preamble may be generated from an older version of the file.

Reading from locations in the preamble may cause files to be re-read. This gives callers two options:

validate that the preamble is still valid, and only use it if so
accept that the preamble contents may be outdated, and try to avoid reading source code from headers. This is the fastest option, usually a preamble is available immediately.

StaleOrAbsent

Besides accepting stale preamble, this also allow preamble to be absent (not ready or failed to build).

Definition at line 313 of file TUScheduler.h.

Constructor & Destructor Documentation

◆ TUScheduler() [1/2]

clang::clangd::TUScheduler::TUScheduler	(	const GlobalCompilationDatabase &	CDB,
		const Options &	Opts,
		std::unique_ptr< ParsingCallbacks >	ASTCallbacks = `nullptr`
	)

Definition at line 1631 of file TUScheduler.cpp.

References clang::clangd::Context::clone(), clang::clangd::TUScheduler::Options::ContextProvider, and clang::clangd::Context::current().

◆ ~TUScheduler()

clang::clangd::TUScheduler::~TUScheduler ( )

Definition at line 1653 of file TUScheduler.cpp.

◆ TUScheduler() [2/2]

clang::clangd::TUScheduler::TUScheduler ( const TUScheduler & other )

delete

Member Function Documentation

◆ blockUntilIdle()

bool clang::clangd::TUScheduler::blockUntilIdle ( Deadline D ) const

Wait until there are no scheduled or running tasks.

Mostly useful for synchronizing tests.

Definition at line 1664 of file TUScheduler.cpp.

References clang::clangd::File.

◆ fileStats()

llvm::StringMap< TUScheduler::FileStats > clang::clangd::TUScheduler::fileStats ( ) const

Returns resources used for each of the currently open files.

Results are inherently racy as they measure activity of other threads.

Definition at line 1818 of file TUScheduler.cpp.

Referenced by profile().

◆ getFileBeingProcessedInContext()

std::optional< llvm::StringRef > clang::clangd::TUScheduler::getFileBeingProcessedInContext ( )

static

Definition at line 141 of file TUScheduler.cpp.

References clang::clangd::Context::current(), clang::clangd::File, and clang::clangd::FileBeingProcessed.

◆ getFilesWithCachedAST()

std::vector< Path > clang::clangd::TUScheduler::getFilesWithCachedAST ( ) const

Returns a list of files with ASTs currently stored in memory.

This method is not very reliable and is only used for test. E.g., the results will not contain files that currently run something over their AST.

Definition at line 1826 of file TUScheduler.cpp.

◆ operator=()

TUScheduler & clang::clangd::TUScheduler::operator= ( const TUScheduler & other )

delete

◆ profile()

void clang::clangd::TUScheduler::profile ( MemoryTree & MT ) const

Definition at line 1864 of file TUScheduler.cpp.

References clang::clangd::MemoryTree::addUsage(), clang::clangd::MemoryTree::child(), clang::clangd::MemoryTree::detail(), and fileStats().

◆ remove()

void clang::clangd::TUScheduler::remove ( PathRef File )

Remove File from the list of tracked files and schedule removal of its resources.

Pending diagnostics for closed files may not be delivered, even if requested with WantDiags::Auto or WantDiags::Yes.

Definition at line 1699 of file TUScheduler.cpp.

References clang::clangd::elog(), and clang::clangd::File.

◆ run()

void clang::clangd::TUScheduler::run	(	llvm::StringRef	Name,
		llvm::StringRef	Path,
		llvm::unique_function< void()>	Action
	)

Schedule an async task with no dependencies.

Path may be empty (it is used only to set the Context).

Definition at line 1710 of file TUScheduler.cpp.

References Action, and Name.

◆ runQuick()

void clang::clangd::TUScheduler::runQuick	(	llvm::StringRef	Name,
		llvm::StringRef	Path,
		llvm::unique_function< void()>	Action
	)

Similar to run, except the task is expected to be quick.

This function will not honor AsyncThreadsCount (except if threading is disabled with AsyncThreadsCount=0) It is intended to run quick tasks that need to run ASAP

Definition at line 1715 of file TUScheduler.cpp.

References Action, and Name.

◆ runWithAST()

void clang::clangd::TUScheduler::runWithAST	(	llvm::StringRef	Name,
		PathRef	File,
		Callback< InputsAndAST >	Action,
		ASTActionInvalidation	= `NoInvalidation`
	)

Schedule an async read of the AST.

Action will be called when AST is ready. The AST passed to Action refers to the version of File tracked at the time of the call, even if new updates are received before Action is executed. If an error occurs during processing, it is forwarded to the Action callback. If the context is cancelled before the AST is ready, or the invalidation policy is triggered, the callback will receive a CancelledError.

Definition at line 1743 of file TUScheduler.cpp.

References Action, clang::clangd::File, clang::clangd::InvalidParams, and Name.

◆ runWithPreamble()

void clang::clangd::TUScheduler::runWithPreamble	(	llvm::StringRef	Name,
		PathRef	File,
		PreambleConsistency	Consistency,
		Callback< InputsAndPreamble >	Action
	)

Schedule an async read of the preamble.

If there's no up-to-date preamble, we follow the PreambleConsistency policy. If an error occurs, it is forwarded to the Action callback. Context cancellation is ignored and should be handled by the Action. (In practice, the Action is almost always executed immediately).

Definition at line 1758 of file TUScheduler.cpp.

References Action, clang::clangd::InputsAndPreamble::Contents, clang::clangd::Context::current(), clang::clangd::Context::derive(), clang::clangd::File, clang::clangd::FileBeingProcessed, clang::clangd::InvalidParams, Name, clang::clangd::Preamble, SPAN_ATTACH, and Stale.

◆ update()

bool clang::clangd::TUScheduler::update	(	PathRef	File,
		ParseInputs	Inputs,
		WantDiagnostics	WD
	)

Schedule an update for File.

The compile command in Inputs is ignored; worker queries CDB to get the actual compile command. If diagnostics are requested (Yes), and the context is cancelled before they are prepared, they may be skipped if eventual-consistency permits it (i.e. WantDiagnostics is downgraded to Auto). Returns true if the file was not previously tracked.

Definition at line 1674 of file TUScheduler.cpp.

References ContentChanged, clang::clangd::File, and WantDiags.

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

Classes

Public Types

Public Member Functions

Static Public Member Functions