1//===--- GlobalModuleIndex.h - Global Module Index --------------*- 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// This file defines the GlobalModuleIndex class, which manages a global index
10// containing all of the identifiers known to the various modules within a given
11// subdirectory of the module cache. It is used to improve the performance of
12// queries such as "do any modules know about this identifier?"
13//
14//===----------------------------------------------------------------------===//
15#ifndef LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
16#define LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
17
18#include "llvm/ADT/DenseMap.h"
19#include "llvm/ADT/SmallPtrSet.h"
20#include "llvm/ADT/SmallVector.h"
21#include "llvm/ADT/StringMap.h"
22#include "llvm/ADT/StringRef.h"
23#include "llvm/Support/Error.h"
24#include <memory>
25#include <utility>
26
27namespace llvm {
28class BitstreamCursor;
29class MemoryBuffer;
30}
31
32namespace clang {
33
34class FileManager;
35class IdentifierIterator;
36class PCHContainerOperations;
37class PCHContainerReader;
38
39namespace serialization {
40 class ModuleFile;
41}
42
43/// A global index for a set of module files, providing information about
44/// the identifiers within those module files.
45///
46/// The global index is an aid for name lookup into modules, offering a central
47/// place where one can look for identifiers determine which
48/// module files contain any information about that identifier. This
49/// allows the client to restrict the search to only those module files known
50/// to have a information about that identifier, improving performance. Moreover,
51/// the global module index may know about module files that have not been
52/// imported, and can be queried to determine which modules the current
53/// translation could or should load to fix a problem.
54class GlobalModuleIndex {
55 using ModuleFile = serialization::ModuleFile;
56
57 /// Buffer containing the index file, which is lazily accessed so long
58 /// as the global module index is live.
59 std::unique_ptr<llvm::MemoryBuffer> Buffer;
60
61 /// The hash table.
62 ///
63 /// This pointer actually points to a IdentifierIndexTable object,
64 /// but that type is only accessible within the implementation of
65 /// GlobalModuleIndex.
66 void *IdentifierIndex;
67
68 /// Information about a given module file.
69 struct ModuleInfo {
70 ModuleInfo() = default;
71
72 /// The module file, once it has been resolved.
73 ModuleFile *File = nullptr;
74
75 /// The module file name.
76 std::string FileName;
77
78 /// Size of the module file at the time the global index was built.
79 off_t Size = 0;
80
81 /// Modification time of the module file at the time the global
82 /// index was built.
83 time_t ModTime = 0;
84
85 /// The module IDs on which this module directly depends.
86 /// FIXME: We don't really need a vector here.
87 llvm::SmallVector<unsigned, 4> Dependencies;
88 };
89
90 /// A mapping from module IDs to information about each module.
91 ///
92 /// This vector may have gaps, if module files have been removed or have
93 /// been updated since the index was built. A gap is indicated by an empty
94 /// file name.
95 llvm::SmallVector<ModuleInfo, 16> Modules;
96
97 /// Lazily-populated mapping from module files to their
98 /// corresponding index into the \c Modules vector.
99 llvm::DenseMap<ModuleFile *, unsigned> ModulesByFile;
100
101 /// The set of modules that have not yet been resolved.
102 ///
103 /// The string is just the name of the module itself, which maps to the
104 /// module ID.
105 llvm::StringMap<unsigned> UnresolvedModules;
106
107 /// The number of identifier lookups we performed.
108 unsigned NumIdentifierLookups;
109
110 /// The number of identifier lookup hits, where we recognize the
111 /// identifier.
112 unsigned NumIdentifierLookupHits;
113
114 /// Internal constructor. Use \c readIndex() to read an index.
115 explicit GlobalModuleIndex(std::unique_ptr<llvm::MemoryBuffer> Buffer,
116 llvm::BitstreamCursor Cursor);
117
118 GlobalModuleIndex(const GlobalModuleIndex &) = delete;
119 GlobalModuleIndex &operator=(const GlobalModuleIndex &) = delete;
120
121public:
122 ~GlobalModuleIndex();
123
124 /// Read a global index file for the given directory.
125 ///
126 /// \param Path The path to the specific module cache where the module files
127 /// for the intended configuration reside.
128 ///
129 /// \returns A pair containing the global module index (if it exists) and
130 /// the error.
131 static std::pair<GlobalModuleIndex *, llvm::Error>
132 readIndex(llvm::StringRef Path);
133
134 /// Returns an iterator for identifiers stored in the index table.
135 ///
136 /// The caller accepts ownership of the returned object.
137 IdentifierIterator *createIdentifierIterator() const;
138
139 /// Retrieve the set of module files on which the given module file
140 /// directly depends.
141 void getModuleDependencies(ModuleFile *File,
142 llvm::SmallVectorImpl<ModuleFile *> &Dependencies);
143
144 /// A set of module files in which we found a result.
145 typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet;
146
147 /// Look for all of the module files with information about the given
148 /// identifier, e.g., a global function, variable, or type with that name.
149 ///
150 /// \param Name The identifier to look for.
151 ///
152 /// \param Hits Will be populated with the set of module files that have
153 /// information about this name.
154 ///
155 /// \returns true if the identifier is known to the index, false otherwise.
156 bool lookupIdentifier(llvm::StringRef Name, HitSet &Hits);
157
158 /// Note that the given module file has been loaded.
159 ///
160 /// \returns false if the global module index has information about this
161 /// module file, and true otherwise.
162 bool loadedModuleFile(ModuleFile *File);
163
164 /// Print statistics to standard error.
165 void printStats();
166
167 /// Print debugging view to standard error.
168 void dump();
169
170 /// Write a global index into the given
171 ///
172 /// \param FileMgr The file manager to use to load module files.
173 /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and
174 /// creating modules.
175 /// \param Path The path to the directory containing module files, into
176 /// which the global index will be written.
177 static llvm::Error writeIndex(FileManager &FileMgr,
178 const PCHContainerReader &PCHContainerRdr,
179 llvm::StringRef Path);
180};
181}
182
183#endif
184

source code of clang/include/clang/Serialization/GlobalModuleIndex.h