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