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