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