ExecutionEngine/Orc/MaterializationUnit.h

0001 //===---- MaterializationUnit.h -- Materialization Black Box ----*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // MaterializationUnit class and related types and operations.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_EXECUTIONENGINE_ORC_MATERIALIZATIONUNIT_H
0014 #define LLVM_EXECUTIONENGINE_ORC_MATERIALIZATIONUNIT_H
0015
0016 #include "llvm/ADT/StringRef.h"
0017 #include "llvm/ExecutionEngine/Orc/CoreContainers.h"
0018 #include "llvm/ExecutionEngine/Orc/SymbolStringPool.h"
0019
0020 namespace llvm::orc {
0021
0022 class MaterializationResponsibility;
0023
0024 /// A MaterializationUnit represents a set of symbol definitions that can
0025 ///        be materialized as a group, or individually discarded (when
0026 ///        overriding definitions are encountered).
0027 ///
0028 /// MaterializationUnits are used when providing lazy definitions of symbols to
0029 /// JITDylibs. The JITDylib will call materialize when the address of a symbol
0030 /// is requested via the lookup method. The JITDylib will call discard if a
0031 /// stronger definition is added or already present.
0032 class MaterializationUnit {
0033   friend class ExecutionSession;
0034   friend class JITDylib;
0035
0036 public:
0037   static char ID;
0038
0039   struct Interface {
0040     Interface() = default;
0041     Interface(SymbolFlagsMap InitalSymbolFlags, SymbolStringPtr InitSymbol)
0042         : SymbolFlags(std::move(InitalSymbolFlags)),
0043           InitSymbol(std::move(InitSymbol)) {
0044       assert((!this->InitSymbol || this->SymbolFlags.count(this->InitSymbol)) &&
0045              "If set, InitSymbol should appear in InitialSymbolFlags map");
0046     }
0047
0048     SymbolFlagsMap SymbolFlags;
0049     SymbolStringPtr InitSymbol;
0050   };
0051
0052   MaterializationUnit(Interface I)
0053       : SymbolFlags(std::move(I.SymbolFlags)),
0054         InitSymbol(std::move(I.InitSymbol)) {}
0055   virtual ~MaterializationUnit() = default;
0056
0057   /// Return the name of this materialization unit. Useful for debugging
0058   /// output.
0059   virtual StringRef getName() const = 0;
0060
0061   /// Return the set of symbols that this source provides.
0062   const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }
0063
0064   /// Returns the initialization symbol for this MaterializationUnit (if any).
0065   const SymbolStringPtr &getInitializerSymbol() const { return InitSymbol; }
0066
0067   /// Implementations of this method should materialize all symbols
0068   ///        in the materialzation unit, except for those that have been
0069   ///        previously discarded.
0070   virtual void
0071   materialize(std::unique_ptr<MaterializationResponsibility> R) = 0;
0072
0073   /// Called by JITDylibs to notify MaterializationUnits that the given symbol
0074   /// has been overridden.
0075   void doDiscard(const JITDylib &JD, const SymbolStringPtr &Name) {
0076     SymbolFlags.erase(Name);
0077     if (InitSymbol == Name) {
0078       DEBUG_WITH_TYPE("orc", {
0079         dbgs() << "In " << getName() << ": discarding init symbol \""
0080                << *Name << "\"\n";
0081       });
0082       InitSymbol = nullptr;
0083     }
0084     discard(JD, std::move(Name));
0085   }
0086
0087 protected:
0088   SymbolFlagsMap SymbolFlags;
0089   SymbolStringPtr InitSymbol;
0090
0091 private:
0092   virtual void anchor();
0093
0094   /// Implementations of this method should discard the given symbol
0095   ///        from the source (e.g. if the source is an LLVM IR Module and the
0096   ///        symbol is a function, delete the function body or mark it available
0097   ///        externally).
0098   virtual void discard(const JITDylib &JD, const SymbolStringPtr &Name) = 0;
0099 };
0100
0101 } // namespace llvm::orc
0102
0103 #endif // LLVM_EXECUTIONENGINE_ORC_MATERIALIZATIONUNIT_H