GlobalModuleIndex.h source code [clang_source_code/include/clang/Serialization/GlobalModuleIndex.h]

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