clang-tools 20.0.0git
Index.h
Go to the documentation of this file.
1//===--- Index.h -------------------------------------------------*- C++-*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_INDEX_H
10#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_INDEX_H
11
12#include "index/Ref.h"
13#include "index/Relation.h"
14#include "index/Symbol.h"
15#include "index/SymbolID.h"
16#include "llvm/ADT/DenseSet.h"
17#include "llvm/ADT/FunctionExtras.h"
18#include "llvm/Support/JSON.h"
19#include <mutex>
20#include <optional>
21#include <string>
22
23namespace clang {
24namespace clangd {
25
27 /// A query string for the fuzzy find. This is matched against symbols'
28 /// un-qualified identifiers and should not contain qualifiers like "::".
29 std::string Query;
30 /// If this is non-empty, symbols must be in at least one of the scopes
31 /// (e.g. namespaces) excluding nested scopes. For example, if a scope "xyz::"
32 /// is provided, the matched symbols must be defined in namespace xyz but not
33 /// namespace xyz::abc.
34 ///
35 /// The global scope is "", a top level scope is "foo::", etc.
36 std::vector<std::string> Scopes;
37 /// If set to true, allow symbols from any scope. Scopes explicitly listed
38 /// above will be ranked higher.
39 bool AnyScope = false;
40 /// The number of top candidates to return. The index may choose to
41 /// return more than this, e.g. if it doesn't know which candidates are best.
42 std::optional<uint32_t> Limit;
43 /// If set to true, only symbols for completion support will be considered.
45 /// Contextually relevant files (e.g. the file we're code-completing in).
46 /// Paths should be absolute.
47 std::vector<std::string> ProximityPaths;
48 /// Preferred types of symbols. These are raw representation of `OpaqueType`.
49 std::vector<std::string> PreferredTypes;
50
51 bool operator==(const FuzzyFindRequest &Req) const {
54 std::tie(Req.Query, Req.Scopes, Req.Limit,
56 Req.PreferredTypes);
57 }
58 bool operator!=(const FuzzyFindRequest &Req) const { return !(*this == Req); }
59};
60bool fromJSON(const llvm::json::Value &Value, FuzzyFindRequest &Request,
61 llvm::json::Path);
62llvm::json::Value toJSON(const FuzzyFindRequest &Request);
63
65 llvm::DenseSet<SymbolID> IDs;
66};
67
69 llvm::DenseSet<SymbolID> IDs;
71 /// If set, limit the number of refers returned from the index. The index may
72 /// choose to return less than this, e.g. it tries to avoid returning stale
73 /// results.
74 std::optional<uint32_t> Limit;
75 /// If set, populates the container of the reference.
76 /// Index implementations may chose to populate containers no matter what.
77 bool WantContainer = false;
78};
79
81 llvm::DenseSet<SymbolID> Subjects;
83 /// If set, limit the number of relations returned from the index.
84 std::optional<uint32_t> Limit;
85};
86
87/// Describes what data is covered by an index.
88///
89/// Indexes may contain symbols but not references from a file, etc.
90/// This affects merging: if a staler index contains a reference but a fresher
91/// one does not, we want to trust the fresher index *only* if it actually
92/// includes references in general.
93enum class IndexContents : uint8_t {
94 None = 0,
95 Symbols = 1 << 1,
96 References = 1 << 2,
97 Relations = 1 << 3,
98 All = Symbols | References | Relations
99};
100
102 return static_cast<IndexContents>(static_cast<uint8_t>(L) &
103 static_cast<uint8_t>(R));
104}
105
107 return static_cast<IndexContents>(static_cast<uint8_t>(L) |
108 static_cast<uint8_t>(R));
109}
110
111/// Interface for symbol indexes that can be used for searching or
112/// matching symbols among a set of symbols based on names or unique IDs.
114public:
115 virtual ~SymbolIndex() = default;
116
117 /// Matches symbols in the index fuzzily and applies \p Callback on
118 /// each matched symbol before returning.
119 /// If returned Symbols are used outside Callback, they must be deep-copied!
120 ///
121 /// Returns true if there may be more results (limited by Req.Limit).
122 virtual bool
124 llvm::function_ref<void(const Symbol &)> Callback) const = 0;
125
126 /// Looks up symbols with any of the given symbol IDs and applies \p Callback
127 /// on each matched symbol.
128 /// The returned symbol must be deep-copied if it's used outside Callback.
129 virtual void
131 llvm::function_ref<void(const Symbol &)> Callback) const = 0;
132
133 /// Finds all occurrences (e.g. references, declarations, definitions) of
134 /// symbols and applies \p Callback on each result.
135 ///
136 /// Results should be returned in arbitrary order.
137 /// The returned result must be deep-copied if it's used outside Callback.
138 /// FIXME: there's no indication which result references which symbol.
139 ///
140 /// Returns true if there will be more results (limited by Req.Limit);
141 virtual bool refs(const RefsRequest &Req,
142 llvm::function_ref<void(const Ref &)> Callback) const = 0;
143
144 /// Finds all relations (S, P, O) stored in the index such that S is among
145 /// Req.Subjects and P is Req.Predicate, and invokes \p Callback for (S, O) in
146 /// each.
147 virtual void relations(
148 const RelationsRequest &Req,
149 llvm::function_ref<void(const SymbolID &Subject, const Symbol &Object)>
150 Callback) const = 0;
151
152 /// Returns function which checks if the specified file was used to build this
153 /// index or not. The function must only be called while the index is alive.
155 llvm::unique_function<IndexContents(llvm::StringRef) const>;
156 virtual IndexedFiles indexedFiles() const = 0;
157
158 /// Returns estimated size of index (in bytes).
159 virtual size_t estimateMemoryUsage() const = 0;
160};
161
162// Delegating implementation of SymbolIndex whose delegate can be swapped out.
163class SwapIndex : public SymbolIndex {
164public:
165 // If an index is not provided, reset() must be called.
166 SwapIndex(std::unique_ptr<SymbolIndex> Index = nullptr)
167 : Index(std::move(Index)) {}
168 void reset(std::unique_ptr<SymbolIndex>);
169
170 // SymbolIndex methods delegate to the current index, which is kept alive
171 // until the call returns (even if reset() is called).
172 bool fuzzyFind(const FuzzyFindRequest &,
173 llvm::function_ref<void(const Symbol &)>) const override;
174 void lookup(const LookupRequest &,
175 llvm::function_ref<void(const Symbol &)>) const override;
176 bool refs(const RefsRequest &,
177 llvm::function_ref<void(const Ref &)>) const override;
178 void relations(const RelationsRequest &,
179 llvm::function_ref<void(const SymbolID &, const Symbol &)>)
180 const override;
181
182 llvm::unique_function<IndexContents(llvm::StringRef) const>
183 indexedFiles() const override;
184
185 size_t estimateMemoryUsage() const override;
186
187private:
188 std::shared_ptr<SymbolIndex> snapshot() const;
189 mutable std::mutex Mutex;
190 std::shared_ptr<SymbolIndex> Index;
191};
192
193} // namespace clangd
194} // namespace clang
195
196#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_INDEX_H
void relations(const RelationsRequest &, llvm::function_ref< void(const SymbolID &, const Symbol &)>) const override
Definition: Index.cpp:69
bool refs(const RefsRequest &, llvm::function_ref< void(const Ref &)>) const override
Finds all occurrences (e.g.
Definition: Index.cpp:65
void reset(std::unique_ptr< SymbolIndex >)
Definition: Index.cpp:16
llvm::unique_function< IndexContents(llvm::StringRef) const > indexedFiles() const override
Definition: Index.cpp:76
size_t estimateMemoryUsage() const override
Returns estimated size of index (in bytes).
Definition: Index.cpp:86
void lookup(const LookupRequest &, llvm::function_ref< void(const Symbol &)>) const override
Looks up symbols with any of the given symbol IDs and applies Callback on each matched symbol.
Definition: Index.cpp:61
bool fuzzyFind(const FuzzyFindRequest &, llvm::function_ref< void(const Symbol &)>) const override
Matches symbols in the index fuzzily and applies Callback on each matched symbol before returning.
Definition: Index.cpp:57
SwapIndex(std::unique_ptr< SymbolIndex > Index=nullptr)
Definition: Index.h:166
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:113
virtual bool fuzzyFind(const FuzzyFindRequest &Req, llvm::function_ref< void(const Symbol &)> Callback) const =0
Matches symbols in the index fuzzily and applies Callback on each matched symbol before returning.
virtual void relations(const RelationsRequest &Req, llvm::function_ref< void(const SymbolID &Subject, const Symbol &Object)> Callback) const =0
Finds all relations (S, P, O) stored in the index such that S is among Req.Subjects and P is Req....
virtual bool refs(const RefsRequest &Req, llvm::function_ref< void(const Ref &)> Callback) const =0
Finds all occurrences (e.g.
virtual size_t estimateMemoryUsage() const =0
Returns estimated size of index (in bytes).
virtual void lookup(const LookupRequest &Req, llvm::function_ref< void(const Symbol &)> Callback) const =0
Looks up symbols with any of the given symbol IDs and applies Callback on each matched symbol.
virtual ~SymbolIndex()=default
llvm::unique_function< IndexContents(llvm::StringRef) const > IndexedFiles
Returns function which checks if the specified file was used to build this index or not.
Definition: Index.h:155
virtual IndexedFiles indexedFiles() const =0
IndexContents
Describes what data is covered by an index.
Definition: Index.h:93
DeclRelationSet operator&(DeclRelation L, DeclRelation R)
Definition: FindTarget.h:211
DeclRelationSet operator|(DeclRelation L, DeclRelation R)
Definition: FindTarget.h:208
llvm::unique_function< void(llvm::Expected< T >)> Callback
A Callback<T> is a void function that accepts Expected<T>.
Definition: Function.h:28
llvm::json::Value toJSON(const FuzzyFindRequest &Request)
Definition: Index.cpp:45
RefKind
Describes the kind of a cross-reference.
Definition: Ref.h:28
bool fromJSON(const llvm::json::Value &Parameters, FuzzyFindRequest &Request, llvm::json::Path P)
Definition: Index.cpp:30
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::vector< std::string > Scopes
If this is non-empty, symbols must be in at least one of the scopes (e.g.
Definition: Index.h:36
bool RestrictForCodeCompletion
If set to true, only symbols for completion support will be considered.
Definition: Index.h:44
bool operator!=(const FuzzyFindRequest &Req) const
Definition: Index.h:58
std::string Query
A query string for the fuzzy find.
Definition: Index.h:29
std::vector< std::string > ProximityPaths
Contextually relevant files (e.g.
Definition: Index.h:47
bool operator==(const FuzzyFindRequest &Req) const
Definition: Index.h:51
bool AnyScope
If set to true, allow symbols from any scope.
Definition: Index.h:39
std::optional< uint32_t > Limit
The number of top candidates to return.
Definition: Index.h:42
std::vector< std::string > PreferredTypes
Preferred types of symbols. These are raw representation of OpaqueType.
Definition: Index.h:49
llvm::DenseSet< SymbolID > IDs
Definition: Index.h:65
Represents a symbol occurrence in the source file.
Definition: Ref.h:85
bool WantContainer
If set, populates the container of the reference.
Definition: Index.h:77
llvm::DenseSet< SymbolID > IDs
Definition: Index.h:69
std::optional< uint32_t > Limit
If set, limit the number of refers returned from the index.
Definition: Index.h:74
std::optional< uint32_t > Limit
If set, limit the number of relations returned from the index.
Definition: Index.h:84
llvm::DenseSet< SymbolID > Subjects
Definition: Index.h:81
The class presents a C++ symbol, e.g.
Definition: Symbol.h:39