clang API Documentation

GlobalModuleIndex.h
Go to the documentation of this file.
00001 //===--- GlobalModuleIndex.h - Global Module Index --------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file defines the GlobalModuleIndex class, which manages a global index
00011 // containing all of the identifiers known to the various modules within a given
00012 // subdirectory of the module cache. It is used to improve the performance of
00013 // queries such as "do any modules know about this identifier?"
00014 //
00015 //===----------------------------------------------------------------------===//
00016 #ifndef LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
00017 #define LLVM_CLANG_SERIALIZATION_GLOBALMODULEINDEX_H
00018 
00019 #include "llvm/ADT/DenseMap.h"
00020 #include "llvm/ADT/SmallPtrSet.h"
00021 #include "llvm/ADT/SmallVector.h"
00022 #include "llvm/ADT/StringMap.h"
00023 #include "llvm/ADT/StringRef.h"
00024 #include <memory>
00025 #include <utility>
00026 
00027 namespace llvm {
00028 class BitstreamCursor;
00029 class MemoryBuffer;
00030 }
00031 
00032 namespace clang {
00033 
00034 class DirectoryEntry;
00035 class FileEntry;
00036 class FileManager;
00037 class IdentifierIterator;
00038 
00039 namespace serialization {
00040   class ModuleFile;
00041 }
00042 
00043 using llvm::SmallVector;
00044 using llvm::SmallVectorImpl;
00045 using llvm::StringRef;
00046 using serialization::ModuleFile;
00047 
00048 /// \brief A global index for a set of module files, providing information about
00049 /// the identifiers within those module files.
00050 ///
00051 /// The global index is an aid for name lookup into modules, offering a central
00052 /// place where one can look for identifiers determine which
00053 /// module files contain any information about that identifier. This
00054 /// allows the client to restrict the search to only those module files known
00055 /// to have a information about that identifier, improving performance. Moreover,
00056 /// the global module index may know about module files that have not been
00057 /// imported, and can be queried to determine which modules the current
00058 /// translation could or should load to fix a problem.
00059 class GlobalModuleIndex {
00060   /// \brief Buffer containing the index file, which is lazily accessed so long
00061   /// as the global module index is live.
00062   std::unique_ptr<llvm::MemoryBuffer> Buffer;
00063 
00064   /// \brief The hash table.
00065   ///
00066   /// This pointer actually points to a IdentifierIndexTable object,
00067   /// but that type is only accessible within the implementation of
00068   /// GlobalModuleIndex.
00069   void *IdentifierIndex;
00070 
00071   /// \brief Information about a given module file.
00072   struct ModuleInfo {
00073     ModuleInfo() : File(), Size(), ModTime() { }
00074 
00075     /// \brief The module file, once it has been resolved.
00076     ModuleFile *File;
00077 
00078     /// \brief The module file name.
00079     std::string FileName;
00080 
00081     /// \brief Size of the module file at the time the global index was built.
00082     off_t Size;
00083 
00084     /// \brief Modification time of the module file at the time the global
00085     /// index was built.
00086     time_t ModTime;
00087 
00088     /// \brief The module IDs on which this module directly depends.
00089     /// FIXME: We don't really need a vector here.
00090     llvm::SmallVector<unsigned, 4> Dependencies;
00091   };
00092 
00093   /// \brief A mapping from module IDs to information about each module.
00094   ///
00095   /// This vector may have gaps, if module files have been removed or have
00096   /// been updated since the index was built. A gap is indicated by an empty
00097   /// file name.
00098   llvm::SmallVector<ModuleInfo, 16> Modules;
00099 
00100   /// \brief Lazily-populated mapping from module files to their
00101   /// corresponding index into the \c Modules vector.
00102   llvm::DenseMap<ModuleFile *, unsigned> ModulesByFile;
00103 
00104   /// \brief The set of modules that have not yet been resolved.
00105   ///
00106   /// The string is just the name of the module itself, which maps to the
00107   /// module ID.
00108   llvm::StringMap<unsigned> UnresolvedModules;
00109 
00110   /// \brief The number of identifier lookups we performed.
00111   unsigned NumIdentifierLookups;
00112 
00113   /// \brief The number of identifier lookup hits, where we recognize the
00114   /// identifier.
00115   unsigned NumIdentifierLookupHits;
00116   
00117   /// \brief Internal constructor. Use \c readIndex() to read an index.
00118   explicit GlobalModuleIndex(std::unique_ptr<llvm::MemoryBuffer> Buffer,
00119                              llvm::BitstreamCursor Cursor);
00120 
00121   GlobalModuleIndex(const GlobalModuleIndex &) LLVM_DELETED_FUNCTION;
00122   GlobalModuleIndex &operator=(const GlobalModuleIndex &) LLVM_DELETED_FUNCTION;
00123 
00124 public:
00125   ~GlobalModuleIndex();
00126 
00127   /// \brief An error code returned when trying to read an index.
00128   enum ErrorCode {
00129     /// \brief No error occurred.
00130     EC_None,
00131     /// \brief No index was found.
00132     EC_NotFound,
00133     /// \brief Some other process is currently building the index; it is not
00134     /// available yet.
00135     EC_Building,
00136     /// \brief There was an unspecified I/O error reading or writing the index.
00137     EC_IOError
00138   };
00139 
00140   /// \brief Read a global index file for the given directory.
00141   ///
00142   /// \param Path The path to the specific module cache where the module files
00143   /// for the intended configuration reside.
00144   ///
00145   /// \returns A pair containing the global module index (if it exists) and
00146   /// the error code.
00147   static std::pair<GlobalModuleIndex *, ErrorCode>
00148   readIndex(StringRef Path);
00149 
00150   /// \brief Returns an iterator for identifiers stored in the index table.
00151   ///
00152   /// The caller accepts ownership of the returned object.
00153   IdentifierIterator *createIdentifierIterator() const;
00154 
00155   /// \brief Retrieve the set of modules that have up-to-date indexes.
00156   ///
00157   /// \param ModuleFiles Will be populated with the set of module files that
00158   /// have been indexed.
00159   void getKnownModules(SmallVectorImpl<ModuleFile *> &ModuleFiles);
00160 
00161   /// \brief Retrieve the set of module files on which the given module file
00162   /// directly depends.
00163   void getModuleDependencies(ModuleFile *File,
00164                              SmallVectorImpl<ModuleFile *> &Dependencies);
00165 
00166   /// \brief A set of module files in which we found a result.
00167   typedef llvm::SmallPtrSet<ModuleFile *, 4> HitSet;
00168   
00169   /// \brief Look for all of the module files with information about the given
00170   /// identifier, e.g., a global function, variable, or type with that name.
00171   ///
00172   /// \param Name The identifier to look for.
00173   ///
00174   /// \param Hits Will be populated with the set of module files that have
00175   /// information about this name.
00176   ///
00177   /// \returns true if the identifier is known to the index, false otherwise.
00178   bool lookupIdentifier(StringRef Name, HitSet &Hits);
00179 
00180   /// \brief Note that the given module file has been loaded.
00181   ///
00182   /// \returns false if the global module index has information about this
00183   /// module file, and true otherwise.
00184   bool loadedModuleFile(ModuleFile *File);
00185 
00186   /// \brief Print statistics to standard error.
00187   void printStats();
00188 
00189   /// \brief Print debugging view to standard error.
00190   void dump();
00191 
00192   /// \brief Write a global index into the given
00193   ///
00194   /// \param FileMgr The file manager to use to load module files.
00195   ///
00196   /// \param Path The path to the directory containing module files, into
00197   /// which the global index will be written.
00198   static ErrorCode writeIndex(FileManager &FileMgr, StringRef Path);
00199 };
00200 
00201 }
00202 
00203 #endif