contrib/llvm/tools/clang/include/clang/Serialization/GlobalModuleIndex.h

   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 {
  75     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