clang 20.0.0git
GlobalModuleIndex.h
Go to the documentation of this file.
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.
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.
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.
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:
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.
138
139 /// Retrieve the set of module files on which the given module file
140 /// directly depends.
143
144 /// A set of module files in which we found a result.
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.
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
IndirectLocalPath & Path
Implements support for file system lookup, file system caching, and directory search management.
Definition: FileManager.h:53
A global index for a set of module files, providing information about the identifiers within those mo...
bool loadedModuleFile(ModuleFile *File)
Note that the given module file has been loaded.
void printStats()
Print statistics to standard error.
llvm::SmallPtrSet< ModuleFile *, 4 > HitSet
A set of module files in which we found a result.
bool lookupIdentifier(llvm::StringRef Name, HitSet &Hits)
Look for all of the module files with information about the given identifier, e.g....
void getModuleDependencies(ModuleFile *File, llvm::SmallVectorImpl< ModuleFile * > &Dependencies)
Retrieve the set of module files on which the given module file directly depends.
IdentifierIterator * createIdentifierIterator() const
Returns an iterator for identifiers stored in the index table.
static std::pair< GlobalModuleIndex *, llvm::Error > readIndex(llvm::StringRef Path)
Read a global index file for the given directory.
void dump()
Print debugging view to standard error.
static llvm::Error writeIndex(FileManager &FileMgr, const PCHContainerReader &PCHContainerRdr, llvm::StringRef Path)
Write a global index into the given.
An iterator that walks over all of the known identifiers in the lookup table.
This abstract interface provides operations for unwrapping containers for serialized ASTs (precompile...
Information about a module that has been loaded by the ASTReader.
Definition: ModuleFile.h:124
@ ModuleFile
The module file (.pcm). Required.
The JSON file list parser is used to communicate input to InstallAPI.
Diagnostic wrappers for TextAPI types for error reporting.
Definition: Dominators.h:30