Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===------ Core.h -- Core ORC APIs (Layer, JITDylib, etc.) -----*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

//

// Contains core ORC APIs.

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_EXECUTIONENGINE_ORC_CORE_H

#define LLVM_EXECUTIONENGINE_ORC_CORE_H

#include "llvm/ADT/BitmaskEnum.h"

#include "llvm/ADT/DenseSet.h"

#include "llvm/ADT/FunctionExtras.h"

#include "llvm/ADT/IntrusiveRefCntPtr.h"

#include "llvm/ExecutionEngine/JITLink/JITLinkDylib.h"

#include "llvm/ExecutionEngine/JITSymbol.h"

#include "llvm/ExecutionEngine/Orc/ExecutorProcessControl.h"

#include "llvm/ExecutionEngine/Orc/Shared/WrapperFunctionUtils.h"

#include "llvm/ExecutionEngine/Orc/TaskDispatch.h"

#include "llvm/Support/Debug.h"

#include "llvm/Support/ExtensibleRTTI.h"

#include <atomic>

#include <future>

#include <memory>

#include <vector>

namespace llvm {

namespace orc {

// Forward declare some classes.

class AsynchronousSymbolQuery;

class ExecutionSession;

class MaterializationUnit;

class MaterializationResponsibility;

class JITDylib;

class ResourceTracker;

class InProgressLookupState;

enum class SymbolState : uint8_t;

using ResourceTrackerSP = IntrusiveRefCntPtr<ResourceTracker>;

using JITDylibSP = IntrusiveRefCntPtr<JITDylib>;

using ResourceKey = uintptr_t;

/// API to remove / transfer ownership of JIT resources.

class ResourceTracker : public ThreadSafeRefCountedBase<ResourceTracker> {

private:

  friend class ExecutionSession;

  friend class JITDylib;

  friend class MaterializationResponsibility;

public:

  ResourceTracker(const ResourceTracker &) = delete;

  ResourceTracker &operator=(const ResourceTracker &) = delete;

  ResourceTracker(ResourceTracker &&) = delete;

  ResourceTracker &operator=(ResourceTracker &&) = delete;

  ~ResourceTracker();

  /// Return the JITDylib targeted by this tracker.

  JITDylib &getJITDylib() const {

    return *reinterpret_cast<JITDylib *>(JDAndFlag.load() &

                                         ~static_cast<uintptr_t>(1));

  }

  /// Runs the given callback under the session lock, passing in the associated

  /// ResourceKey. This is the safe way to associate resources with trackers.

  template <typename Func> Error withResourceKeyDo(Func &&F);

  /// Remove all resources associated with this key.

  Error remove();

  /// Transfer all resources associated with this key to the given

  /// tracker, which must target the same JITDylib as this one.

  void transferTo(ResourceTracker &DstRT);

  /// Return true if this tracker has become defunct.

  bool isDefunct() const { return JDAndFlag.load() & 0x1; }

  /// Returns the key associated with this tracker.

  /// This method should not be used except for debug logging: there is no

  /// guarantee that the returned value will remain valid.

  ResourceKey getKeyUnsafe() const { return reinterpret_cast<uintptr_t>(this); }

private:

  ResourceTracker(JITDylibSP JD);

  void makeDefunct();

  std::atomic_uintptr_t JDAndFlag;

};

/// Listens for ResourceTracker operations.

class ResourceManager {

public:

  virtual ~ResourceManager();

  virtual Error handleRemoveResources(JITDylib &JD, ResourceKey K) = 0;

  virtual void handleTransferResources(JITDylib &JD, ResourceKey DstK,

                                       ResourceKey SrcK) = 0;

};

/// A set of symbol names (represented by SymbolStringPtrs for

//         efficiency).

using SymbolNameSet = DenseSet<SymbolStringPtr>;

/// A vector of symbol names.

using SymbolNameVector = std::vector<SymbolStringPtr>;

/// A map from symbol names (as SymbolStringPtrs) to JITSymbols

/// (address/flags pairs).

using SymbolMap = DenseMap<SymbolStringPtr, JITEvaluatedSymbol>;

/// A map from symbol names (as SymbolStringPtrs) to JITSymbolFlags.

using SymbolFlagsMap = DenseMap<SymbolStringPtr, JITSymbolFlags>;

/// A map from JITDylibs to sets of symbols.

using SymbolDependenceMap = DenseMap<JITDylib *, SymbolNameSet>;

/// Lookup flags that apply to each dylib in the search order for a lookup.

///

/// If MatchHiddenSymbolsOnly is used (the default) for a given dylib, then

/// only symbols in that Dylib's interface will be searched. If

/// MatchHiddenSymbols is used then symbols with hidden visibility will match

/// as well.

enum class JITDylibLookupFlags { MatchExportedSymbolsOnly, MatchAllSymbols };

/// Lookup flags that apply to each symbol in a lookup.

///

/// If RequiredSymbol is used (the default) for a given symbol then that symbol

/// must be found during the lookup or the lookup will fail returning a

/// SymbolNotFound error. If WeaklyReferencedSymbol is used and the given

/// symbol is not found then the query will continue, and no result for the

/// missing symbol will be present in the result (assuming the rest of the

/// lookup succeeds).

enum class SymbolLookupFlags { RequiredSymbol, WeaklyReferencedSymbol };

/// Describes the kind of lookup being performed. The lookup kind is passed to

/// symbol generators (if they're invoked) to help them determine what

/// definitions to generate.

///

/// Static -- Lookup is being performed as-if at static link time (e.g.

///           generators representing static archives should pull in new

///           definitions).

///

/// DLSym -- Lookup is being performed as-if at runtime (e.g. generators

///          representing static archives should not pull in new definitions).

enum class LookupKind { Static, DLSym };

/// A list of (JITDylib*, JITDylibLookupFlags) pairs to be used as a search

/// order during symbol lookup.

using JITDylibSearchOrder =

    std::vector<std::pair<JITDylib *, JITDylibLookupFlags>>;

/// Convenience function for creating a search order from an ArrayRef of

/// JITDylib*, all with the same flags.

inline JITDylibSearchOrder makeJITDylibSearchOrder(

    ArrayRef<JITDylib *> JDs,

    JITDylibLookupFlags Flags = JITDylibLookupFlags::MatchExportedSymbolsOnly) {

  JITDylibSearchOrder O;

  O.reserve(JDs.size());

  for (auto *JD : JDs)

    O.push_back(std::make_pair(JD, Flags));

  return O;

}

/// A set of symbols to look up, each associated with a SymbolLookupFlags

/// value.

///

/// This class is backed by a vector and optimized for fast insertion,

/// deletion and iteration. It does not guarantee a stable order between

/// operations, and will not automatically detect duplicate elements (they

/// can be manually checked by calling the validate method).

class SymbolLookupSet {

public:

  using value_type = std::pair<SymbolStringPtr, SymbolLookupFlags>;

  using UnderlyingVector = std::vector<value_type>;

  using iterator = UnderlyingVector::iterator;

  using const_iterator = UnderlyingVector::const_iterator;

  SymbolLookupSet() = default;

  explicit SymbolLookupSet(

      SymbolStringPtr Name,

      SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {

    add(std::move(Name), Flags);

  }

  /// Construct a SymbolLookupSet from an initializer list of SymbolStringPtrs.

  explicit SymbolLookupSet(

      std::initializer_list<SymbolStringPtr> Names,

      SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {

    Symbols.reserve(Names.size());

    for (const auto &Name : Names)

      add(std::move(Name), Flags);

  }

  /// Construct a SymbolLookupSet from a SymbolNameSet with the given

  /// Flags used for each value.

  explicit SymbolLookupSet(

      const SymbolNameSet &Names,

      SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {

    Symbols.reserve(Names.size());

    for (const auto &Name : Names)

      add(Name, Flags);

  }

  /// Construct a SymbolLookupSet from a vector of symbols with the given Flags

  /// used for each value.

  /// If the ArrayRef contains duplicates it is up to the client to remove these

  /// before using this instance for lookup.

  explicit SymbolLookupSet(

      ArrayRef<SymbolStringPtr> Names,

      SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {

    Symbols.reserve(Names.size());

    for (const auto &Name : Names)

      add(Name, Flags);

  }

  /// Construct a SymbolLookupSet from DenseMap keys.

  template <typename KeyT>

  static SymbolLookupSet

  fromMapKeys(const DenseMap<SymbolStringPtr, KeyT> &M,

              SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {

    SymbolLookupSet Result;

    Result.Symbols.reserve(M.size());

    for (const auto &KV : M)

      Result.add(KV.first, Flags);

    return Result;

  }

  /// Add an element to the set. The client is responsible for checking that

  /// duplicates are not added.

  SymbolLookupSet &

  add(SymbolStringPtr Name,

      SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {

    Symbols.push_back(std::make_pair(std::move(Name), Flags));

    return *this;

  }

  /// Quickly append one lookup set to another.

  SymbolLookupSet &append(SymbolLookupSet Other) {

    Symbols.reserve(Symbols.size() + Other.size());

    for (auto &KV : Other)

      Symbols.push_back(std::move(KV));

    return *this;

  }

  bool empty() const { return Symbols.empty(); }

  UnderlyingVector::size_type size() const { return Symbols.size(); }

  iterator begin() { return Symbols.begin(); }

  iterator end() { return Symbols.end(); }

  const_iterator begin() const { return Symbols.begin(); }

  const_iterator end() const { return Symbols.end(); }

  /// Removes the Ith element of the vector, replacing it with the last element.

  void remove(UnderlyingVector::size_type I) {

    std::swap(Symbols[I], Symbols.back());

    Symbols.pop_back();

  }

  /// Removes the element pointed to by the given iterator. This iterator and

  /// all subsequent ones (including end()) are invalidated.

  void remove(iterator I) { remove(I - begin()); }

  /// Removes all elements matching the given predicate, which must be callable

  /// as bool(const SymbolStringPtr &, SymbolLookupFlags Flags).

  template <typename PredFn> void remove_if(PredFn &&Pred) {

    UnderlyingVector::size_type I = 0;

    while (I != Symbols.size()) {

      const auto &Name = Symbols[I].first;

      auto Flags = Symbols[I].second;

      if (Pred(Name, Flags))

        remove(I);

      else

        ++I;

    }

  }

  /// Loop over the elements of this SymbolLookupSet, applying the Body function

  /// to each one. Body must be callable as

  /// bool(const SymbolStringPtr &, SymbolLookupFlags).

  /// If Body returns true then the element just passed in is removed from the

  /// set. If Body returns false then the element is retained.

  template <typename BodyFn>

  auto forEachWithRemoval(BodyFn &&Body) -> std::enable_if_t<

      std::is_same<decltype(Body(std::declval<const SymbolStringPtr &>(),

                                 std::declval<SymbolLookupFlags>())),

                   bool>::value> {

    UnderlyingVector::size_type I = 0;

    while (I != Symbols.size()) {

      const auto &Name = Symbols[I].first;

      auto Flags = Symbols[I].second;

      if (Body(Name, Flags))

        remove(I);

      else

        ++I;

    }

  }

  /// Loop over the elements of this SymbolLookupSet, applying the Body function

  /// to each one. Body must be callable as

  /// Expected<bool>(const SymbolStringPtr &, SymbolLookupFlags).

  /// If Body returns a failure value, the loop exits immediately. If Body

  /// returns true then the element just passed in is removed from the set. If

  /// Body returns false then the element is retained.

  template <typename BodyFn>

  auto forEachWithRemoval(BodyFn &&Body) -> std::enable_if_t<

      std::is_same<decltype(Body(std::declval<const SymbolStringPtr &>(),

                                 std::declval<SymbolLookupFlags>())),

                   Expected<bool>>::value,

      Error> {

    UnderlyingVector::size_type I = 0;

    while (I != Symbols.size()) {

      const auto &Name = Symbols[I].first;

      auto Flags = Symbols[I].second;

      auto Remove = Body(Name, Flags);

      if (!Remove)

        return Remove.takeError();

      if (*Remove)

        remove(I);

      else

        ++I;

    }

    return Error::success();

  }

  /// Construct a SymbolNameVector from this instance by dropping the Flags

  /// values.

  SymbolNameVector getSymbolNames() const {

    SymbolNameVector Names;

    Names.reserve(Symbols.size());

    for (const auto &KV : Symbols)

      Names.push_back(KV.first);

    return Names;

  }

  /// Sort the lookup set by pointer value. This sort is fast but sensitive to

  /// allocation order and so should not be used where a consistent order is

  /// required.

  void sortByAddress() { llvm::sort(Symbols, llvm::less_first()); }

  /// Sort the lookup set lexicographically. This sort is slow but the order

  /// is unaffected by allocation order.

  void sortByName() {

    llvm::sort(Symbols, [](const value_type &LHS, const value_type &RHS) {

      return *LHS.first < *RHS.first;

    });

  }

  /// Remove any duplicate elements. If a SymbolLookupSet is not duplicate-free

  /// by construction, this method can be used to turn it into a proper set.

  void removeDuplicates() {

    sortByAddress();

    auto LastI = std::unique(Symbols.begin(), Symbols.end());

    Symbols.erase(LastI, Symbols.end());

  }

#ifndef NDEBUG

  /// Returns true if this set contains any duplicates. This should only be used

  /// in assertions.

  bool containsDuplicates() {

    if (Symbols.size() < 2)

      return false;

    sortByAddress();

    for (UnderlyingVector::size_type I = 1; I != Symbols.size(); ++I)

      if (Symbols[I].first == Symbols[I - 1].first)

        return true;

    return false;

  }

#endif

private:

  UnderlyingVector Symbols;

};

struct SymbolAliasMapEntry {

  SymbolAliasMapEntry() = default;

  SymbolAliasMapEntry(SymbolStringPtr Aliasee, JITSymbolFlags AliasFlags)

      : Aliasee(std::move(Aliasee)), AliasFlags(AliasFlags) {}

  SymbolStringPtr Aliasee;

  JITSymbolFlags AliasFlags;

};

/// A map of Symbols to (Symbol, Flags) pairs.

using SymbolAliasMap = DenseMap<SymbolStringPtr, SymbolAliasMapEntry>;

/// Callback to notify client that symbols have been resolved.

using SymbolsResolvedCallback = unique_function<void(Expected<SymbolMap>)>;

/// Callback to register the dependencies for a given query.

using RegisterDependenciesFunction =

    std::function<void(const SymbolDependenceMap &)>;

/// This can be used as the value for a RegisterDependenciesFunction if there

/// are no dependants to register with.

extern RegisterDependenciesFunction NoDependenciesToRegister;

class ResourceTrackerDefunct : public ErrorInfo<ResourceTrackerDefunct> {

public:

  static char ID;

  ResourceTrackerDefunct(ResourceTrackerSP RT);

  std::error_code convertToErrorCode() const override;

  void log(raw_ostream &OS) const override;

private:

  ResourceTrackerSP RT;

};

/// Used to notify a JITDylib that the given set of symbols failed to

/// materialize.

class FailedToMaterialize : public ErrorInfo<FailedToMaterialize> {

public:

  static char ID;

  FailedToMaterialize(std::shared_ptr<SymbolStringPool> SSP,

                      std::shared_ptr<SymbolDependenceMap> Symbols);

  ~FailedToMaterialize();

  std::error_code convertToErrorCode() const override;

  void log(raw_ostream &OS) const override;

  const SymbolDependenceMap &getSymbols() const { return *Symbols; }

private:

  std::shared_ptr<SymbolStringPool> SSP;

  std::shared_ptr<SymbolDependenceMap> Symbols;

};

/// Used to notify clients when symbols can not be found during a lookup.

class SymbolsNotFound : public ErrorInfo<SymbolsNotFound> {

public:

  static char ID;

  SymbolsNotFound(std::shared_ptr<SymbolStringPool> SSP, SymbolNameSet Symbols);

  SymbolsNotFound(std::shared_ptr<SymbolStringPool> SSP,

                  SymbolNameVector Symbols);

  std::error_code convertToErrorCode() const override;

  void log(raw_ostream &OS) const override;

  std::shared_ptr<SymbolStringPool> getSymbolStringPool() { return SSP; }

  const SymbolNameVector &getSymbols() const { return Symbols; }

private:

  std::shared_ptr<SymbolStringPool> SSP;

  SymbolNameVector Symbols;

};

/// Used to notify clients that a set of symbols could not be removed.

class SymbolsCouldNotBeRemoved : public ErrorInfo<SymbolsCouldNotBeRemoved> {

public:

  static char ID;

  SymbolsCouldNotBeRemoved(std::shared_ptr<SymbolStringPool> SSP,

                           SymbolNameSet Symbols);

  std::error_code convertToErrorCode() const override;

  void log(raw_ostream &OS) const override;

  std::shared_ptr<SymbolStringPool> getSymbolStringPool() { return SSP; }

  const SymbolNameSet &getSymbols() const { return Symbols; }

private:

  std::shared_ptr<SymbolStringPool> SSP;

  SymbolNameSet Symbols;

};

/// Errors of this type should be returned if a module fails to include

/// definitions that are claimed by the module's associated

/// MaterializationResponsibility. If this error is returned it is indicative of

/// a broken transformation / compiler / object cache.

class MissingSymbolDefinitions : public ErrorInfo<MissingSymbolDefinitions> {

public:

  static char ID;

  MissingSymbolDefinitions(std::shared_ptr<SymbolStringPool> SSP,

                           std::string ModuleName, SymbolNameVector Symbols)

      : SSP(std::move(SSP)), ModuleName(std::move(ModuleName)),

        Symbols(std::move(Symbols)) {}

  std::error_code convertToErrorCode() const override;

  void log(raw_ostream &OS) const override;

  std::shared_ptr<SymbolStringPool> getSymbolStringPool() { return SSP; }

  const std::string &getModuleName() const { return ModuleName; }

  const SymbolNameVector &getSymbols() const { return Symbols; }

private:

  std::shared_ptr<SymbolStringPool> SSP;

  std::string ModuleName;

  SymbolNameVector Symbols;

};

/// Errors of this type should be returned if a module contains definitions for

/// symbols that are not claimed by the module's associated

/// MaterializationResponsibility. If this error is returned it is indicative of

/// a broken transformation / compiler / object cache.

class UnexpectedSymbolDefinitions : public ErrorInfo<UnexpectedSymbolDefinitions> {

public:

  static char ID;

  UnexpectedSymbolDefinitions(std::shared_ptr<SymbolStringPool> SSP,

                              std::string ModuleName, SymbolNameVector Symbols)

      : SSP(std::move(SSP)), ModuleName(std::move(ModuleName)),

        Symbols(std::move(Symbols)) {}

  std::error_code convertToErrorCode() const override;

  void log(raw_ostream &OS) const override;

  std::shared_ptr<SymbolStringPool> getSymbolStringPool() { return SSP; }

  const std::string &getModuleName() const { return ModuleName; }

  const SymbolNameVector &getSymbols() const { return Symbols; }

private:

  std::shared_ptr<SymbolStringPool> SSP;

  std::string ModuleName;

  SymbolNameVector Symbols;

};

/// Tracks responsibility for materialization, and mediates interactions between

/// MaterializationUnits and JDs.

///

/// An instance of this class is passed to MaterializationUnits when their

/// materialize method is called. It allows MaterializationUnits to resolve and

/// emit symbols, or abandon materialization by notifying any unmaterialized

/// symbols of an error.

class MaterializationResponsibility {

  friend class ExecutionSession;

  friend class JITDylib;

public:

  MaterializationResponsibility(MaterializationResponsibility &&) = delete;

  MaterializationResponsibility &

  operator=(MaterializationResponsibility &&) = delete;

  /// Destruct a MaterializationResponsibility instance. In debug mode

  ///        this asserts that all symbols being tracked have been either

  ///        emitted or notified of an error.

  ~MaterializationResponsibility();

  /// Runs the given callback under the session lock, passing in the associated

  /// ResourceKey. This is the safe way to associate resources with trackers.

  template <typename Func> Error withResourceKeyDo(Func &&F) const {

    return RT->withResourceKeyDo(std::forward<Func>(F));

  }

  /// Returns the target JITDylib that these symbols are being materialized

  ///        into.

  JITDylib &getTargetJITDylib() const { return JD; }

  /// Returns the ExecutionSession for this instance.

  ExecutionSession &getExecutionSession() const;

  /// Returns the symbol flags map for this responsibility instance.

  /// Note: The returned flags may have transient flags (Lazy, Materializing)

  /// set. These should be stripped with JITSymbolFlags::stripTransientFlags

  /// before using.

  const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }

  /// Returns the initialization pseudo-symbol, if any. This symbol will also

  /// be present in the SymbolFlagsMap for this MaterializationResponsibility

  /// object.

  const SymbolStringPtr &getInitializerSymbol() const { return InitSymbol; }

  /// Returns the names of any symbols covered by this

  /// MaterializationResponsibility object that have queries pending. This

  /// information can be used to return responsibility for unrequested symbols

  /// back to the JITDylib via the delegate method.

  SymbolNameSet getRequestedSymbols() const;

  /// Notifies the target JITDylib that the given symbols have been resolved.

  /// This will update the given symbols' addresses in the JITDylib, and notify

  /// any pending queries on the given symbols of their resolution. The given

  /// symbols must be ones covered by this MaterializationResponsibility

  /// instance. Individual calls to this method may resolve a subset of the

  /// symbols, but all symbols must have been resolved prior to calling emit.

  ///

  /// This method will return an error if any symbols being resolved have been

  /// moved to the error state due to the failure of a dependency. If this

  /// method returns an error then clients should log it and call

  /// failMaterialize. If no dependencies have been registered for the

  /// symbols covered by this MaterializationResponsibiility then this method

  /// is guaranteed to return Error::success() and can be wrapped with cantFail.

  Error notifyResolved(const SymbolMap &Symbols);

  /// Notifies the target JITDylib (and any pending queries on that JITDylib)

  /// that all symbols covered by this MaterializationResponsibility instance

  /// have been emitted.

  ///

  /// This method will return an error if any symbols being resolved have been

  /// moved to the error state due to the failure of a dependency. If this

  /// method returns an error then clients should log it and call

  /// failMaterialize. If no dependencies have been registered for the

  /// symbols covered by this MaterializationResponsibiility then this method

  /// is guaranteed to return Error::success() and can be wrapped with cantFail.

  Error notifyEmitted();

  /// Attempt to claim responsibility for new definitions. This method can be

  /// used to claim responsibility for symbols that are added to a

  /// materialization unit during the compilation process (e.g. literal pool

  /// symbols). Symbol linkage rules are the same as for symbols that are

  /// defined up front: duplicate strong definitions will result in errors.

  /// Duplicate weak definitions will be discarded (in which case they will

  /// not be added to this responsibility instance).

  ///

  ///   This method can be used by materialization units that want to add

  /// additional symbols at materialization time (e.g. stubs, compile

  /// callbacks, metadata).

  Error defineMaterializing(SymbolFlagsMap SymbolFlags);

  /// Define the given symbols as non-existent, removing it from the symbol

  /// table and notifying any pending queries. Queries that lookup up the

  /// symbol using the SymbolLookupFlags::WeaklyReferencedSymbol flag will

  /// behave as if the symbol had not been matched in the first place. Queries

  /// that required this symbol will fail with a missing symbol definition

  /// error.

  ///

  /// This method is intended to support cleanup of special symbols like

  /// initializer symbols: Queries using

  /// SymbolLookupFlags::WeaklyReferencedSymbol can be used to trigger their

  /// emission, and this method can be used to remove them from the JITDylib

  /// once materialization is complete.

  void defineNonExistent(ArrayRef<SymbolStringPtr> Symbols);

  /// Notify all not-yet-emitted covered by this MaterializationResponsibility

  /// instance that an error has occurred.

  /// This will remove all symbols covered by this MaterializationResponsibilty

  /// from the target JITDylib, and send an error to any queries waiting on

  /// these symbols.

  void failMaterialization();

  /// Transfers responsibility to the given MaterializationUnit for all

  /// symbols defined by that MaterializationUnit. This allows

  /// materializers to break up work based on run-time information (e.g.

  /// by introspecting which symbols have actually been looked up and

  /// materializing only those).

  Error replace(std::unique_ptr<MaterializationUnit> MU);

  /// Delegates responsibility for the given symbols to the returned

  /// materialization responsibility. Useful for breaking up work between

  /// threads, or different kinds of materialization processes.

  Expected<std::unique_ptr<MaterializationResponsibility>>

  delegate(const SymbolNameSet &Symbols);

  void addDependencies(const SymbolStringPtr &Name,

                       const SymbolDependenceMap &Dependencies);

  /// Add dependencies that apply to all symbols covered by this instance.

  void addDependenciesForAll(const SymbolDependenceMap &Dependencies);

private:

  /// Create a MaterializationResponsibility for the given JITDylib and

  ///        initial symbols.

  MaterializationResponsibility(ResourceTrackerSP RT,

                                SymbolFlagsMap SymbolFlags,

                                SymbolStringPtr InitSymbol)

      : JD(RT->getJITDylib()), RT(std::move(RT)),

        SymbolFlags(std::move(SymbolFlags)), InitSymbol(std::move(InitSymbol)) {

    assert(!this->SymbolFlags.empty() && "Materializing nothing?");

  }

  JITDylib &JD;

  ResourceTrackerSP RT;

  SymbolFlagsMap SymbolFlags;

  SymbolStringPtr InitSymbol;

};

/// A MaterializationUnit represents a set of symbol definitions that can

///        be materialized as a group, or individually discarded (when

///        overriding definitions are encountered).

///

/// MaterializationUnits are used when providing lazy definitions of symbols to

/// JITDylibs. The JITDylib will call materialize when the address of a symbol

/// is requested via the lookup method. The JITDylib will call discard if a

/// stronger definition is added or already present.

class MaterializationUnit {

  friend class ExecutionSession;

  friend class JITDylib;

public:

  static char ID;

  struct Interface {

    Interface() = default;

    Interface(SymbolFlagsMap InitalSymbolFlags, SymbolStringPtr InitSymbol)

        : SymbolFlags(std::move(InitalSymbolFlags)),

          InitSymbol(std::move(InitSymbol)) {

      assert((!this->InitSymbol || this->SymbolFlags.count(this->InitSymbol)) &&

             "If set, InitSymbol should appear in InitialSymbolFlags map");

    }

    SymbolFlagsMap SymbolFlags;

    SymbolStringPtr InitSymbol;

  };

  MaterializationUnit(Interface I)

      : SymbolFlags(std::move(I.SymbolFlags)),

        InitSymbol(std::move(I.InitSymbol)) {}

  virtual ~MaterializationUnit() = default;

  /// Return the name of this materialization unit. Useful for debugging

  /// output.

  virtual StringRef getName() const = 0;

  /// Return the set of symbols that this source provides.

  const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }

  /// Returns the initialization symbol for this MaterializationUnit (if any).

  const SymbolStringPtr &getInitializerSymbol() const { return InitSymbol; }

  /// Implementations of this method should materialize all symbols

  ///        in the materialzation unit, except for those that have been

  ///        previously discarded.

  virtual void

  materialize(std::unique_ptr<MaterializationResponsibility> R) = 0;

  /// Called by JITDylibs to notify MaterializationUnits that the given symbol

  /// has been overridden.

  void doDiscard(const JITDylib &JD, const SymbolStringPtr &Name) {

    SymbolFlags.erase(Name);

    if (InitSymbol == Name) {

      DEBUG_WITH_TYPE("orc", {

        dbgs() << "In " << getName() << ": discarding init symbol \""

               << *Name << "\"\n";

      });

      InitSymbol = nullptr;

    }

    discard(JD, std::move(Name));

  }

protected:

  SymbolFlagsMap SymbolFlags;

  SymbolStringPtr InitSymbol;

private:

  virtual void anchor();

  /// Implementations of this method should discard the given symbol

  ///        from the source (e.g. if the source is an LLVM IR Module and the

  ///        symbol is a function, delete the function body or mark it available

  ///        externally).

  virtual void discard(const JITDylib &JD, const SymbolStringPtr &Name) = 0;

};

/// A MaterializationUnit implementation for pre-existing absolute symbols.

///

/// All symbols will be resolved and marked ready as soon as the unit is

/// materialized.

class AbsoluteSymbolsMaterializationUnit : public MaterializationUnit {

public:

  AbsoluteSymbolsMaterializationUnit(SymbolMap Symbols);

  StringRef getName() const override;

private:

  void materialize(std::unique_ptr<MaterializationResponsibility> R) override;

  void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;

  static MaterializationUnit::Interface extractFlags(const SymbolMap &Symbols);

  SymbolMap Symbols;

};

/// Create an AbsoluteSymbolsMaterializationUnit with the given symbols.

/// Useful for inserting absolute symbols into a JITDylib. E.g.:

/// \code{.cpp}

///   JITDylib &JD = ...;

///   SymbolStringPtr Foo = ...;

///   JITEvaluatedSymbol FooSym = ...;

///   if (auto Err = JD.define(absoluteSymbols({{Foo, FooSym}})))

///     return Err;

/// \endcode

///

inline std::unique_ptr<AbsoluteSymbolsMaterializationUnit>

absoluteSymbols(SymbolMap Symbols) {

  return std::make_unique<AbsoluteSymbolsMaterializationUnit>(

      std::move(Symbols));

}

/// A materialization unit for symbol aliases. Allows existing symbols to be

/// aliased with alternate flags.

class ReExportsMaterializationUnit : public MaterializationUnit {

public:

  /// SourceJD is allowed to be nullptr, in which case the source JITDylib is

  /// taken to be whatever JITDylib these definitions are materialized in (and

  /// MatchNonExported has no effect). This is useful for defining aliases

  /// within a JITDylib.

  ///

  /// Note: Care must be taken that no sets of aliases form a cycle, as such

  ///       a cycle will result in a deadlock when any symbol in the cycle is

  ///       resolved.

  ReExportsMaterializationUnit(JITDylib *SourceJD,

                               JITDylibLookupFlags SourceJDLookupFlags,

                               SymbolAliasMap Aliases);

  StringRef getName() const override;

private:

  void materialize(std::unique_ptr<MaterializationResponsibility> R) override;

  void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;

  static MaterializationUnit::Interface

  extractFlags(const SymbolAliasMap &Aliases);

  JITDylib *SourceJD = nullptr;

  JITDylibLookupFlags SourceJDLookupFlags;

  SymbolAliasMap Aliases;

};

/// Create a ReExportsMaterializationUnit with the given aliases.

/// Useful for defining symbol aliases.: E.g., given a JITDylib JD containing

/// symbols "foo" and "bar", we can define aliases "baz" (for "foo") and "qux"

/// (for "bar") with: \code{.cpp}