clang  9.0.0svn
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 <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.
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.
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:
124 
125  /// An error code returned when trying to read an index.
126  enum ErrorCode {
127  /// No error occurred.
129  /// No index was found.
131  /// Some other process is currently building the index; it is not
132  /// available yet.
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,
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
Implements support for file system lookup, file system caching, and directory search management...
Definition: FileManager.h:116
DominatorTree GraphTraits specialization so the DominatorTree can be iterable by generic graph iterat...
Definition: Dominators.h:29
llvm::SmallPtrSet< ModuleFile *, 4 > HitSet
A set of module files in which we found a result.
static void dump(llvm::raw_ostream &OS, StringRef FunctionName, ArrayRef< CounterExpression > Expressions, ArrayRef< CounterMappingRegion > Regions)
ErrorCode
An error code returned when trying to read an index.
This abstract interface provides operations for unwrapping containers for serialized ASTs (precompile...
Information about a module that has been loaded by the ASTReader.
Definition: Module.h:107
An iterator that walks over all of the known identifiers in the lookup table.
A global index for a set of module files, providing information about the identifiers within those mo...
Dataflow Directional Tag Classes.
Some other process is currently building the index; it is not available yet.