1 //===- ModuleLoader.h - Module Loader Interface -----------------*- 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 ModuleLoader interface, which is responsible for
11 //  loading named modules.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 #ifndef LLVM_CLANG_LEX_MODULELOADER_H
16 #define LLVM_CLANG_LEX_MODULELOADER_H
17 
18 #include "clang/Basic/LLVM.h"
19 #include "clang/Basic/Module.h"
20 #include "clang/Basic/SourceLocation.h"
21 #include "llvm/ADT/ArrayRef.h"
22 #include "llvm/ADT/PointerIntPair.h"
23 #include "llvm/ADT/StringRef.h"
24 #include <utility>
25 
26 namespace clang {
27 
28 class GlobalModuleIndex;
29 class IdentifierInfo;
30 
31 /// A sequence of identifier/location pairs used to describe a particular
32 /// module or submodule, e.g., std.vector.
33 using ModuleIdPath = ArrayRef<std::pair<IdentifierInfo *, SourceLocation>>;
34 
35 /// Describes the result of attempting to load a module.
36 class ModuleLoadResult {
37 public:
38   enum LoadResultKind {
39     // We either succeeded or failed to load the named module.
40     Normal,
41 
42     // The module exists, but does not actually contain the named submodule.
43     // This should only happen if the named submodule was inferred from an
44     // umbrella directory, but not actually part of the umbrella header.
45     MissingExpected,
46 
47     // The module exists but cannot be imported due to a configuration mismatch.
48     ConfigMismatch
49   };
50   llvm::PointerIntPair<Module *, 2, LoadResultKind> Storage;
51 
52   ModuleLoadResult() = default;
ModuleLoadResult(Module * M)53   ModuleLoadResult(Module *M) : Storage(M, Normal) {}
ModuleLoadResult(LoadResultKind Kind)54   ModuleLoadResult(LoadResultKind Kind) : Storage(nullptr, Kind) {}
55 
56   operator Module *() const { return Storage.getPointer(); }
57 
58   /// Determines whether the module, which failed to load, was
59   /// actually a submodule that we expected to see (based on implying the
60   /// submodule from header structure), but didn't materialize in the actual
61   /// module.
isMissingExpected()62   bool isMissingExpected() const { return Storage.getInt() == MissingExpected; }
63 
64   /// Determines whether the module failed to load due to a configuration
65   /// mismatch with an explicitly-named .pcm file from the command line.
isConfigMismatch()66   bool isConfigMismatch() const { return Storage.getInt() == ConfigMismatch; }
67 };
68 
69 /// Abstract interface for a module loader.
70 ///
71 /// This abstract interface describes a module loader, which is responsible
72 /// for resolving a module name (e.g., "std") to an actual module file, and
73 /// then loading that module.
74 class ModuleLoader {
75   // Building a module if true.
76   bool BuildingModule;
77 
78 public:
79   explicit ModuleLoader(bool BuildingModule = false)
BuildingModule(BuildingModule)80       : BuildingModule(BuildingModule) {}
81 
82   virtual ~ModuleLoader();
83 
84   /// Returns true if this instance is building a module.
buildingModule()85   bool buildingModule() const {
86     return BuildingModule;
87   }
88 
89   /// Flag indicating whether this instance is building a module.
setBuildingModule(bool BuildingModuleFlag)90   void setBuildingModule(bool BuildingModuleFlag) {
91     BuildingModule = BuildingModuleFlag;
92   }
93 
94   /// Attempt to load the given module.
95   ///
96   /// This routine attempts to load the module described by the given
97   /// parameters.
98   ///
99   /// \param ImportLoc The location of the 'import' keyword.
100   ///
101   /// \param Path The identifiers (and their locations) of the module
102   /// "path", e.g., "std.vector" would be split into "std" and "vector".
103   ///
104   /// \param Visibility The visibility provided for the names in the loaded
105   /// module.
106   ///
107   /// \param IsInclusionDirective Indicates that this module is being loaded
108   /// implicitly, due to the presence of an inclusion directive. Otherwise,
109   /// it is being loaded due to an import declaration.
110   ///
111   /// \returns If successful, returns the loaded module. Otherwise, returns
112   /// NULL to indicate that the module could not be loaded.
113   virtual ModuleLoadResult loadModule(SourceLocation ImportLoc,
114                                       ModuleIdPath Path,
115                                       Module::NameVisibilityKind Visibility,
116                                       bool IsInclusionDirective) = 0;
117 
118   /// Attempt to load the given module from the specified source buffer. Does
119   /// not make any submodule visible; for that, use loadModule or
120   /// makeModuleVisible.
121   ///
122   /// \param Loc The location at which the module was loaded.
123   /// \param ModuleName The name of the module to build.
124   /// \param Source The source of the module: a (preprocessed) module map.
125   virtual void loadModuleFromSource(SourceLocation Loc, StringRef ModuleName,
126                                     StringRef Source) = 0;
127 
128   /// Make the given module visible.
129   virtual void makeModuleVisible(Module *Mod,
130                                  Module::NameVisibilityKind Visibility,
131                                  SourceLocation ImportLoc) = 0;
132 
133   /// Load, create, or return global module.
134   /// This function returns an existing global module index, if one
135   /// had already been loaded or created, or loads one if it
136   /// exists, or creates one if it doesn't exist.
137   /// Also, importantly, if the index doesn't cover all the modules
138   /// in the module map, it will be update to do so here, because
139   /// of its use in searching for needed module imports and
140   /// associated fixit messages.
141   /// \param TriggerLoc The location for what triggered the load.
142   /// \returns Returns null if load failed.
143   virtual GlobalModuleIndex *loadGlobalModuleIndex(
144                                                 SourceLocation TriggerLoc) = 0;
145 
146   /// Check global module index for missing imports.
147   /// \param Name The symbol name to look for.
148   /// \param TriggerLoc The location for what triggered the load.
149   /// \returns Returns true if any modules with that symbol found.
150   virtual bool lookupMissingImports(StringRef Name,
151                                     SourceLocation TriggerLoc) = 0;
152 
153   bool HadFatalFailure = false;
154 };
155 
156 /// A module loader that doesn't know how to load modules.
157 class TrivialModuleLoader : public ModuleLoader {
158 public:
loadModule(SourceLocation ImportLoc,ModuleIdPath Path,Module::NameVisibilityKind Visibility,bool IsInclusionDirective)159   ModuleLoadResult loadModule(SourceLocation ImportLoc, ModuleIdPath Path,
160                               Module::NameVisibilityKind Visibility,
161                               bool IsInclusionDirective) override {
162     return {};
163   }
164 
loadModuleFromSource(SourceLocation ImportLoc,StringRef ModuleName,StringRef Source)165   void loadModuleFromSource(SourceLocation ImportLoc, StringRef ModuleName,
166                             StringRef Source) override {}
167 
makeModuleVisible(Module * Mod,Module::NameVisibilityKind Visibility,SourceLocation ImportLoc)168   void makeModuleVisible(Module *Mod, Module::NameVisibilityKind Visibility,
169                          SourceLocation ImportLoc) override {}
170 
loadGlobalModuleIndex(SourceLocation TriggerLoc)171   GlobalModuleIndex *loadGlobalModuleIndex(SourceLocation TriggerLoc) override {
172     return nullptr;
173   }
174 
lookupMissingImports(StringRef Name,SourceLocation TriggerLoc)175   bool lookupMissingImports(StringRef Name,
176                             SourceLocation TriggerLoc) override {
177     return false;
178   }
179 };
180 
181 } // namespace clang
182 
183 #endif // LLVM_CLANG_LEX_MODULELOADER_H
184