clang-tools 8.0.0

FileIndex.h
Go to the documentation of this file.
1 //===--- FileIndex.h - Index for files. ---------------------------- C++-*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // FileIndex implements SymbolIndex for symbols from a set of files. Symbols are
11 // maintained at source-file granuality (e.g. with ASTs), and files can be
12 // updated dynamically.
13 //
14 //===----------------------------------------------------------------------===//
15
16 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_FILEINDEX_H
17 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_FILEINDEX_H
18
19 #include "ClangdUnit.h"
20 #include "Index.h"
21 #include "MemIndex.h"
22 #include "Merge.h"
23 #include "clang/Lex/Preprocessor.h"
24 #include <memory>
25
26 namespace clang {
27 namespace clangd {
28
29 /// Select between in-memory index implementations, which have tradeoffs.
30 enum class IndexType {
31 // MemIndex is trivially cheap to build, but has poor query performance.
32 Light,
33 // Dex is relatively expensive to build and uses more memory, but is fast.
34 Heavy,
35 };
36
37 /// How to handle duplicated symbols across multiple files.
38 enum class DuplicateHandling {
39 // Pick a random symbol. Less accurate but faster.
40 PickOne,
41 // Merge symbols. More accurate but slower.
42 Merge,
43 };
44
45 /// A container of Symbols from several source files. It can be updated
46 /// at source-file granularity, replacing all symbols from one file with a new
47 /// set.
48 ///
49 /// This implements a snapshot semantics for symbols in a file. Each update to a
50 /// file will create a new snapshot for all symbols in the file. Snapshots are
51 /// managed with shared pointers that are shared between this class and the
52 /// users. For each file, this class only stores a pointer pointing to the
53 /// newest snapshot, and an outdated snapshot is deleted by the last owner of
54 /// the snapshot, either this class or the symbol index.
55 ///
56 /// The snapshot semantics keeps critical sections minimal since we only need
57 /// locking when we swap or obtain references to snapshots.
58 class FileSymbols {
59 public:
60 /// Updates all symbols and refs in a file.
61 /// If either is nullptr, corresponding data for \p Path will be removed.
62 void update(PathRef Path, std::unique_ptr<SymbolSlab> Slab,
63 std::unique_ptr<RefSlab> Refs);
64
65 // The index keeps the symbols alive.
66 std::unique_ptr<SymbolIndex>
67 buildIndex(IndexType,
68 DuplicateHandling DuplicateHandle = DuplicateHandling::PickOne);
69
70 private:
71 mutable std::mutex Mutex;
72
73 /// Stores the latest symbol snapshots for all active files.
74 llvm::StringMap<std::shared_ptr<SymbolSlab>> FileToSymbols;
75 /// Stores the latest ref snapshots for all active files.
76 llvm::StringMap<std::shared_ptr<RefSlab>> FileToRefs;
77 };
78
79 /// This manages symbols from files and an in-memory index on all symbols.
80 /// FIXME: Expose an interface to remove files that are closed.
81 class FileIndex : public MergedIndex {
82 public:
83 FileIndex(bool UseDex = true);
84
85 /// Update preamble symbols of file \p Path with all declarations in \p AST
86 /// and macros in \p PP.
87 void updatePreamble(PathRef Path, ASTContext &AST,
88 std::shared_ptr<Preprocessor> PP);
89
90 /// Update symbols and references from main file \p Path with
91 /// `indexMainDecls`.
92 void updateMain(PathRef Path, ParsedAST &AST);
93
94 private:
95 bool UseDex; // FIXME: this should be always on.
96
97 // Contains information from each file's preamble only.
98 // These are large, but update fairly infrequently (preambles are stable).
99 // Missing information:
100 // - symbol refs (these are always "from the main file")
101 // - definition locations in the main file
102 //
103 // FIXME: Because the preambles for different TUs have large overlap and
104 // FileIndex doesn't deduplicate, this uses lots of extra RAM.
105 // The biggest obstacle in fixing this: the obvious approach of partitioning
106 // by declaring file (rather than main file) fails if headers provide
107 // different symbols based on preprocessor state.
108 FileSymbols PreambleSymbols;
109 SwapIndex PreambleIndex;
110
111 // Contains information from each file's main AST.
112 // These are updated frequently (on file change), but are relatively small.
113 // Mostly contains:
114 // - refs to symbols declared in the preamble and referenced from main
115 // - symbols declared both in the main file and the preamble
116 // (Note that symbols *only* in the main file are not indexed).
117 FileSymbols MainFileSymbols;
118 SwapIndex MainFileIndex;
119 };
120
121 /// Retrieves symbols and refs of local top level decls in \p AST (i.e.
122 /// `AST.getLocalTopLevelDecls()`).
123 /// Exposed to assist in unit tests.
124 std::pair<SymbolSlab, RefSlab> indexMainDecls(ParsedAST &AST);
125
126 /// Idex declarations from \p AST and macros from \p PP that are declared in
127 /// included headers.
128 SymbolSlab indexHeaderSymbols(ASTContext &AST,
129 std::shared_ptr<Preprocessor> PP);
130
131 } // namespace clangd
132 } // namespace clang
133
134 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_FILEINDEX_H
clang::clangd::SymbolSlab
Definition: Index.h:292
clang::clangd::indexHeaderSymbols
SymbolSlab indexHeaderSymbols(ASTContext &AST, std::shared_ptr< Preprocessor > PP)
Idex declarations from AST and macros from PP that are declared in included headers.
Definition: FileIndex.cpp:80
Index.h
clang::clangd::IndexType
IndexType
Select between in-memory index implementations, which have tradeoffs.
Definition: FileIndex.h:30
clang::clangd::FileSymbols
A container of Symbols from several source files.
Definition: FileIndex.h:58
clang::clangd::IndexType::Light
clang::clangd::FileIndex
This manages symbols from files and an in-memory index on all symbols.
Definition: FileIndex.h:81
clang::clangd::DuplicateHandling::Merge
MemIndex.h
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:24
ClangdUnit.h
clang::clangd::UseDex
static llvm::cl::opt< bool > UseDex("use-dex-index", llvm::cl::desc("Use experimental Dex dynamic index."), llvm::cl::init(false), llvm::cl::Hidden)
clang::clangd::DuplicateHandling
DuplicateHandling
How to handle duplicated symbols across multiple files.
Definition: FileIndex.h:38
clang::clangd::SymbolOrigin::AST
clang::clangd::indexMainDecls
std::pair< SymbolSlab, RefSlab > indexMainDecls(ParsedAST &AST)
Retrieves symbols and refs of local top level decls in AST (i.e.
Definition: FileIndex.cpp:74
clang::clangd::Path
std::string Path
A typedef to represent a file path.
Definition: Path.h:21
clang::clangd::ParsedAST
Stores and provides access to parsed AST.
Definition: ClangdUnit.h:71
clang::clangd::SwapIndex
Definition: Index.h:523
clang::clangd::DuplicateHandling::PickOne
Merge.h
clang::clangd::IndexType::Heavy
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ChangeNamespace.cpp:18
clang::clangd::MergedIndex
Definition: Merge.h:31