clang-tools 8.0.0

Classes | Public Member Functions | Static Public Member Functions | List of all members
clang::clangd::ClangdServer Class Reference

Manages a collection of source files and derived data (ASTs, indexes), and provides language-aware features such as code completion. More...

`#include <ClangdServer.h>`

## Classes
struct | Options

## Public Member Functions
| ClangdServer (const GlobalCompilationDatabase &CDB, const FileSystemProvider &FSProvider, DiagnosticsConsumer &DiagConsumer, const Options &Opts)
| Creates a new ClangdServer instance. More...
void | addDocument (PathRef File, StringRef Contents, WantDiagnostics WD=WantDiagnostics::Auto)
| Add a `File` to the list of tracked C++ files or update the contents if `File` is already tracked. More...
void | removeDocument (PathRef File)
| Remove `File` from list of tracked files, schedule a request to free resources associated with it. More...
void | codeComplete (PathRef File, Position Pos, const clangd::CodeCompleteOptions &Opts, Callback< CodeCompleteResult > CB)
| Run code completion for `File` at `Pos`. More...
void | signatureHelp (PathRef File, Position Pos, Callback< SignatureHelp > CB)
| Provide signature help for `File` at `Pos`. More...
void | findDefinitions (PathRef File, Position Pos, Callback< std::vector< Location >> CB)
| Get definition of symbol at a specified `Line` and `Column` in `File`. More...
llvm::Optional< Path > | switchSourceHeader (PathRef Path)
| Helper function that returns a path to the corresponding source file when given a header file and vice versa. More...
void | findDocumentHighlights (PathRef File, Position Pos, Callback< std::vector< DocumentHighlight >> CB)
| Get document highlights for a given position. More...
void | findHover (PathRef File, Position Pos, Callback< llvm::Optional< Hover >> CB)
| Get code hover for a given position. More...
void | workspaceSymbols (StringRef Query, int Limit, Callback< std::vector< SymbolInformation >> CB)
| Retrieve the top symbols from the workspace matching a query. More...
void | documentSymbols (StringRef File, Callback< std::vector< DocumentSymbol >> CB)
| Retrieve the symbols within the specified file. More...
void | findReferences (PathRef File, Position Pos, uint32_t Limit, Callback< std::vector< Location >> CB)
| Retrieve locations for symbol references. More...
llvm::Expected< tooling::Replacements > | formatRange (StringRef Code, PathRef File, Range Rng)
| Run formatting for `Rng` inside `File` with content `Code`. More...
llvm::Expected< tooling::Replacements > | formatFile (StringRef Code, PathRef File)
| Run formatting for the whole `File` with content `Code`. More...
llvm::Expected< tooling::Replacements > | formatOnType (StringRef Code, PathRef File, Position Pos)
| Run formatting after a character was typed at `Pos` in `File` with content `Code`. More...
void | rename (PathRef File, Position Pos, llvm::StringRef NewName, Callback< std::vector< tooling::Replacement >> CB)
| Rename all occurrences of the symbol at the `Pos` in `File` to `NewName`. More...
void | dumpAST (PathRef File, llvm::unique_function< void(std::string)> Callback)
| Only for testing purposes. More...
void | onFileEvent (const DidChangeWatchedFilesParams &Params)
| Called when an event occurs for a watched file in the workspace. More...
void | symbolInfo (PathRef File, Position Pos, Callback< std::vector< SymbolDetails >> CB)
| Get symbol info for given position. More...
std::vector< std::pair< Path, std::size_t > > | getUsedBytesPerFile () const
| Returns estimated memory usage for each of the currently open files. More...
const SymbolIndex * | dynamicIndex () const
| Returns the active dynamic index if one was built. More...
LLVM_NODISCARD bool | blockUntilIdleForTest (llvm::Optional< double > TimeoutSeconds=10)

## Static Public Member Functions
static Options | optsForTest ()

## Detailed Description

Manages a collection of source files and derived data (ASTs, indexes), and provides language-aware features such as code completion.

The primary client is ClangdLSPServer which exposes these features via the Language Server protocol. ClangdServer may also be embedded directly, though its API is not stable over time.

ClangdServer should be used from a single thread. Many potentially-slow operations have asynchronous APIs and deliver their results on another thread. Such operations support cancellation: if the caller sets up a cancelable context, many operations will notice cancellation and fail early. (ClangdLSPServer uses this to implement $/cancelRequest).

Definition at line 65 of file ClangdServer.h.

## Constructor & Destructor Documentation

## ◆ ClangdServer()

clang::clangd::ClangdServer::ClangdServer | ( | const GlobalCompilationDatabase & | CDB,
|  | const FileSystemProvider & | FSProvider,
|  | DiagnosticsConsumer & | DiagConsumer,
|  | const Options & | Opts
| ) |  |

Creates a new ClangdServer instance.

ClangdServer uses `CDB` to obtain compilation arguments for parsing. Note that ClangdServer only obtains compilation arguments once for each newly added file (i.e., when processing a first call to addDocument) and reuses those arguments for subsequent reparses. However, ClangdServer will check if compilation arguments changed on calls to forceReparse().

After each parsing request finishes, ClangdServer reports diagnostics to `DiagConsumer`. Note that a callback to `DiagConsumer` happens on a worker thread. Therefore, instances of `DiagConsumer` must properly synchronize access to shared state.

Definition at line 101 of file ClangdServer.cpp.

## Member Function Documentation

## ◆ addDocument()

void clang::clangd::ClangdServer::addDocument | ( | PathRef | File,
|  | StringRef | Contents,
|  | WantDiagnostics | WD = `WantDiagnostics::Auto`
| ) |  |

Add a `File` to the list of tracked C++ files or update the contents if `File` is already tracked.

Also schedules parsing of the AST for it on a separate thread. When the parsing is complete, DiagConsumer passed in constructor will receive onDiagnosticsReady callback.

Definition at line 142 of file ClangdServer.cpp.

References clang::clangd::FileSystemProvider::getFileSystem(), and clang::clangd::TUScheduler::update().

## ◆ blockUntilIdleForTest()

LLVM_NODISCARD bool clang::clangd::ClangdServer::blockUntilIdleForTest | ( | llvm::Optional< double > | TimeoutSeconds = `10` | ) |

Definition at line 522 of file ClangdServer.cpp.

References clang::clangd::TUScheduler::blockUntilIdle(), and clang::clangd::timeoutSeconds().

## ◆ codeComplete()

void clang::clangd::ClangdServer::codeComplete | ( | PathRef | File,
|  | Position | Pos,
|  | const clangd::CodeCompleteOptions & | Opts,
|  | Callback< CodeCompleteResult > | CB
| ) |  |

Run code completion for `File` at `Pos`.

Request is processed asynchronously.

This method should only be called for currently tracked files. However, it is safe to call removeDocument for `File` after this method returns, even while returned future is not yet ready. A version of `codeComplete` that runs `Callback` on the processing thread when codeComplete results become available.

Definition at line 156 of file ClangdServer.cpp.

## ◆ documentSymbols()

void clang::clangd::ClangdServer::documentSymbols | ( | StringRef | File,
|  | Callback< std::vector< DocumentSymbol >> | CB
| ) |  |

Retrieve the symbols within the specified file.

Definition at line 480 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::getDocumentSymbols(), and clang::clangd::TUScheduler::runWithAST().

## ◆ dumpAST()

void clang::clangd::ClangdServer::dumpAST | ( | PathRef | File,
|  | llvm::unique_function< void(std::string)> | Callback
| ) |  |

Only for testing purposes.

Waits until all requests to worker thread are finished and dumps AST for `File`. `File` must be in the list of added documents.

Definition at line 318 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::dumpAST(), Result, and clang::clangd::TUScheduler::runWithAST().

## ◆ dynamicIndex()

const SymbolIndex* clang::clangd::ClangdServer::dynamicIndex | ( |  | ) | const
| inline

Returns the active dynamic index if one was built.

This can be useful for testing, debugging, or observing memory usage.

Definition at line 228 of file ClangdServer.h.

References Index, PCHs, and clang::clangd::ResourceDir().

## ◆ findDefinitions()

void clang::clangd::ClangdServer::findDefinitions | ( | PathRef | File,
|  | Position | Pos,
|  | Callback< std::vector< Location >> | CB
| ) |  |

Get definition of symbol at a specified `Line` and `Column` in `File`.

Definition at line 338 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::findDefinitions(), Pos, and clang::clangd::TUScheduler::runWithAST().

## ◆ findDocumentHighlights()

void clang::clangd::ClangdServer::findDocumentHighlights | ( | PathRef | File,
|  | Position | Pos,
|  | Callback< std::vector< DocumentHighlight >> | CB
| ) |  |

Get document highlights for a given position.

Definition at line 429 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::findDocumentHighlights(), Pos, and clang::clangd::TUScheduler::runWithAST().

## ◆ findHover()

void clang::clangd::ClangdServer::findHover | ( | PathRef | File,
|  | Position | Pos,
|  | Callback< llvm::Optional< Hover >> | CB
| ) |  |

Get code hover for a given position.

Definition at line 441 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::GlobalCompilationDatabase::getCompileCommand(), clang::clangd::GlobalCompilationDatabase::getFallbackCommand(), clang::clangd::getHover(), Pos, and clang::clangd::TUScheduler::runWithAST().

## ◆ findReferences()

void clang::clangd::ClangdServer::findReferences | ( | PathRef | File,
|  | Position | Pos,
|  | uint32_t | Limit,
|  | Callback< std::vector< Location >> | CB
| ) |  |

Retrieve locations for symbol references.

Definition at line 492 of file ClangdServer.cpp.

## ◆ formatFile()

llvm::Expected< tooling::Replacements > clang::clangd::ClangdServer::formatFile | ( | StringRef | Code,
|  | PathRef | File
| ) |  |

Run formatting for the whole `File` with content `Code`.

Definition at line 246 of file ClangdServer.cpp.

References Range.

## ◆ formatOnType()

llvm::Expected< tooling::Replacements > clang::clangd::ClangdServer::formatOnType | ( | StringRef | Code,
|  | PathRef | File,
|  | Position | Pos
| ) |  |

Run formatting after a character was typed at `Pos` in `File` with content `Code`.

Definition at line 252 of file ClangdServer.cpp.

References clang::clangd::positionToOffset(), and Range.

## ◆ formatRange()

llvm::Expected< tooling::Replacements > clang::clangd::ClangdServer::formatRange | ( | StringRef | Code,
|  | PathRef | File,
|  | Range | Rng
| ) |  |

Run formatting for `Rng` inside `File` with content `Code`.

Definition at line 235 of file ClangdServer.cpp.

## ◆ getUsedBytesPerFile()

std::vector< std::pair< Path, std::size_t > > clang::clangd::ClangdServer::getUsedBytesPerFile | ( |  | ) | const

Returns estimated memory usage for each of the currently open files.

The order of results is unspecified. Overall memory usage of clangd may be significantly more than reported here, as this metric does not account (at least) for:

- memory occupied by static and dynamic index,
- memory required for in-flight requests, FIXME: those metrics might be useful too, we should add them.

Definition at line 517 of file ClangdServer.cpp.

References clang::clangd::TUScheduler::getUsedBytesPerFile().

## ◆ onFileEvent()

void clang::clangd::ClangdServer::onFileEvent | ( | const DidChangeWatchedFilesParams & | Params | ) |

Called when an event occurs for a watched file in the workspace.

Definition at line 461 of file ClangdServer.cpp.

## ◆ optsForTest()

ClangdServer::Options clang::clangd::ClangdServer::optsForTest | ( |  | ) |
| static

Definition at line 93 of file ClangdServer.cpp.

## ◆ removeDocument()

void clang::clangd::ClangdServer::removeDocument | ( | PathRef | File | ) |

Remove `File` from list of tracked files, schedule a request to free resources associated with it.

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

Definition at line 154 of file ClangdServer.cpp.

References clang::clangd::TUScheduler::remove().

## ◆ rename()

void clang::clangd::ClangdServer::rename | ( | PathRef | File,
|  | Position | Pos,
|  | llvm::StringRef | NewName,
|  | Callback< std::vector< tooling::Replacement >> | CB
| ) |  |

Rename all occurrences of the symbol at the `Pos` in `File` to `NewName`.

Definition at line 267 of file ClangdServer.cpp.

References Action, clang::clangd::AST, clang::clangd::File, and Pos.

## ◆ signatureHelp()

void clang::clangd::ClangdServer::signatureHelp | ( | PathRef | File,
|  | Position | Pos,
|  | Callback< SignatureHelp > | CB
| ) |  |

Provide signature help for `File` at `Pos`.

This method should only be called for tracked files.

Definition at line 210 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::TUScheduler::Consistent, clang::clangd::File, clang::clangd::FileSystemProvider::getFileSystem(), Pos, clang::clangd::PreambleData::Preamble, clang::clangd::TUScheduler::runWithPreamble(), and clang::clangd::signatureHelp().

## ◆ switchSourceHeader()

llvm::Optional< Path > clang::clangd::ClangdServer::switchSourceHeader | ( | PathRef | Path | ) |

Helper function that returns a path to the corresponding source file when given a header file and vice versa.

Definition at line 350 of file ClangdServer.cpp.

References clang::clangd::FileSystemProvider::getFileSystem(), and clang::clangd::None.

## ◆ symbolInfo()

void clang::clangd::ClangdServer::symbolInfo | ( | PathRef | File,
|  | Position | Pos,
|  | Callback< std::vector< SymbolDetails >> | CB
| ) |  |

Get symbol info for given position.

Clangd extension - not part of official LSP.

Definition at line 504 of file ClangdServer.cpp.

References Action, clang::clangd::Bind(), clang::clangd::getSymbolInfo(), Pos, and clang::clangd::TUScheduler::runWithAST().

## ◆ workspaceSymbols()

void clang::clangd::ClangdServer::workspaceSymbols | ( | StringRef | Query,
|  | int | Limit,
|  | Callback< std::vector< SymbolInformation >> | CB
| ) |  |

Retrieve the top symbols from the workspace matching a query.

Definition at line 466 of file ClangdServer.cpp.

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

- ClangdServer.h
- ClangdServer.cpp