llvm/include/llvm/ExecutionEngine/Orc/Layer.h

   1 //===---------------- Layer.h -- Layer interfaces --------------*- 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 // Layer interfaces.
  10 //
  11 //===----------------------------------------------------------------------===//
  12
  13 #ifndef LLVM_EXECUTIONENGINE_ORC_LAYER_H
  14 #define LLVM_EXECUTIONENGINE_ORC_LAYER_H
  15
  16 #include "llvm/ExecutionEngine/Orc/Core.h"
  17 #include "llvm/ExecutionEngine/Orc/Mangling.h"
  18 #include "llvm/ExecutionEngine/Orc/ThreadSafeModule.h"
  19 #include "llvm/IR/Module.h"
  20 #include "llvm/Support/MemoryBuffer.h"
  21
  22 namespace llvm {
  23 namespace orc {
  24
  25 /// IRMaterializationUnit is a convenient base class for MaterializationUnits
  26 /// wrapping LLVM IR. Represents materialization responsibility for all symbols
  27 /// in the given module. If symbols are overridden by other definitions, then
  28 /// their linkage is changed to available-externally.
  29 class IRMaterializationUnit : public MaterializationUnit {
  30 public:
  31   using SymbolNameToDefinitionMap = std::map<SymbolStringPtr, GlobalValue *>;
  32
  33   /// Create an IRMaterializationLayer. Scans the module to build the
  34   /// SymbolFlags and SymbolToDefinition maps.
  35   IRMaterializationUnit(ExecutionSession &ES,
  36                         const IRSymbolMapper::ManglingOptions &MO,
  37                         ThreadSafeModule TSM);
  38
  39   /// Create an IRMaterializationLayer from a module, and pre-existing
  40   /// SymbolFlags and SymbolToDefinition maps. The maps must provide
  41   /// entries for each definition in M.
  42   /// This constructor is useful for delegating work from one
  43   /// IRMaterializationUnit to another.
  44   IRMaterializationUnit(ThreadSafeModule TSM, SymbolFlagsMap SymbolFlags,
  45                         SymbolStringPtr InitSymbol,
  46                         SymbolNameToDefinitionMap SymbolToDefinition);
  47
  48   /// Return the ModuleIdentifier as the name for this MaterializationUnit.
  49   StringRef getName() const override;
  50
  51   /// Return a reference to the contained ThreadSafeModule.
  52   const ThreadSafeModule &getModule() const { return TSM; }
  53
  54 protected:
  55   ThreadSafeModule TSM;
  56   SymbolNameToDefinitionMap SymbolToDefinition;
  57
  58 private:
  59   static SymbolStringPtr getInitSymbol(ExecutionSession &ES,
  60                                        const ThreadSafeModule &TSM);
  61
  62   void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;
  63 };
  64
  65 /// Interface for layers that accept LLVM IR.
  66 class IRLayer {
  67 public:
  68   IRLayer(ExecutionSession &ES, const IRSymbolMapper::ManglingOptions *&MO)
  69       : ES(ES), MO(MO) {}
  70
  71   virtual ~IRLayer();
  72
  73   /// Returns the ExecutionSession for this layer.
  74   ExecutionSession &getExecutionSession() { return ES; }
  75
  76   /// Get the mangling options for this layer.
  77   const IRSymbolMapper::ManglingOptions *&getManglingOptions() const {
  78     return MO;
  79   }
  80
  81   /// Sets the CloneToNewContextOnEmit flag (false by default).
  82   ///
  83   /// When set, IR modules added to this layer will be cloned on to a new
  84   /// context before emit is called. This can be used by clients who want
  85   /// to load all IR using one LLVMContext (to save memory via type and
  86   /// constant uniquing), but want to move Modules to fresh contexts before
  87   /// compiling them to enable concurrent compilation.
  88   /// Single threaded clients, or clients who load every module on a new
  89   /// context, need not set this.
  90   void setCloneToNewContextOnEmit(bool CloneToNewContextOnEmit) {
  91     this->CloneToNewContextOnEmit = CloneToNewContextOnEmit;
  92   }
  93
  94   /// Returns the current value of the CloneToNewContextOnEmit flag.
  95   bool getCloneToNewContextOnEmit() const { return CloneToNewContextOnEmit; }
  96
  97   /// Add a MaterializatinoUnit representing the given IR to the JITDylib
  98   /// targeted by the given tracker.
  99   virtual Error add(ResourceTrackerSP RT, ThreadSafeModule TSM);
 100
 101   /// Adds a MaterializationUnit representing the given IR to the given
 102   /// JITDylib. If RT is not specif
 103   Error add(JITDylib &JD, ThreadSafeModule TSM) {
 104     return add(JD.getDefaultResourceTracker(), std::move(TSM));
 105   }
 106
 107   /// Emit should materialize the given IR.
 108   virtual void emit(std::unique_ptr<MaterializationResponsibility> R,
 109                     ThreadSafeModule TSM) = 0;
 110
 111 private:
 112   bool CloneToNewContextOnEmit = false;
 113   ExecutionSession &ES;
 114   const IRSymbolMapper::ManglingOptions *&MO;
 115 };
 116
 117 /// MaterializationUnit that materializes modules by calling the 'emit' method
 118 /// on the given IRLayer.
 119 class BasicIRLayerMaterializationUnit : public IRMaterializationUnit {
 120 public:
 121   BasicIRLayerMaterializationUnit(IRLayer &L,
 122                                   const IRSymbolMapper::ManglingOptions &MO,
 123                                   ThreadSafeModule TSM);
 124
 125 private:
 126   void materialize(std::unique_ptr<MaterializationResponsibility> R) override;
 127
 128   IRLayer &L;
 129 };
 130
 131 /// Interface for Layers that accept object files.
 132 class ObjectLayer {
 133 public:
 134   ObjectLayer(ExecutionSession &ES);
 135   virtual ~ObjectLayer();
 136
 137   /// Returns the execution session for this layer.
 138   ExecutionSession &getExecutionSession() { return ES; }
 139
 140   /// Adds a MaterializationUnit representing the given IR to the given
 141   /// JITDylib.
 142   virtual Error add(ResourceTrackerSP RT, std::unique_ptr<MemoryBuffer> O);
 143
 144   Error add(JITDylib &JD, std::unique_ptr<MemoryBuffer> O) {
 145     return add(JD.getDefaultResourceTracker(), std::move(O));
 146   }
 147
 148   /// Emit should materialize the given IR.
 149   virtual void emit(std::unique_ptr<MaterializationResponsibility> R,
 150                     std::unique_ptr<MemoryBuffer> O) = 0;
 151
 152 private:
 153   ExecutionSession &ES;
 154 };
 155
 156 /// Materializes the given object file (represented by a MemoryBuffer
 157 /// instance) by calling 'emit' on the given ObjectLayer.
 158 class BasicObjectLayerMaterializationUnit : public MaterializationUnit {
 159 public:
 160   static Expected<std::unique_ptr<BasicObjectLayerMaterializationUnit>>
 161   Create(ObjectLayer &L, std::unique_ptr<MemoryBuffer> O);
 162
 163   BasicObjectLayerMaterializationUnit(ObjectLayer &L,
 164                                       std::unique_ptr<MemoryBuffer> O,
 165                                       SymbolFlagsMap SymbolFlags,
 166                                       SymbolStringPtr InitSymbol);
 167
 168   /// Return the buffer's identifier as the name for this MaterializationUnit.
 169   StringRef getName() const override;
 170
 171 private:
 172   void materialize(std::unique_ptr<MaterializationResponsibility> R) override;
 173   void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;
 174
 175   ObjectLayer &L;
 176   std::unique_ptr<MemoryBuffer> O;
 177 };
 178
 179 } // End namespace orc
 180 } // End namespace llvm
 181
 182 #endif // LLVM_EXECUTIONENGINE_ORC_LAYER_H