clang-tools  15.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/ADT/Optional.h"
19 #include "llvm/Support/JSON.h"
20 #include <mutex>
21 #include <string>
22 
23 namespace clang {
24 namespace 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  llvm::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 {
52  return std::tie(Query, Scopes, Limit, RestrictForCodeCompletion,
54  std::tie(Req.Query, Req.Scopes, Req.Limit,
56  Req.PreferredTypes);
57  }
58  bool operator!=(const FuzzyFindRequest &Req) const { return !(*this == Req); }
59 };
60 bool fromJSON(const llvm::json::Value &Value, FuzzyFindRequest &Request,
62 llvm::json::Value toJSON(const FuzzyFindRequest &Request);
63 
64 struct LookupRequest {
65  llvm::DenseSet<SymbolID> IDs;
66 };
67 
68 struct RefsRequest {
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  llvm::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  llvm::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.
93 enum class IndexContents : uint8_t {
94  None = 0,
95  Symbols = 1 << 1,
96  References = 1 << 2,
97  Relations = 1 << 3,
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.
113 class SymbolIndex {
114 public:
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
123  fuzzyFind(const FuzzyFindRequest &Req,
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
130  lookup(const LookupRequest &Req,
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.
154  using IndexedFiles =
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.
163 class SwapIndex : public SymbolIndex {
164 public:
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 
187 private:
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
SymbolID.h
clang::clangd::RefKind::All
@ All
clang::clangd::SwapIndex::SwapIndex
SwapIndex(std::unique_ptr< SymbolIndex > Index=nullptr)
Definition: Index.h:166
clang::clangd::FuzzyFindRequest::PreferredTypes
std::vector< std::string > PreferredTypes
Preferred types of symbols. These are raw representation of OpaqueType.
Definition: Index.h:49
clang::clangd::FuzzyFindRequest::operator==
bool operator==(const FuzzyFindRequest &Req) const
Definition: Index.h:51
clang::clangd::RelationsRequest::Limit
llvm::Optional< uint32_t > Limit
If set, limit the number of relations returned from the index.
Definition: Index.h:84
clang::clangd::SymbolIndex::indexedFiles
virtual IndexedFiles indexedFiles() const =0
clang::clangd::SymbolKind::Object
@ Object
clang::clangd::SwapIndex::reset
void reset(std::unique_ptr< SymbolIndex >)
Definition: Index.cpp:16
clang::clangd::IndexContents::Relations
@ Relations
clang::clangd::RefKind
RefKind
Describes the kind of a cross-reference.
Definition: Ref.h:28
clang::clangd::SwapIndex
Definition: Index.h:163
clang::clangd::SymbolIndex::~SymbolIndex
virtual ~SymbolIndex()=default
clang::clangd::FuzzyFindRequest::Scopes
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
clang::clangd::IndexContents::Symbols
@ Symbols
clang::clangd::RelationsRequest::Predicate
RelationKind Predicate
Definition: Index.h:82
clang::clangd::FuzzyFindRequest
Definition: Index.h:26
clang::clangd::SymbolIndex::IndexedFiles
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
clang::clangd::FuzzyFindRequest::Query
std::string Query
A query string for the fuzzy find.
Definition: Index.h:29
clang::clangd::operator&
DeclRelationSet operator&(DeclRelation L, DeclRelation R)
Definition: FindTarget.h:211
clang::clangd::SymbolIndex::estimateMemoryUsage
virtual size_t estimateMemoryUsage() const =0
Returns estimated size of index (in bytes).
Relation.h
clang::clangd::FuzzyFindRequest::operator!=
bool operator!=(const FuzzyFindRequest &Req) const
Definition: Index.h:58
clang::clangd::SymbolIndex::lookup
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.
clang::clangd::RelationsRequest::Subjects
llvm::DenseSet< SymbolID > Subjects
Definition: Index.h:81
clang::clangd::SymbolIndex::relations
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....
clang::clangd::SwapIndex::relations
void relations(const RelationsRequest &, llvm::function_ref< void(const SymbolID &, const Symbol &)>) const override
Definition: Index.cpp:69
clang::clangd::toJSON
llvm::json::Value toJSON(const FuzzyFindRequest &Request)
Definition: Index.cpp:45
clang::clangd::Symbol
The class presents a C++ symbol, e.g.
Definition: Symbol.h:36
clang::clangd::fromJSON
bool fromJSON(const llvm::json::Value &Parameters, FuzzyFindRequest &Request, llvm::json::Path P)
Definition: Index.cpp:30
clang::clangd::IndexContents
IndexContents
Describes what data is covered by an index.
Definition: Index.h:93
clang::clangd::SwapIndex::refs
bool refs(const RefsRequest &, llvm::function_ref< void(const Ref &)>) const override
Finds all occurrences (e.g.
Definition: Index.cpp:65
clang::clangd::RefsRequest::IDs
llvm::DenseSet< SymbolID > IDs
Definition: Index.h:69
clang::clangd::SwapIndex::indexedFiles
llvm::unique_function< IndexContents(llvm::StringRef) const > indexedFiles() const override
Definition: Index.cpp:76
clang::clangd::FuzzyFindRequest::Limit
llvm::Optional< uint32_t > Limit
The number of top candidates to return.
Definition: Index.h:42
Symbol.h
clang::clangd::IndexContents::All
@ All
clang::clangd::LookupRequest::IDs
llvm::DenseSet< SymbolID > IDs
Definition: Index.h:65
clang::clangd::SymbolIndex::refs
virtual bool refs(const RefsRequest &Req, llvm::function_ref< void(const Ref &)> Callback) const =0
Finds all occurrences (e.g.
clang::clangd::SymbolIndex
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:113
clang::clangd::RefsRequest::Filter
RefKind Filter
Definition: Index.h:70
clang::clangd::LookupRequest
Definition: Index.h:64
clang::clangd::IndexContents::References
@ References
clang::clangd::IndexContents::None
@ None
clang::clangd::Ref
Represents a symbol occurrence in the source file.
Definition: Ref.h:85
Ref.h
clang::clangd::operator|
DeclRelationSet operator|(DeclRelation L, DeclRelation R)
Definition: FindTarget.h:208
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::SwapIndex::estimateMemoryUsage
size_t estimateMemoryUsage() const override
Returns estimated size of index (in bytes).
Definition: Index.cpp:86
clang::clangd::RefsRequest::Limit
llvm::Optional< uint32_t > Limit
If set, limit the number of refers returned from the index.
Definition: Index.h:74
clang::clangd::FuzzyFindRequest::AnyScope
bool AnyScope
If set to true, allow symbols from any scope.
Definition: Index.h:39
clang::clangd::Callback
llvm::unique_function< void(llvm::Expected< T >)> Callback
A Callback<T> is a void function that accepts Expected<T>.
Definition: Function.h:28
clang::clangd::RelationsRequest
Definition: Index.h:80
clang::clangd::FuzzyFindRequest::RestrictForCodeCompletion
bool RestrictForCodeCompletion
If set to true, only symbols for completion support will be considered.
Definition: Index.h:44
clang::clangd::RefsRequest::WantContainer
bool WantContainer
If set, populates the container of the reference.
Definition: Index.h:77
clang::clangd::SymbolID
Definition: SymbolID.h:32
clang::clangd::SwapIndex::fuzzyFind
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
clang::clangd::RefsRequest
Definition: Index.h:68
clang::clangd::FuzzyFindRequest::ProximityPaths
std::vector< std::string > ProximityPaths
Contextually relevant files (e.g.
Definition: Index.h:47
clang::clangd::SwapIndex::lookup
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
clang::clangd::SymbolIndex::fuzzyFind
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.
Value
static constexpr bool Value
Definition: SuspiciousCallArgumentCheck.cpp:72
Path
std::vector< HeaderHandle > Path
Definition: PreprocessorTracker.cpp:525
clang::clangd::RelationKind
RelationKind
Definition: Relation.h:20