1//===------------ EPCDynamicLibrarySearchGenerator.h ------------*- 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// Support loading and searching of dynamic libraries in an executor process
10// via the ExecutorProcessControl class.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_EXECUTIONENGINE_ORC_EPCDYNAMICLIBRARYSEARCHGENERATOR_H
15#define LLVM_EXECUTIONENGINE_ORC_EPCDYNAMICLIBRARYSEARCHGENERATOR_H
16
17#include "llvm/ADT/FunctionExtras.h"
18#include "llvm/ExecutionEngine/Orc/Core.h"
19#include "llvm/Support/Compiler.h"
20
21namespace llvm {
22namespace orc {
23
24class ExecutorProcessControl;
25
26class LLVM_ABI EPCDynamicLibrarySearchGenerator : public DefinitionGenerator {
27public:
28 using SymbolPredicate = unique_function<bool(const SymbolStringPtr &)>;
29 using AddAbsoluteSymbolsFn = unique_function<Error(JITDylib &, SymbolMap)>;
30
31 /// Create an EPCDynamicLibrarySearchGenerator that searches for symbols in
32 /// the library with the given handle.
33 ///
34 /// If the Allow predicate is given then only symbols matching the predicate
35 /// will be searched for. If the predicate is not given then all symbols will
36 /// be searched for.
37 ///
38 /// If \p AddAbsoluteSymbols is provided, it is used to add the symbols to the
39 /// \c JITDylib; otherwise it uses JD.define(absoluteSymbols(...)).
40 EPCDynamicLibrarySearchGenerator(
41 ExecutionSession &ES, tpctypes::DylibHandle H,
42 SymbolPredicate Allow = SymbolPredicate(),
43 AddAbsoluteSymbolsFn AddAbsoluteSymbols = nullptr)
44 : EPC(ES.getExecutorProcessControl()), H(H), Allow(std::move(Allow)),
45 AddAbsoluteSymbols(std::move(AddAbsoluteSymbols)) {}
46
47 /// Create an EPCDynamicLibrarySearchGenerator that resolves all symbols
48 /// matching the Allow predicate to null. This can be used to emulate linker
49 /// options like -weak-l / -weak_library where the library is missing at
50 /// runtime. (Note: here we're explicitly returning null for these symbols,
51 /// rather than returning no value at all for them, which is the usual
52 /// "missing symbol" behavior in ORC. This distinction shouldn't matter for
53 /// most use-cases).
54 EPCDynamicLibrarySearchGenerator(
55 ExecutionSession &ES, SymbolPredicate Allow,
56 AddAbsoluteSymbolsFn AddAbsoluteSymbols = nullptr)
57 : EPC(ES.getExecutorProcessControl()), Allow(std::move(Allow)),
58 AddAbsoluteSymbols(std::move(AddAbsoluteSymbols)) {}
59
60 /// Permanently loads the library at the given path and, on success, returns
61 /// an EPCDynamicLibrarySearchGenerator that will search it for symbol
62 /// definitions in the library. On failure returns the reason the library
63 /// failed to load.
64 static Expected<std::unique_ptr<EPCDynamicLibrarySearchGenerator>>
65 Load(ExecutionSession &ES, const char *LibraryPath,
66 SymbolPredicate Allow = SymbolPredicate(),
67 AddAbsoluteSymbolsFn AddAbsoluteSymbols = nullptr);
68
69 /// Creates a EPCDynamicLibrarySearchGenerator that searches for symbols in
70 /// the target process.
71 static Expected<std::unique_ptr<EPCDynamicLibrarySearchGenerator>>
72 GetForTargetProcess(ExecutionSession &ES,
73 SymbolPredicate Allow = SymbolPredicate(),
74 AddAbsoluteSymbolsFn AddAbsoluteSymbols = nullptr) {
75 return Load(ES, LibraryPath: nullptr, Allow: std::move(Allow), AddAbsoluteSymbols: std::move(AddAbsoluteSymbols));
76 }
77
78 Error tryToGenerate(LookupState &LS, LookupKind K, JITDylib &JD,
79 JITDylibLookupFlags JDLookupFlags,
80 const SymbolLookupSet &Symbols) override;
81
82private:
83 Error addAbsolutes(JITDylib &JD, SymbolMap Symbols);
84
85 ExecutorProcessControl &EPC;
86 std::optional<tpctypes::DylibHandle> H;
87 SymbolPredicate Allow;
88 AddAbsoluteSymbolsFn AddAbsoluteSymbols;
89};
90
91} // end namespace orc
92} // end namespace llvm
93
94#endif // LLVM_EXECUTIONENGINE_ORC_EPCDYNAMICLIBRARYSEARCHGENERATOR_H
95