contrib/llvm-project/clang/include/clang/Serialization/GlobalModuleIndex.h

   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
  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 /// A global index for a set of module files, providing information about
  46 /// the identifiers within those module files.
  47 ///
  48 /// The global index is an aid for name lookup into modules, offering a central
  49 /// place where one can look for identifiers determine which
  50 /// module files contain any information about that identifier. This
  51 /// allows the client to restrict the search to only those module files known
  52 /// to have a information about that identifier, improving performance. Moreover,
  53 /// the global module index may know about module files that have not been
  54 /// imported, and can be queried to determine which modules the current
  55 /// translation could or should load to fix a problem.
  56 class GlobalModuleIndex {
  57   using ModuleFile = serialization::ModuleFile;
  58
  59   /// Buffer containing the index file, which is lazily accessed so long
  60   /// as the global module index is live.
  61   std::unique_ptr<llvm::MemoryBuffer> Buffer;
  62
  63   /// 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   /// Information about a given module file.
  71   struct ModuleInfo {
  72     ModuleInfo() : File(), Size(), ModTime() { }
  73
  74     /// The module file, once it has been resolved.
  75     ModuleFile *File;
  76
  77     /// The module file name.
  78     std::string FileName;
  79
  80     /// Size of the module file at the time the global index was built.
  81     off_t Size;
  82
  83     /// Modification time of the module file at the time the global
  84     /// index was built.
  85     time_t ModTime;
  86
  87     /// 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   /// 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   /// Lazily-populated mapping from module files to their
 100   /// corresponding index into the \c Modules vector.
 101   llvm::DenseMap<ModuleFile *, unsigned> ModulesByFile;
 102
 103   /// 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   /// The number of identifier lookups we performed.
 110   unsigned NumIdentifierLookups;
 111
 112   /// The number of identifier lookup hits, where we recognize the
 113   /// identifier.
 114   unsigned NumIdentifierLookupHits;
 115
 116   /// Internal constructor. Use \c readIndex() to read an index.
 117   explicit GlobalModuleIndex(std::unique_ptr<llvm::MemoryBuffer> Buffer,
 118                              llvm::BitstreamCursor Cursor);
 119
 120   GlobalModuleIndex(const GlobalModuleIndex &) = delete;
 121   GlobalModuleIndex &operator=(const GlobalModuleIndex &) = delete;
 122
 123 public:
 124   ~GlobalModuleIndex();
 125
 126   /// Read a global index file for the given directory.
 127   ///
 128   /// \param Path The path to the specific module cache where the module files
 129   /// for the intended configuration reside.
 130   ///
 131   /// \returns A pair containing the global module index (if it exists) and
 132   /// the error.
 133   static std::pair<GlobalModuleIndex *, llvm::Error>
 134   readIndex(llvm::StringRef Path);
 135
 136   /// Returns an iterator for identifiers stored in the index table.
 137   ///
 138   /// The caller accepts ownership of the returned object.
 139   IdentifierIterator *createIdentifierIterator() const;
 140
 141   /// Retrieve the set of modules that have up-to-date indexes.
 142   ///
 143   /// \param ModuleFiles Will be populated with the set of module files that
 144   /// have been indexed.
 145   void getKnownModules(llvm::SmallVectorImpl<ModuleFile *> &ModuleFiles);
 146
 147   /// Retrieve the set of module files on which the given module file
 148   /// directly depends.
 149   void getModuleDependencies(ModuleFile *File,
 150                              llvm::SmallVectorImpl<ModuleFile *> &Dependencies);
 151
 152   /// A set of module files in which we found a result.
 153   typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet;
 154
 155   /// Look for all of the module files with information about the given
 156   /// identifier, e.g., a global function, variable, or type with that name.
 157   ///
 158   /// \param Name The identifier to look for.
 159   ///
 160   /// \param Hits Will be populated with the set of module files that have
 161   /// information about this name.
 162   ///
 163   /// \returns true if the identifier is known to the index, false otherwise.
 164   bool lookupIdentifier(llvm::StringRef Name, HitSet &Hits);
 165
 166   /// Note that the given module file has been loaded.
 167   ///
 168   /// \returns false if the global module index has information about this
 169   /// module file, and true otherwise.
 170   bool loadedModuleFile(ModuleFile *File);
 171
 172   /// Print statistics to standard error.
 173   void printStats();
 174
 175   /// Print debugging view to standard error.
 176   void dump();
 177
 178   /// Write a global index into the given
 179   ///
 180   /// \param FileMgr The file manager to use to load module files.
 181   /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and
 182   /// creating modules.
 183   /// \param Path The path to the directory containing module files, into
 184   /// which the global index will be written.
 185   static llvm::Error writeIndex(FileManager &FileMgr,
 186                                 const PCHContainerReader &PCHContainerRdr,
 187                                 llvm::StringRef Path);
 188 };
 189 }
 190
 191 #endif