//===- ExecutorProcessControl.h - Executor process control APIs -*- 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
//
//===----------------------------------------------------------------------===//
//
// Utilities for interacting with the executor processes.
//
//===----------------------------------------------------------------------===//
#ifndef LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H
#define LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H
#include "llvm/ADT/StringRef.h"
#include "llvm/ADT/Triple.h"
#include "llvm/ExecutionEngine/JITLink/JITLinkMemoryManager.h"
#include "llvm/ExecutionEngine/Orc/Shared/ExecutorAddress.h"
#include "llvm/ExecutionEngine/Orc/Shared/TargetProcessControlTypes.h"
#include "llvm/ExecutionEngine/Orc/Shared/WrapperFunctionUtils.h"
#include "llvm/ExecutionEngine/Orc/SymbolStringPool.h"
#include "llvm/ExecutionEngine/Orc/TaskDispatch.h"
#include "llvm/Support/DynamicLibrary.h"
#include "llvm/Support/MSVCErrorWorkarounds.h"
#include <future>
#include <mutex>
#include <vector>
namespace llvm {
namespace orc {
class ExecutionSession;
class SymbolLookupSet;
/// ExecutorProcessControl supports interaction with a JIT target process.
class ExecutorProcessControl {
friend class ExecutionSession;
public:
/// A handler or incoming WrapperFunctionResults -- either return values from
/// callWrapper* calls, or incoming JIT-dispatch requests.
///
/// IncomingWFRHandlers are constructible from
/// unique_function<void(shared::WrapperFunctionResult)>s using the
/// runInPlace function or a RunWithDispatch object.
class IncomingWFRHandler {
friend class ExecutorProcessControl;
public:
IncomingWFRHandler() = default;
explicit operator bool() const { return !!H; }
void operator()(shared::WrapperFunctionResult WFR) { H(std::move(WFR)); }
private:
template <typename FnT> IncomingWFRHandler(FnT &&Fn)
: H(std::forward<FnT>(Fn)) {}
unique_function<void(shared::WrapperFunctionResult)> H;
};
/// Constructs an IncomingWFRHandler from a function object that is callable
/// as void(shared::WrapperFunctionResult). The function object will be called
/// directly. This should be used with care as it may block listener threads
/// in remote EPCs. It is only suitable for simple tasks (e.g. setting a
/// future), or for performing some quick analysis before dispatching "real"
/// work as a Task.
class RunInPlace {
public:
template <typename FnT>
IncomingWFRHandler operator()(FnT &&Fn) {
return IncomingWFRHandler(std::forward<FnT>(Fn));
}
};
/// Constructs an IncomingWFRHandler from a function object by creating a new
/// function object that dispatches the original using a TaskDispatcher,
/// wrapping the original as a GenericNamedTask.
///
/// This is the default approach for running WFR handlers.
class RunAsTask {
public:
RunAsTask(TaskDispatcher &D) : D(D) {}
template <typename FnT>
IncomingWFRHandler operator()(FnT &&Fn) {
return IncomingWFRHandler(
[&D = this->D, Fn = std::move(Fn)]
(shared::WrapperFunctionResult WFR) mutable {
D.dispatch(
makeGenericNamedTask(
[Fn = std::move(Fn), WFR = std::move(WFR)]() mutable {
Fn(std::move(WFR));
}, "WFR handler task"));
});
}
private:
TaskDispatcher &D;
};
/// APIs for manipulating memory in the target process.
class MemoryAccess {
public:
/// Callback function for asynchronous writes.
using WriteResultFn = unique_function<void(Error)>;
virtual ~MemoryAccess();
virtual void writeUInt8sAsync(ArrayRef<tpctypes::UInt8Write> Ws,
WriteResultFn OnWriteComplete) = 0;
virtual void writeUInt16sAsync(ArrayRef<tpctypes::UInt16Write> Ws,
WriteResultFn OnWriteComplete) = 0;
virtual void writeUInt32sAsync(ArrayRef<tpctypes::UInt32Write> Ws,
WriteResultFn OnWriteComplete) = 0;
virtual void writeUInt64sAsync(ArrayRef<tpctypes::UInt64Write> Ws,
WriteResultFn OnWriteComplete) = 0;
virtual void writeBuffersAsync(ArrayRef<tpctypes::BufferWrite> Ws,
WriteResultFn OnWriteComplete) = 0;
Error writeUInt8s(ArrayRef<tpctypes::UInt8Write> Ws) {
std::promise<MSVCPError> ResultP;
auto ResultF = ResultP.get_future();
writeUInt8sAsync(Ws,
[&](Error Err) { ResultP.set_value(std::move(Err)); });
return ResultF.get();
}
Error writeUInt16s(ArrayRef<tpctypes::UInt16Write> Ws) {
std::promise<MSVCPError> ResultP;
auto ResultF = ResultP.get_future();
writeUInt16sAsync(Ws,
[&](Error Err) { ResultP.set_value(std::move(Err)); });
return ResultF.get();
}
Error writeUInt32s(ArrayRef<tpctypes::UInt32Write> Ws) {
std::promise<MSVCPError> ResultP;
auto ResultF = ResultP.get_future();
writeUInt32sAsync(Ws,
[&](Error Err) { ResultP.set_value(std::move(Err)); });
return ResultF.get();
}
Error writeUInt64s(ArrayRef<tpctypes::UInt64Write> Ws) {
std::promise<MSVCPError> ResultP;
auto ResultF = ResultP.get_future();
writeUInt64sAsync(Ws,
[&](Error Err) { ResultP.set_value(std::move(Err)); });
return ResultF.get();
}
Error writeBuffers(ArrayRef<tpctypes::BufferWrite> Ws) {
std::promise<MSVCPError> ResultP;
auto ResultF = ResultP.get_future();
writeBuffersAsync(Ws,
[&](Error Err) { ResultP.set_value(std::move(Err)); });
return ResultF.get();
}
};
/// A pair of a dylib and a set of symbols to be looked up.
struct LookupRequest {
LookupRequest(tpctypes::DylibHandle Handle, const SymbolLookupSet &Symbols)
: Handle(Handle), Symbols(Symbols) {}
tpctypes::DylibHandle Handle;
const SymbolLookupSet &Symbols;
};
/// Contains the address of the dispatch function and context that the ORC
/// runtime can use to call functions in the JIT.
struct JITDispatchInfo {
ExecutorAddr JITDispatchFunction;
ExecutorAddr JITDispatchContext;
};
ExecutorProcessControl(std::shared_ptr<SymbolStringPool> SSP,
std::unique_ptr<TaskDispatcher> D)
: SSP(std::move(SSP)), D(std::move(D)) {}
virtual ~ExecutorProcessControl();
/// Return the ExecutionSession associated with this instance.
/// Not callable until the ExecutionSession has been associated.
ExecutionSession &getExecutionSession() {
assert(ES && "No ExecutionSession associated yet");
return *ES;
}
/// Intern a symbol name in the SymbolStringPool.
SymbolStringPtr intern(StringRef SymName) { return SSP->intern(SymName); }
/// Return a shared pointer to the SymbolStringPool for this instance.
std::shared_ptr<SymbolStringPool> getSymbolStringPool() const { return SSP; }
TaskDispatcher &getDispatcher() { return *D; }
/// Return the Triple for the target process.
const Triple &getTargetTriple() const { return TargetTriple; }
/// Get the page size for the target process.
unsigned getPageSize() const { return PageSize; }
/// Get the JIT dispatch function and context address for the executor.
const JITDispatchInfo &getJITDispatchInfo() const { return JDI; }
/// Return a MemoryAccess object for the target process.
MemoryAccess &getMemoryAccess() const {
assert(MemAccess && "No MemAccess object set.");
return *MemAccess;
}
/// Return a JITLinkMemoryManager for the target process.
jitlink::JITLinkMemoryManager &getMemMgr() const {
assert(MemMgr && "No MemMgr object set");
return *MemMgr;
}
/// Returns the bootstrap symbol map.
const StringMap<ExecutorAddr> &getBootstrapSymbolsMap() const {
return BootstrapSymbols;
}
/// For each (ExecutorAddr&, StringRef) pair, looks up the string in the
/// bootstrap symbols map and writes its address to the ExecutorAddr if
/// found. If any symbol is not found then the function returns an error.
Error getBootstrapSymbols(
ArrayRef<std::pair<ExecutorAddr &, StringRef>> Pairs) const {
for (const auto &KV : Pairs) {
auto I = BootstrapSymbols.find(KV.second);
if (I == BootstrapSymbols.end())
return make_error<StringError>("Symbol \"" + KV.second +
"\" not found "
"in bootstrap symbols map",
inconvertibleErrorCode());
KV.first = I->second;
}
return Error::success();
}
/// Load the dynamic library at the given path and return a handle to it.
/// If LibraryPath is null this function will return the global handle for
/// the target process.
virtual Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) = 0;
/// Search for symbols in the target process.
///
/// The result of the lookup is a 2-dimentional array of target addresses
/// that correspond to the lookup order. If a required symbol is not
/// found then this method will return an error. If a weakly referenced
/// symbol is not found then it be assigned a '0' value.
virtual Expected<std::vector<tpctypes::LookupResult>>
lookupSymbols(ArrayRef<LookupRequest> Request) = 0;
/// Run function with a main-like signature.
virtual Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr,
ArrayRef<std::string> Args) = 0;
// TODO: move this to ORC runtime.
/// Run function with a int (*)(void) signature.
virtual Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) = 0;
// TODO: move this to ORC runtime.
/// Run function with a int (*)(int) signature.
virtual Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr,
int Arg) = 0;
/// Run a wrapper function in the executor. The given WFRHandler will be
/// called on the result when it is returned.
///
/// The wrapper function should be callable as:
///
/// \code{.cpp}
/// CWrapperFunctionResult fn(uint8_t *Data, uint64_t Size);
/// \endcode{.cpp}
virtual void callWrapperAsync(ExecutorAddr WrapperFnAddr,
IncomingWFRHandler OnComplete,
ArrayRef<char> ArgBuffer) = 0;
/// Run a wrapper function in the executor using the given Runner to dispatch
/// OnComplete when the result is ready.
template <typename RunPolicyT, typename FnT>
void callWrapperAsync(RunPolicyT &&Runner, ExecutorAddr WrapperFnAddr,
FnT &&OnComplete, ArrayRef<char> ArgBuffer) {
callWrapperAsync(
WrapperFnAddr, Runner(std::forward<FnT>(OnComplete)), ArgBuffer);
}
/// Run a wrapper function in the executor. OnComplete will be dispatched
/// as a GenericNamedTask using this instance's TaskDispatch object.
template <typename FnT>
void callWrapperAsync(ExecutorAddr WrapperFnAddr, FnT &&OnComplete,
ArrayRef<char> ArgBuffer) {
callWrapperAsync(RunAsTask(*D), WrapperFnAddr,
std::forward<FnT>(OnComplete), ArgBuffer);
}
/// Run a wrapper function in the executor. The wrapper function should be
/// callable as:
///
/// \code{.cpp}
/// CWrapperFunctionResult fn(uint8_t *Data, uint64_t Size);
/// \endcode{.cpp}
shared::WrapperFunctionResult callWrapper(ExecutorAddr WrapperFnAddr,
ArrayRef<char> ArgBuffer) {
std::promise<shared::WrapperFunctionResult> RP;
auto RF = RP.get_future();
callWrapperAsync(
RunInPlace(), WrapperFnAddr,
[&](shared::WrapperFunctionResult R) {
RP.set_value(std::move(R));
}, ArgBuffer);
return RF.get();
}
/// Run a wrapper function using SPS to serialize the arguments and
/// deserialize the results.
template <typename SPSSignature, typename RunPolicyT, typename SendResultT,
typename... ArgTs>
void callSPSWrapperAsync(RunPolicyT &&Runner, ExecutorAddr WrapperFnAddr,
SendResultT &&SendResult, const ArgTs &...Args) {
shared::WrapperFunction<SPSSignature>::callAsync(
[this, WrapperFnAddr, Runner = std::move(Runner)]
(auto &&SendResult, const char *ArgData, size_t ArgSize) mutable {
this->callWrapperAsync(std::move(Runner), WrapperFnAddr,
std::move(SendResult),
ArrayRef<char>(ArgData, ArgSize));
},
std::forward<SendResultT>(SendResult), Args...);
}
/// Run a wrapper function using SPS to serialize the arguments and
/// deserialize the results.
template <typename SPSSignature, typename SendResultT, typename... ArgTs>
void callSPSWrapperAsync(ExecutorAddr WrapperFnAddr, SendResultT &&SendResult,
const ArgTs &...Args) {
callSPSWrapperAsync<SPSSignature>(RunAsTask(*D), WrapperFnAddr,
std::forward<SendResultT>(SendResult),
Args...);
}
/// Run a wrapper function using SPS to serialize the arguments and
/// deserialize the results.
///
/// If SPSSignature is a non-void function signature then the second argument
/// (the first in the Args list) should be a reference to a return value.
template <typename SPSSignature, typename... WrapperCallArgTs>
Error callSPSWrapper(ExecutorAddr WrapperFnAddr,
WrapperCallArgTs &&...WrapperCallArgs) {
return shared::WrapperFunction<SPSSignature>::call(
[this, WrapperFnAddr](const char *ArgData, size_t ArgSize) {
return callWrapper(WrapperFnAddr, ArrayRef<char>(ArgData, ArgSize));
},
std::forward<WrapperCallArgTs>(WrapperCallArgs)...);
}
/// Disconnect from the target process.
///
/// This should be called after the JIT session is shut down.
virtual Error disconnect() = 0;
protected:
std::shared_ptr<SymbolStringPool> SSP;
std::unique_ptr<TaskDispatcher> D;
ExecutionSession *ES = nullptr;
Triple TargetTriple;
unsigned PageSize = 0;
JITDispatchInfo JDI;
MemoryAccess *MemAccess = nullptr;
jitlink::JITLinkMemoryManager *MemMgr = nullptr;
StringMap<ExecutorAddr> BootstrapSymbols;
};
/// A ExecutorProcessControl instance that asserts if any of its methods are
/// used. Suitable for use is unit tests, and by ORC clients who haven't moved
/// to ExecutorProcessControl-based APIs yet.
class UnsupportedExecutorProcessControl : public ExecutorProcessControl {
public:
UnsupportedExecutorProcessControl(
std::shared_ptr<SymbolStringPool> SSP = nullptr,
std::unique_ptr<TaskDispatcher> D = nullptr,
const std::string &TT = "", unsigned PageSize = 0)
: ExecutorProcessControl(SSP ? std::move(SSP)
: std::make_shared<SymbolStringPool>(),
D ? std::move(D)
: std::make_unique<InPlaceTaskDispatcher>()) {
this->TargetTriple = Triple(TT);
this->PageSize = PageSize;
}
Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) override {
llvm_unreachable("Unsupported");
}
Expected<std::vector<tpctypes::LookupResult>>
lookupSymbols(ArrayRef<LookupRequest> Request) override {
llvm_unreachable("Unsupported");
}
Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr,
ArrayRef<std::string> Args) override {
llvm_unreachable("Unsupported");
}
Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) override {
llvm_unreachable("Unsupported");
}
Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, int Arg) override {
llvm_unreachable("Unsupported");
}
void callWrapperAsync(ExecutorAddr WrapperFnAddr,
IncomingWFRHandler OnComplete,
ArrayRef<char> ArgBuffer) override {
llvm_unreachable("Unsupported");
}
Error disconnect() override { return Error::success(); }
};
/// A ExecutorProcessControl implementation targeting the current process.
class SelfExecutorProcessControl
: public ExecutorProcessControl,
private ExecutorProcessControl::MemoryAccess {
public:
SelfExecutorProcessControl(
std::shared_ptr<SymbolStringPool> SSP, std::unique_ptr<TaskDispatcher> D,
Triple TargetTriple, unsigned PageSize,
std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr);
/// Create a SelfExecutorProcessControl with the given symbol string pool and
/// memory manager.
/// If no symbol string pool is given then one will be created.
/// If no memory manager is given a jitlink::InProcessMemoryManager will
/// be created and used by default.
static Expected<std::unique_ptr<SelfExecutorProcessControl>>
Create(std::shared_ptr<SymbolStringPool> SSP = nullptr,
std::unique_ptr<TaskDispatcher> D = nullptr,
std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr = nullptr);
Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) override;
Expected<std::vector<tpctypes::LookupResult>>
lookupSymbols(ArrayRef<LookupRequest> Request) override;
Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr,
ArrayRef<std::string> Args) override;
Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) override;
Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, int Arg) override;
void callWrapperAsync(ExecutorAddr WrapperFnAddr,
IncomingWFRHandler OnComplete,
ArrayRef<char> ArgBuffer) override;
Error disconnect() override;
private:
void writeUInt8sAsync(ArrayRef<tpctypes::UInt8Write> Ws,
WriteResultFn OnWriteComplete) override;
void writeUInt16sAsync(ArrayRef<tpctypes::UInt16Write> Ws,
WriteResultFn OnWriteComplete) override;
void writeUInt32sAsync(ArrayRef<tpctypes::UInt32Write> Ws,
WriteResultFn OnWriteComplete) override;
void writeUInt64sAsync(ArrayRef<tpctypes::UInt64Write> Ws,
WriteResultFn OnWriteComplete) override;
void writeBuffersAsync(ArrayRef<tpctypes::BufferWrite> Ws,
WriteResultFn OnWriteComplete) override;
static shared::CWrapperFunctionResult
jitDispatchViaWrapperFunctionManager(void *Ctx, const void *FnTag,
const char *Data, size_t Size);
std::unique_ptr<jitlink::JITLinkMemoryManager> OwnedMemMgr;
char GlobalManglingPrefix = 0;
};
} // end namespace orc
} // end namespace llvm
#endif // LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H