1//===------ Core.h -- Core ORC APIs (Layer, JITDylib, etc.) -----*- 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// Contains core ORC APIs.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_EXECUTIONENGINE_ORC_CORE_H
14#define LLVM_EXECUTIONENGINE_ORC_CORE_H
15
16#include "llvm/ADT/BitmaskEnum.h"
17#include "llvm/ADT/DenseSet.h"
18#include "llvm/ADT/FunctionExtras.h"
19#include "llvm/ADT/IntrusiveRefCntPtr.h"
20#include "llvm/ExecutionEngine/JITLink/JITLinkDylib.h"
21#include "llvm/ExecutionEngine/JITSymbol.h"
22#include "llvm/ExecutionEngine/Orc/SymbolStringPool.h"
23#include "llvm/ExecutionEngine/OrcV1Deprecation.h"
24#include "llvm/Support/Debug.h"
25
26#include <atomic>
27#include <memory>
28#include <vector>
29
30namespace llvm {
31namespace orc {
32
33// Forward declare some classes.
34class AsynchronousSymbolQuery;
35class ExecutionSession;
36class MaterializationUnit;
37class MaterializationResponsibility;
38class JITDylib;
39class ResourceTracker;
40class InProgressLookupState;
41
42enum class SymbolState : uint8_t;
43
44using ResourceTrackerSP = IntrusiveRefCntPtr<ResourceTracker>;
45using JITDylibSP = IntrusiveRefCntPtr<JITDylib>;
46
47using ResourceKey = uintptr_t;
48
49/// API to remove / transfer ownership of JIT resources.
50class ResourceTracker : public ThreadSafeRefCountedBase<ResourceTracker> {
51private:
52 friend class ExecutionSession;
53 friend class JITDylib;
54 friend class MaterializationResponsibility;
55
56public:
57 ResourceTracker(const ResourceTracker &) = delete;
58 ResourceTracker &operator=(const ResourceTracker &) = delete;
59 ResourceTracker(ResourceTracker &&) = delete;
60 ResourceTracker &operator=(ResourceTracker &&) = delete;
61
62 ~ResourceTracker();
63
64 /// Return the JITDylib targeted by this tracker.
65 JITDylib &getJITDylib() const {
66 return *reinterpret_cast<JITDylib *>(JDAndFlag.load() &
67 ~static_cast<uintptr_t>(1));
68 }
69
70 /// Remove all resources associated with this key.
71 Error remove();
72
73 /// Transfer all resources associated with this key to the given
74 /// tracker, which must target the same JITDylib as this one.
75 void transferTo(ResourceTracker &DstRT);
76
77 /// Return true if this tracker has become defunct.
78 bool isDefunct() const { return JDAndFlag.load() & 0x1; }
79
80 /// Returns the key associated with this tracker.
81 /// This method should not be used except for debug logging: there is no
82 /// guarantee that the returned value will remain valid.
83 ResourceKey getKeyUnsafe() const { return reinterpret_cast<uintptr_t>(this); }
84
85private:
86 ResourceTracker(JITDylibSP JD);
87
88 void makeDefunct();
89
90 std::atomic_uintptr_t JDAndFlag;
91};
92
93/// Listens for ResourceTracker operations.
94class ResourceManager {
95public:
96 virtual ~ResourceManager();
97 virtual Error handleRemoveResources(ResourceKey K) = 0;
98 virtual void handleTransferResources(ResourceKey DstK, ResourceKey SrcK) = 0;
99};
100
101/// A set of symbol names (represented by SymbolStringPtrs for
102// efficiency).
103using SymbolNameSet = DenseSet<SymbolStringPtr>;
104
105/// A vector of symbol names.
106using SymbolNameVector = std::vector<SymbolStringPtr>;
107
108/// A map from symbol names (as SymbolStringPtrs) to JITSymbols
109/// (address/flags pairs).
110using SymbolMap = DenseMap<SymbolStringPtr, JITEvaluatedSymbol>;
111
112/// A map from symbol names (as SymbolStringPtrs) to JITSymbolFlags.
113using SymbolFlagsMap = DenseMap<SymbolStringPtr, JITSymbolFlags>;
114
115/// A map from JITDylibs to sets of symbols.
116using SymbolDependenceMap = DenseMap<JITDylib *, SymbolNameSet>;
117
118/// Lookup flags that apply to each dylib in the search order for a lookup.
119///
120/// If MatchHiddenSymbolsOnly is used (the default) for a given dylib, then
121/// only symbols in that Dylib's interface will be searched. If
122/// MatchHiddenSymbols is used then symbols with hidden visibility will match
123/// as well.
124enum class JITDylibLookupFlags { MatchExportedSymbolsOnly, MatchAllSymbols };
125
126/// Lookup flags that apply to each symbol in a lookup.
127///
128/// If RequiredSymbol is used (the default) for a given symbol then that symbol
129/// must be found during the lookup or the lookup will fail returning a
130/// SymbolNotFound error. If WeaklyReferencedSymbol is used and the given
131/// symbol is not found then the query will continue, and no result for the
132/// missing symbol will be present in the result (assuming the rest of the
133/// lookup succeeds).
134enum class SymbolLookupFlags { RequiredSymbol, WeaklyReferencedSymbol };
135
136/// Describes the kind of lookup being performed. The lookup kind is passed to
137/// symbol generators (if they're invoked) to help them determine what
138/// definitions to generate.
139///
140/// Static -- Lookup is being performed as-if at static link time (e.g.
141/// generators representing static archives should pull in new
142/// definitions).
143///
144/// DLSym -- Lookup is being performed as-if at runtime (e.g. generators
145/// representing static archives should not pull in new definitions).
146enum class LookupKind { Static, DLSym };
147
148/// A list of (JITDylib*, JITDylibLookupFlags) pairs to be used as a search
149/// order during symbol lookup.
150using JITDylibSearchOrder =
151 std::vector<std::pair<JITDylib *, JITDylibLookupFlags>>;
152
153/// Convenience function for creating a search order from an ArrayRef of
154/// JITDylib*, all with the same flags.
155inline JITDylibSearchOrder makeJITDylibSearchOrder(
156 ArrayRef<JITDylib *> JDs,
157 JITDylibLookupFlags Flags = JITDylibLookupFlags::MatchExportedSymbolsOnly) {
158 JITDylibSearchOrder O;
159 O.reserve(JDs.size());
160 for (auto *JD : JDs)
161 O.push_back(std::make_pair(JD, Flags));
162 return O;
163}
164
165/// A set of symbols to look up, each associated with a SymbolLookupFlags
166/// value.
167///
168/// This class is backed by a vector and optimized for fast insertion,
169/// deletion and iteration. It does not guarantee a stable order between
170/// operations, and will not automatically detect duplicate elements (they
171/// can be manually checked by calling the validate method).
172class SymbolLookupSet {
173public:
174 using value_type = std::pair<SymbolStringPtr, SymbolLookupFlags>;
175 using UnderlyingVector = std::vector<value_type>;
176 using iterator = UnderlyingVector::iterator;
177 using const_iterator = UnderlyingVector::const_iterator;
178
179 SymbolLookupSet() = default;
180
181 explicit SymbolLookupSet(
182 SymbolStringPtr Name,
183 SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {
184 add(std::move(Name), Flags);
185 }
186
187 /// Construct a SymbolLookupSet from an initializer list of SymbolStringPtrs.
188 explicit SymbolLookupSet(
189 std::initializer_list<SymbolStringPtr> Names,
190 SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {
191 Symbols.reserve(Names.size());
192 for (auto &Name : Names)
193 add(std::move(Name), Flags);
194 }
195
196 /// Construct a SymbolLookupSet from a SymbolNameSet with the given
197 /// Flags used for each value.
198 explicit SymbolLookupSet(
199 const SymbolNameSet &Names,
200 SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {
201 Symbols.reserve(Names.size());
202 for (const auto &Name : Names)
203 add(Name, Flags);
204 }
205
206 /// Construct a SymbolLookupSet from a vector of symbols with the given Flags
207 /// used for each value.
208 /// If the ArrayRef contains duplicates it is up to the client to remove these
209 /// before using this instance for lookup.
210 explicit SymbolLookupSet(
211 ArrayRef<SymbolStringPtr> Names,
212 SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {
213 Symbols.reserve(Names.size());
214 for (const auto &Name : Names)
215 add(Name, Flags);
216 }
217
218 /// Add an element to the set. The client is responsible for checking that
219 /// duplicates are not added.
220 SymbolLookupSet &
221 add(SymbolStringPtr Name,
222 SymbolLookupFlags Flags = SymbolLookupFlags::RequiredSymbol) {
223 Symbols.push_back(std::make_pair(std::move(Name), Flags));
224 return *this;
225 }
226
227 /// Quickly append one lookup set to another.
228 SymbolLookupSet &append(SymbolLookupSet Other) {
229 Symbols.reserve(Symbols.size() + Other.size());
230 for (auto &KV : Other)
231 Symbols.push_back(std::move(KV));
232 return *this;
233 }
234
235 bool empty() const { return Symbols.empty(); }
236 UnderlyingVector::size_type size() const { return Symbols.size(); }
237 iterator begin() { return Symbols.begin(); }
238 iterator end() { return Symbols.end(); }
239 const_iterator begin() const { return Symbols.begin(); }
240 const_iterator end() const { return Symbols.end(); }
241
242 /// Removes the Ith element of the vector, replacing it with the last element.
243 void remove(UnderlyingVector::size_type I) {
244 std::swap(Symbols[I], Symbols.back());
245 Symbols.pop_back();
246 }
247
248 /// Removes the element pointed to by the given iterator. This iterator and
249 /// all subsequent ones (including end()) are invalidated.
250 void remove(iterator I) { remove(I - begin()); }
251
252 /// Removes all elements matching the given predicate, which must be callable
253 /// as bool(const SymbolStringPtr &, SymbolLookupFlags Flags).
254 template <typename PredFn> void remove_if(PredFn &&Pred) {
255 UnderlyingVector::size_type I = 0;
256 while (I != Symbols.size()) {
257 const auto &Name = Symbols[I].first;
258 auto Flags = Symbols[I].second;
259 if (Pred(Name, Flags))
260 remove(I);
261 else
262 ++I;
263 }
264 }
265
266 /// Loop over the elements of this SymbolLookupSet, applying the Body function
267 /// to each one. Body must be callable as
268 /// bool(const SymbolStringPtr &, SymbolLookupFlags).
269 /// If Body returns true then the element just passed in is removed from the
270 /// set. If Body returns false then the element is retained.
271 template <typename BodyFn>
272 auto forEachWithRemoval(BodyFn &&Body) -> std::enable_if_t<
273 std::is_same<decltype(Body(std::declval<const SymbolStringPtr &>(),
274 std::declval<SymbolLookupFlags>())),
275 bool>::value> {
276 UnderlyingVector::size_type I = 0;
277 while (I != Symbols.size()) {
278 const auto &Name = Symbols[I].first;
279 auto Flags = Symbols[I].second;
280 if (Body(Name, Flags))
281 remove(I);
282 else
283 ++I;
284 }
285 }
286
287 /// Loop over the elements of this SymbolLookupSet, applying the Body function
288 /// to each one. Body must be callable as
289 /// Expected<bool>(const SymbolStringPtr &, SymbolLookupFlags).
290 /// If Body returns a failure value, the loop exits immediately. If Body
291 /// returns true then the element just passed in is removed from the set. If
292 /// Body returns false then the element is retained.
293 template <typename BodyFn>
294 auto forEachWithRemoval(BodyFn &&Body) -> std::enable_if_t<
295 std::is_same<decltype(Body(std::declval<const SymbolStringPtr &>(),
296 std::declval<SymbolLookupFlags>())),
297 Expected<bool>>::value,
298 Error> {
299 UnderlyingVector::size_type I = 0;
300 while (I != Symbols.size()) {
301 const auto &Name = Symbols[I].first;
302 auto Flags = Symbols[I].second;
303 auto Remove = Body(Name, Flags);
304 if (!Remove)
305 return Remove.takeError();
306 if (*Remove)
307 remove(I);
308 else
309 ++I;
310 }
311 return Error::success();
312 }
313
314 /// Construct a SymbolNameVector from this instance by dropping the Flags
315 /// values.
316 SymbolNameVector getSymbolNames() const {
317 SymbolNameVector Names;
318 Names.reserve(Symbols.size());
319 for (auto &KV : Symbols)
320 Names.push_back(KV.first);
321 return Names;
322 }
323
324 /// Sort the lookup set by pointer value. This sort is fast but sensitive to
325 /// allocation order and so should not be used where a consistent order is
326 /// required.
327 void sortByAddress() {
328 llvm::sort(Symbols, [](const value_type &LHS, const value_type &RHS) {
329 return LHS.first < RHS.first;
330 });
331 }
332
333 /// Sort the lookup set lexicographically. This sort is slow but the order
334 /// is unaffected by allocation order.
335 void sortByName() {
336 llvm::sort(Symbols, [](const value_type &LHS, const value_type &RHS) {
337 return *LHS.first < *RHS.first;
338 });
339 }
340
341 /// Remove any duplicate elements. If a SymbolLookupSet is not duplicate-free
342 /// by construction, this method can be used to turn it into a proper set.
343 void removeDuplicates() {
344 sortByAddress();
345 auto LastI = std::unique(Symbols.begin(), Symbols.end());
346 Symbols.erase(LastI, Symbols.end());
347 }
348
349#ifndef NDEBUG
350 /// Returns true if this set contains any duplicates. This should only be used
351 /// in assertions.
352 bool containsDuplicates() {
353 if (Symbols.size() < 2)
354 return false;
355 sortByAddress();
356 for (UnderlyingVector::size_type I = 1; I != Symbols.size(); ++I)
357 if (Symbols[I].first == Symbols[I - 1].first)
358 return true;
359 return false;
360 }
361#endif
362
363private:
364 UnderlyingVector Symbols;
365};
366
367struct SymbolAliasMapEntry {
368 SymbolAliasMapEntry() = default;
369 SymbolAliasMapEntry(SymbolStringPtr Aliasee, JITSymbolFlags AliasFlags)
370 : Aliasee(std::move(Aliasee)), AliasFlags(AliasFlags) {}
371
372 SymbolStringPtr Aliasee;
373 JITSymbolFlags AliasFlags;
374};
375
376/// A map of Symbols to (Symbol, Flags) pairs.
377using SymbolAliasMap = DenseMap<SymbolStringPtr, SymbolAliasMapEntry>;
378
379/// Callback to notify client that symbols have been resolved.
380using SymbolsResolvedCallback = unique_function<void(Expected<SymbolMap>)>;
381
382/// Callback to register the dependencies for a given query.
383using RegisterDependenciesFunction =
384 std::function<void(const SymbolDependenceMap &)>;
385
386/// This can be used as the value for a RegisterDependenciesFunction if there
387/// are no dependants to register with.
388extern RegisterDependenciesFunction NoDependenciesToRegister;
389
390class ResourceTrackerDefunct : public ErrorInfo<ResourceTrackerDefunct> {
391public:
392 static char ID;
393
394 ResourceTrackerDefunct(ResourceTrackerSP RT);
395 std::error_code convertToErrorCode() const override;
396 void log(raw_ostream &OS) const override;
397
398private:
399 ResourceTrackerSP RT;
400};
401
402/// Used to notify a JITDylib that the given set of symbols failed to
403/// materialize.
404class FailedToMaterialize : public ErrorInfo<FailedToMaterialize> {
405public:
406 static char ID;
407
408 FailedToMaterialize(std::shared_ptr<SymbolDependenceMap> Symbols);
409 std::error_code convertToErrorCode() const override;
410 void log(raw_ostream &OS) const override;
411 const SymbolDependenceMap &getSymbols() const { return *Symbols; }
412
413private:
414 std::shared_ptr<SymbolDependenceMap> Symbols;
415};
416
417/// Used to notify clients when symbols can not be found during a lookup.
418class SymbolsNotFound : public ErrorInfo<SymbolsNotFound> {
419public:
420 static char ID;
421
422 SymbolsNotFound(SymbolNameSet Symbols);
423 SymbolsNotFound(SymbolNameVector Symbols);
424 std::error_code convertToErrorCode() const override;
425 void log(raw_ostream &OS) const override;
426 const SymbolNameVector &getSymbols() const { return Symbols; }
427
428private:
429 SymbolNameVector Symbols;
430};
431
432/// Used to notify clients that a set of symbols could not be removed.
433class SymbolsCouldNotBeRemoved : public ErrorInfo<SymbolsCouldNotBeRemoved> {
434public:
435 static char ID;
436
437 SymbolsCouldNotBeRemoved(SymbolNameSet Symbols);
438 std::error_code convertToErrorCode() const override;
439 void log(raw_ostream &OS) const override;
440 const SymbolNameSet &getSymbols() const { return Symbols; }
441
442private:
443 SymbolNameSet Symbols;
444};
445
446/// Errors of this type should be returned if a module fails to include
447/// definitions that are claimed by the module's associated
448/// MaterializationResponsibility. If this error is returned it is indicative of
449/// a broken transformation / compiler / object cache.
450class MissingSymbolDefinitions : public ErrorInfo<MissingSymbolDefinitions> {
451public:
452 static char ID;
453
454 MissingSymbolDefinitions(std::string ModuleName, SymbolNameVector Symbols)
455 : ModuleName(std::move(ModuleName)), Symbols(std::move(Symbols)) {}
456 std::error_code convertToErrorCode() const override;
457 void log(raw_ostream &OS) const override;
458 const std::string &getModuleName() const { return ModuleName; }
459 const SymbolNameVector &getSymbols() const { return Symbols; }
460private:
461 std::string ModuleName;
462 SymbolNameVector Symbols;
463};
464
465/// Errors of this type should be returned if a module contains definitions for
466/// symbols that are not claimed by the module's associated
467/// MaterializationResponsibility. If this error is returned it is indicative of
468/// a broken transformation / compiler / object cache.
469class UnexpectedSymbolDefinitions : public ErrorInfo<UnexpectedSymbolDefinitions> {
470public:
471 static char ID;
472
473 UnexpectedSymbolDefinitions(std::string ModuleName, SymbolNameVector Symbols)
474 : ModuleName(std::move(ModuleName)), Symbols(std::move(Symbols)) {}
475 std::error_code convertToErrorCode() const override;
476 void log(raw_ostream &OS) const override;
477 const std::string &getModuleName() const { return ModuleName; }
478 const SymbolNameVector &getSymbols() const { return Symbols; }
479private:
480 std::string ModuleName;
481 SymbolNameVector Symbols;
482};
483
484/// Tracks responsibility for materialization, and mediates interactions between
485/// MaterializationUnits and JDs.
486///
487/// An instance of this class is passed to MaterializationUnits when their
488/// materialize method is called. It allows MaterializationUnits to resolve and
489/// emit symbols, or abandon materialization by notifying any unmaterialized
490/// symbols of an error.
491class MaterializationResponsibility {
492 friend class ExecutionSession;
493
494public:
495 MaterializationResponsibility(MaterializationResponsibility &&) = delete;
496 MaterializationResponsibility &
497 operator=(MaterializationResponsibility &&) = delete;
498
499 /// Destruct a MaterializationResponsibility instance. In debug mode
500 /// this asserts that all symbols being tracked have been either
501 /// emitted or notified of an error.
502 ~MaterializationResponsibility();
503
504 /// Returns the ResourceTracker for this instance.
505 template <typename Func> Error withResourceKeyDo(Func &&F) const;
506
507 /// Returns the target JITDylib that these symbols are being materialized
508 /// into.
509 JITDylib &getTargetJITDylib() const { return *JD; }
510
511 /// Returns the ExecutionSession for this instance.
512 ExecutionSession &getExecutionSession();
513
514 /// Returns the symbol flags map for this responsibility instance.
515 /// Note: The returned flags may have transient flags (Lazy, Materializing)
516 /// set. These should be stripped with JITSymbolFlags::stripTransientFlags
517 /// before using.
518 const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }
519
520 /// Returns the initialization pseudo-symbol, if any. This symbol will also
521 /// be present in the SymbolFlagsMap for this MaterializationResponsibility
522 /// object.
523 const SymbolStringPtr &getInitializerSymbol() const { return InitSymbol; }
524
525 /// Returns the names of any symbols covered by this
526 /// MaterializationResponsibility object that have queries pending. This
527 /// information can be used to return responsibility for unrequested symbols
528 /// back to the JITDylib via the delegate method.
529 SymbolNameSet getRequestedSymbols() const;
530
531 /// Notifies the target JITDylib that the given symbols have been resolved.
532 /// This will update the given symbols' addresses in the JITDylib, and notify
533 /// any pending queries on the given symbols of their resolution. The given
534 /// symbols must be ones covered by this MaterializationResponsibility
535 /// instance. Individual calls to this method may resolve a subset of the
536 /// symbols, but all symbols must have been resolved prior to calling emit.
537 ///
538 /// This method will return an error if any symbols being resolved have been
539 /// moved to the error state due to the failure of a dependency. If this
540 /// method returns an error then clients should log it and call
541 /// failMaterialize. If no dependencies have been registered for the
542 /// symbols covered by this MaterializationResponsibiility then this method
543 /// is guaranteed to return Error::success() and can be wrapped with cantFail.
544 Error notifyResolved(const SymbolMap &Symbols);
545
546 /// Notifies the target JITDylib (and any pending queries on that JITDylib)
547 /// that all symbols covered by this MaterializationResponsibility instance
548 /// have been emitted.
549 ///
550 /// This method will return an error if any symbols being resolved have been
551 /// moved to the error state due to the failure of a dependency. If this
552 /// method returns an error then clients should log it and call
553 /// failMaterialize. If no dependencies have been registered for the
554 /// symbols covered by this MaterializationResponsibiility then this method
555 /// is guaranteed to return Error::success() and can be wrapped with cantFail.
556 Error notifyEmitted();
557
558 /// Attempt to claim responsibility for new definitions. This method can be
559 /// used to claim responsibility for symbols that are added to a
560 /// materialization unit during the compilation process (e.g. literal pool
561 /// symbols). Symbol linkage rules are the same as for symbols that are
562 /// defined up front: duplicate strong definitions will result in errors.
563 /// Duplicate weak definitions will be discarded (in which case they will
564 /// not be added to this responsibility instance).
565 ///
566 /// This method can be used by materialization units that want to add
567 /// additional symbols at materialization time (e.g. stubs, compile
568 /// callbacks, metadata).
569 Error defineMaterializing(SymbolFlagsMap SymbolFlags);
570
571 /// Define the given symbols as non-existent, removing it from the symbol
572 /// table and notifying any pending queries. Queries that lookup up the
573 /// symbol using the SymbolLookupFlags::WeaklyReferencedSymbol flag will
574 /// behave as if the symbol had not been matched in the first place. Queries
575 /// that required this symbol will fail with a missing symbol definition
576 /// error.
577 ///
578 /// This method is intended to support cleanup of special symbols like
579 /// initializer symbols: Queries using
580 /// SymbolLookupFlags::WeaklyReferencedSymbol can be used to trigger their
581 /// emission, and this method can be used to remove them from the JITDylib
582 /// once materialization is complete.
583 void defineNonExistent(ArrayRef<SymbolStringPtr> Symbols);
584
585 /// Notify all not-yet-emitted covered by this MaterializationResponsibility
586 /// instance that an error has occurred.
587 /// This will remove all symbols covered by this MaterializationResponsibilty
588 /// from the target JITDylib, and send an error to any queries waiting on
589 /// these symbols.
590 void failMaterialization();
591
592 /// Transfers responsibility to the given MaterializationUnit for all
593 /// symbols defined by that MaterializationUnit. This allows
594 /// materializers to break up work based on run-time information (e.g.
595 /// by introspecting which symbols have actually been looked up and
596 /// materializing only those).
597 Error replace(std::unique_ptr<MaterializationUnit> MU);
598
599 /// Delegates responsibility for the given symbols to the returned
600 /// materialization responsibility. Useful for breaking up work between
601 /// threads, or different kinds of materialization processes.
602 Expected<std::unique_ptr<MaterializationResponsibility>>
603 delegate(const SymbolNameSet &Symbols);
604
605 void addDependencies(const SymbolStringPtr &Name,
606 const SymbolDependenceMap &Dependencies);
607
608 /// Add dependencies that apply to all symbols covered by this instance.
609 void addDependenciesForAll(const SymbolDependenceMap &Dependencies);
610
611private:
612 /// Create a MaterializationResponsibility for the given JITDylib and
613 /// initial symbols.
614 MaterializationResponsibility(JITDylibSP JD, SymbolFlagsMap SymbolFlags,
615 SymbolStringPtr InitSymbol)
616 : JD(std::move(JD)), SymbolFlags(std::move(SymbolFlags)),
617 InitSymbol(std::move(InitSymbol)) {
618 assert(this->JD && "Cannot initialize with null JITDylib");
619 assert(!this->SymbolFlags.empty() && "Materializing nothing?");
620 }
621
622 JITDylibSP JD;
623 SymbolFlagsMap SymbolFlags;
624 SymbolStringPtr InitSymbol;
625};
626
627/// A MaterializationUnit represents a set of symbol definitions that can
628/// be materialized as a group, or individually discarded (when
629/// overriding definitions are encountered).
630///
631/// MaterializationUnits are used when providing lazy definitions of symbols to
632/// JITDylibs. The JITDylib will call materialize when the address of a symbol
633/// is requested via the lookup method. The JITDylib will call discard if a
634/// stronger definition is added or already present.
635class MaterializationUnit {
636 friend class ExecutionSession;
637 friend class JITDylib;
638
639public:
640 MaterializationUnit(SymbolFlagsMap InitalSymbolFlags,
641 SymbolStringPtr InitSymbol)
642 : SymbolFlags(std::move(InitalSymbolFlags)),
643 InitSymbol(std::move(InitSymbol)) {
644 assert((!this->InitSymbol || this->SymbolFlags.count(this->InitSymbol)) &&
645 "If set, InitSymbol should appear in InitialSymbolFlags map");
646 }
647
648 virtual ~MaterializationUnit() {}
649
650 /// Return the name of this materialization unit. Useful for debugging
651 /// output.
652 virtual StringRef getName() const = 0;
653
654 /// Return the set of symbols that this source provides.
655 const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }
656
657 /// Returns the initialization symbol for this MaterializationUnit (if any).
658 const SymbolStringPtr &getInitializerSymbol() const { return InitSymbol; }
659
660 /// Implementations of this method should materialize all symbols
661 /// in the materialzation unit, except for those that have been
662 /// previously discarded.
663 virtual void
664 materialize(std::unique_ptr<MaterializationResponsibility> R) = 0;
665
666 /// Called by JITDylibs to notify MaterializationUnits that the given symbol
667 /// has been overridden.
668 void doDiscard(const JITDylib &JD, const SymbolStringPtr &Name) {
669 SymbolFlags.erase(Name);
670 discard(JD, std::move(Name));
671 }
672
673protected:
674 SymbolFlagsMap SymbolFlags;
675 SymbolStringPtr InitSymbol;
676
677private:
678 virtual void anchor();
679
680 /// Implementations of this method should discard the given symbol
681 /// from the source (e.g. if the source is an LLVM IR Module and the
682 /// symbol is a function, delete the function body or mark it available
683 /// externally).
684 virtual void discard(const JITDylib &JD, const SymbolStringPtr &Name) = 0;
685};
686
687/// A MaterializationUnit implementation for pre-existing absolute symbols.
688///
689/// All symbols will be resolved and marked ready as soon as the unit is
690/// materialized.
691class AbsoluteSymbolsMaterializationUnit : public MaterializationUnit {
692public:
693 AbsoluteSymbolsMaterializationUnit(SymbolMap Symbols);
694
695 StringRef getName() const override;
696
697private:
698 void materialize(std::unique_ptr<MaterializationResponsibility> R) override;
699 void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;
700 static SymbolFlagsMap extractFlags(const SymbolMap &Symbols);
701
702 SymbolMap Symbols;
703};
704
705/// Create an AbsoluteSymbolsMaterializationUnit with the given symbols.
706/// Useful for inserting absolute symbols into a JITDylib. E.g.:
707/// \code{.cpp}
708/// JITDylib &JD = ...;
709/// SymbolStringPtr Foo = ...;
710/// JITEvaluatedSymbol FooSym = ...;
711/// if (auto Err = JD.define(absoluteSymbols({{Foo, FooSym}})))
712/// return Err;
713/// \endcode
714///
715inline std::unique_ptr<AbsoluteSymbolsMaterializationUnit>
716absoluteSymbols(SymbolMap Symbols) {
717 return std::make_unique<AbsoluteSymbolsMaterializationUnit>(
718 std::move(Symbols));
719}
720
721/// A materialization unit for symbol aliases. Allows existing symbols to be
722/// aliased with alternate flags.
723class ReExportsMaterializationUnit : public MaterializationUnit {
724public:
725 /// SourceJD is allowed to be nullptr, in which case the source JITDylib is
726 /// taken to be whatever JITDylib these definitions are materialized in (and
727 /// MatchNonExported has no effect). This is useful for defining aliases
728 /// within a JITDylib.
729 ///
730 /// Note: Care must be taken that no sets of aliases form a cycle, as such
731 /// a cycle will result in a deadlock when any symbol in the cycle is
732 /// resolved.
733 ReExportsMaterializationUnit(JITDylib *SourceJD,
734 JITDylibLookupFlags SourceJDLookupFlags,
735 SymbolAliasMap Aliases);
736
737 StringRef getName() const override;
738
739private:
740 void materialize(std::unique_ptr<MaterializationResponsibility> R) override;
741 void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;
742 static SymbolFlagsMap extractFlags(const SymbolAliasMap &Aliases);
743
744 JITDylib *SourceJD = nullptr;
745 JITDylibLookupFlags SourceJDLookupFlags;
746 SymbolAliasMap Aliases;
747};
748
749/// Create a ReExportsMaterializationUnit with the given aliases.
750/// Useful for defining symbol aliases.: E.g., given a JITDylib JD containing
751/// symbols "foo" and "bar", we can define aliases "baz" (for "foo") and "qux"
752/// (for "bar") with: \code{.cpp}
753/// SymbolStringPtr Baz = ...;
754/// SymbolStringPtr Qux = ...;
755/// if (auto Err = JD.define(symbolAliases({
756/// {Baz, { Foo, JITSymbolFlags::Exported }},
757/// {Qux, { Bar, JITSymbolFlags::Weak }}}))
758/// return Err;
759/// \endcode
760inline std::unique_ptr<ReExportsMaterializationUnit>
761symbolAliases(SymbolAliasMap Aliases) {
762 return std::make_unique<ReExportsMaterializationUnit>(
763 nullptr, JITDylibLookupFlags::MatchAllSymbols, std::move(Aliases));
764}
765
766/// Create a materialization unit for re-exporting symbols from another JITDylib
767/// with alternative names/flags.
768/// SourceJD will be searched using the given JITDylibLookupFlags.
769inline std::unique_ptr<ReExportsMaterializationUnit>
770reexports(JITDylib &SourceJD, SymbolAliasMap Aliases,
771 JITDylibLookupFlags SourceJDLookupFlags =
772 JITDylibLookupFlags::MatchExportedSymbolsOnly) {
773 return std::make_unique<ReExportsMaterializationUnit>(
774 &SourceJD, SourceJDLookupFlags, std::move(Aliases));
775}
776
777/// Build a SymbolAliasMap for the common case where you want to re-export
778/// symbols from another JITDylib with the same linkage/flags.
779Expected<SymbolAliasMap>
780buildSimpleReexportsAAliasMap(JITDylib &SourceJD, const SymbolNameSet &Symbols);
781
782/// Represents the state that a symbol has reached during materialization.
783enum class SymbolState : uint8_t {
784 Invalid, /// No symbol should be in this state.
785 NeverSearched, /// Added to the symbol table, never queried.
786 Materializing, /// Queried, materialization begun.
787 Resolved, /// Assigned address, still materializing.
788 Emitted, /// Emitted to memory, but waiting on transitive dependencies.
789 Ready = 0x3f /// Ready and safe for clients to access.
790};
791
792/// A symbol query that returns results via a callback when results are
793/// ready.
794///
795/// makes a callback when all symbols are available.
796class AsynchronousSymbolQuery {
797 friend class ExecutionSession;
798 friend class InProgressFullLookupState;
799 friend class JITDylib;
800 friend class JITSymbolResolverAdapter;
801 friend class MaterializationResponsibility;
802
803public:
804 /// Create a query for the given symbols. The NotifyComplete
805 /// callback will be called once all queried symbols reach the given
806 /// minimum state.
807 AsynchronousSymbolQuery(const SymbolLookupSet &Symbols,
808 SymbolState RequiredState,
809 SymbolsResolvedCallback NotifyComplete);
810
811 /// Notify the query that a requested symbol has reached the required state.
812 void notifySymbolMetRequiredState(const SymbolStringPtr &Name,
813 JITEvaluatedSymbol Sym);
814
815 /// Returns true if all symbols covered by this query have been
816 /// resolved.
817 bool isComplete() const { return OutstandingSymbolsCount == 0; }
818
819 /// Call the NotifyComplete callback.
820 ///
821 /// This should only be called if all symbols covered by the query have
822 /// reached the specified state.
823 void handleComplete();
824
825private:
826 SymbolState getRequiredState() { return RequiredState; }
827
828 void addQueryDependence(JITDylib &JD, SymbolStringPtr Name);
829
830 void removeQueryDependence(JITDylib &JD, const SymbolStringPtr &Name);
831
832 void dropSymbol(const SymbolStringPtr &Name);
833
834 void handleFailed(Error Err);
835
836 void detach();
837
838 SymbolsResolvedCallback NotifyComplete;
839 SymbolDependenceMap QueryRegistrations;
840 SymbolMap ResolvedSymbols;
841 size_t OutstandingSymbolsCount;
842 SymbolState RequiredState;
843};
844
845/// Wraps state for a lookup-in-progress.
846/// DefinitionGenerators can optionally take ownership of a LookupState object
847/// to suspend a lookup-in-progress while they search for definitions.
848class LookupState {
849 friend class OrcV2CAPIHelper;
850 friend class ExecutionSession;
851
852public:
853 LookupState();
854 LookupState(LookupState &&);
855 LookupState &operator=(LookupState &&);
856 ~LookupState();
857
858 /// Continue the lookup. This can be called by DefinitionGenerators
859 /// to re-start a captured query-application operation.
860 void continueLookup(Error Err);
861
862private:
863 LookupState(std::unique_ptr<InProgressLookupState> IPLS);
864
865 // For C API.
866 void reset(InProgressLookupState *IPLS);
867
868 std::unique_ptr<InProgressLookupState> IPLS;
869};
870
871/// Definition generators can be attached to JITDylibs to generate new
872/// definitions for otherwise unresolved symbols during lookup.
873class DefinitionGenerator {
874public:
875 virtual ~DefinitionGenerator();
876
877 /// DefinitionGenerators should override this method to insert new
878 /// definitions into the parent JITDylib. K specifies the kind of this
879 /// lookup. JD specifies the target JITDylib being searched, and
880 /// JDLookupFlags specifies whether the search should match against
881 /// hidden symbols. Finally, Symbols describes the set of unresolved
882 /// symbols and their associated lookup flags.
883 virtual Error tryToGenerate(LookupState &LS, LookupKind K, JITDylib &JD,
884 JITDylibLookupFlags JDLookupFlags,
885 const SymbolLookupSet &LookupSet) = 0;
886};
887
888/// A symbol table that supports asynchoronous symbol queries.
889///
890/// Represents a virtual shared object. Instances can not be copied or moved, so
891/// their addresses may be used as keys for resource management.
892/// JITDylib state changes must be made via an ExecutionSession to guarantee
893/// that they are synchronized with respect to other JITDylib operations.
894class JITDylib : public ThreadSafeRefCountedBase<JITDylib>,
895 public jitlink::JITLinkDylib {
896 friend class AsynchronousSymbolQuery;
897 friend class ExecutionSession;
898 friend class Platform;
899 friend class MaterializationResponsibility;
900public:
901
902 using AsynchronousSymbolQuerySet =
903 std::set<std::shared_ptr<AsynchronousSymbolQuery>>;
904
905 JITDylib(const JITDylib &) = delete;
906 JITDylib &operator=(const JITDylib &) = delete;
907 JITDylib(JITDylib &&) = delete;
908 JITDylib &operator=(JITDylib &&) = delete;
909
910 /// Get the name for this JITDylib.
911 const std::string &getName() const { return JITDylibName; }
912
913 /// Get a reference to the ExecutionSession for this JITDylib.
914 ExecutionSession &getExecutionSession() const { return ES; }
915
916 /// Calls remove on all trackers currently associated with this JITDylib.
917 /// Does not run static deinits.
918 ///
919 /// Note that removal happens outside the session lock, so new code may be
920 /// added concurrently while the clear is underway, and the newly added
921 /// code will *not* be cleared. Adding new code concurrently with a clear
922 /// is usually a bug and should be avoided.
923 Error clear();
924
925 /// Get the default resource tracker for this JITDylib.
926 ResourceTrackerSP getDefaultResourceTracker();
927
928 /// Create a resource tracker for this JITDylib.
929 ResourceTrackerSP createResourceTracker();
930
931 /// Adds a definition generator to this JITDylib and returns a referenece to
932 /// it.
933 ///
934 /// When JITDylibs are searched during lookup, if no existing definition of
935 /// a symbol is found, then any generators that have been added are run (in
936 /// the order that they were added) to potentially generate a definition.
937 template <typename GeneratorT>
938 GeneratorT &addGenerator(std::unique_ptr<GeneratorT> DefGenerator);
939
940 /// Remove a definition generator from this JITDylib.
941 ///
942 /// The given generator must exist in this JITDylib's generators list (i.e.
943 /// have been added and not yet removed).
944 void removeGenerator(DefinitionGenerator &G);
945
946 /// Set the link order to be used when fixing up definitions in JITDylib.
947 /// This will replace the previous link order, and apply to any symbol
948 /// resolutions made for definitions in this JITDylib after the call to
949 /// setLinkOrder (even if the definition itself was added before the
950 /// call).
951 ///
952 /// If LinkAgainstThisJITDylibFirst is true (the default) then this JITDylib
953 /// will add itself to the beginning of the LinkOrder (Clients should not
954 /// put this JITDylib in the list in this case, to avoid redundant lookups).
955 ///
956 /// If LinkAgainstThisJITDylibFirst is false then the link order will be used
957 /// as-is. The primary motivation for this feature is to support deliberate
958 /// shadowing of symbols in this JITDylib by a facade JITDylib. For example,
959 /// the facade may resolve function names to stubs, and the stubs may compile
960 /// lazily by looking up symbols in this dylib. Adding the facade dylib
961 /// as the first in the link order (instead of this dylib) ensures that
962 /// definitions within this dylib resolve to the lazy-compiling stubs,
963 /// rather than immediately materializing the definitions in this dylib.
964 void setLinkOrder(JITDylibSearchOrder NewSearchOrder,
965 bool LinkAgainstThisJITDylibFirst = true);
966
967 /// Add the given JITDylib to the link order for definitions in this
968 /// JITDylib.
969 void addToLinkOrder(JITDylib &JD,
970 JITDylibLookupFlags JDLookupFlags =
971 JITDylibLookupFlags::MatchExportedSymbolsOnly);
972
973 /// Replace OldJD with NewJD in the link order if OldJD is present.
974 /// Otherwise this operation is a no-op.
975 void replaceInLinkOrder(JITDylib &OldJD, JITDylib &NewJD,
976 JITDylibLookupFlags JDLookupFlags =
977 JITDylibLookupFlags::MatchExportedSymbolsOnly);
978
979 /// Remove the given JITDylib from the link order for this JITDylib if it is
980 /// present. Otherwise this operation is a no-op.
981 void removeFromLinkOrder(JITDylib &JD);
982
983 /// Do something with the link order (run under the session lock).
984 template <typename Func>
985 auto withLinkOrderDo(Func &&F)
986 -> decltype(F(std::declval<const JITDylibSearchOrder &>()));
987
988 /// Define all symbols provided by the materialization unit to be part of this
989 /// JITDylib.
990 ///
991 /// If RT is not specified then the default resource tracker will be used.
992 ///
993 /// This overload always takes ownership of the MaterializationUnit. If any
994 /// errors occur, the MaterializationUnit consumed.
995 template <typename MaterializationUnitType>
996 Error define(std::unique_ptr<MaterializationUnitType> &&MU,
997 ResourceTrackerSP RT = nullptr);
998
999 /// Define all symbols provided by the materialization unit to be part of this
1000 /// JITDylib.
1001 ///
1002 /// This overload only takes ownership of the MaterializationUnit no error is
1003 /// generated. If an error occurs, ownership remains with the caller. This
1004 /// may allow the caller to modify the MaterializationUnit to correct the
1005 /// issue, then re-call define.
1006 template <typename MaterializationUnitType>
1007 Error define(std::unique_ptr<MaterializationUnitType> &MU,
1008 ResourceTrackerSP RT = nullptr);
1009
1010 /// Tries to remove the given symbols.
1011 ///
1012 /// If any symbols are not defined in this JITDylib this method will return
1013 /// a SymbolsNotFound error covering the missing symbols.
1014 ///
1015 /// If all symbols are found but some symbols are in the process of being
1016 /// materialized this method will return a SymbolsCouldNotBeRemoved error.
1017 ///
1018 /// On success, all symbols are removed. On failure, the JITDylib state is
1019 /// left unmodified (no symbols are removed).
1020 Error remove(const SymbolNameSet &Names);
1021
1022 /// Dump current JITDylib state to OS.
1023 void dump(raw_ostream &OS);
1024
1025 /// Returns the given JITDylibs and all of their transitive dependencies in
1026 /// DFS order (based on linkage relationships). Each JITDylib will appear
1027 /// only once.
1028 static std::vector<JITDylibSP> getDFSLinkOrder(ArrayRef<JITDylibSP> JDs);
1029
1030 /// Returns the given JITDylibs and all of their transitive dependensies in
1031 /// reverse DFS order (based on linkage relationships). Each JITDylib will
1032 /// appear only once.
1033 static std::vector<JITDylibSP>
1034 getReverseDFSLinkOrder(ArrayRef<JITDylibSP> JDs);
1035
1036 /// Return this JITDylib and its transitive dependencies in DFS order
1037 /// based on linkage relationships.
1038 std::vector<JITDylibSP> getDFSLinkOrder();
1039
1040 /// Rteurn this JITDylib and its transitive dependencies in reverse DFS order
1041 /// based on linkage relationships.
1042 std::vector<JITDylibSP> getReverseDFSLinkOrder();
1043
1044private:
1045 using AsynchronousSymbolQueryList =
1046 std::vector<std::shared_ptr<AsynchronousSymbolQuery>>;
1047
1048 struct UnmaterializedInfo {
1049 UnmaterializedInfo(std::unique_ptr<MaterializationUnit> MU,
1050 ResourceTracker *RT)
1051 : MU(std::move(MU)), RT(RT) {}
1052
1053 std::unique_ptr<MaterializationUnit> MU;
1054 ResourceTracker *RT;
1055 };
1056
1057 using UnmaterializedInfosMap =
1058 DenseMap<SymbolStringPtr, std::shared_ptr<UnmaterializedInfo>>;
1059
1060 using UnmaterializedInfosList =
1061 std::vector<std::shared_ptr<UnmaterializedInfo>>;
1062
1063 struct MaterializingInfo {
1064 SymbolDependenceMap Dependants;
1065 SymbolDependenceMap UnemittedDependencies;
1066
1067 void addQuery(std::shared_ptr<AsynchronousSymbolQuery> Q);
1068 void removeQuery(const AsynchronousSymbolQuery &Q);
1069 AsynchronousSymbolQueryList takeQueriesMeeting(SymbolState RequiredState);
1070 AsynchronousSymbolQueryList takeAllPendingQueries() {
1071 return std::move(PendingQueries);
1072 }
1073 bool hasQueriesPending() const { return !PendingQueries.empty(); }
1074 const AsynchronousSymbolQueryList &pendingQueries() const {
1075 return PendingQueries;
1076 }
1077 private:
1078 AsynchronousSymbolQueryList PendingQueries;
1079 };
1080
1081 using MaterializingInfosMap = DenseMap<SymbolStringPtr, MaterializingInfo>;
1082
1083 class SymbolTableEntry {
1084 public:
1085 SymbolTableEntry() = default;
1086 SymbolTableEntry(JITSymbolFlags Flags)
1087 : Flags(Flags), State(static_cast<uint8_t>(SymbolState::NeverSearched)),
1088 MaterializerAttached(false), PendingRemoval(false) {}
1089
1090 JITTargetAddress getAddress() const { return Addr; }
1091 JITSymbolFlags getFlags() const { return Flags; }
1092 SymbolState getState() const { return static_cast<SymbolState>(State); }
1093
1094 bool hasMaterializerAttached() const { return MaterializerAttached; }
1095 bool isPendingRemoval() const { return PendingRemoval; }
1096
1097 void setAddress(JITTargetAddress Addr) { this->Addr = Addr; }
1098 void setFlags(JITSymbolFlags Flags) { this->Flags = Flags; }
1099 void setState(SymbolState State) {
1100 assert(static_cast<uint8_t>(State) < (1 << 6) &&
1101 "State does not fit in bitfield");
1102 this->State = static_cast<uint8_t>(State);
1103 }
1104
1105 void setMaterializerAttached(bool MaterializerAttached) {
1106 this->MaterializerAttached = MaterializerAttached;
1107 }
1108
1109 void setPendingRemoval(bool PendingRemoval) {
1110 this->PendingRemoval = PendingRemoval;
1111 }
1112
1113 JITEvaluatedSymbol getSymbol() const {
1114 return JITEvaluatedSymbol(Addr, Flags);
1115 }
1116
1117 private:
1118 JITTargetAddress Addr = 0;
1119 JITSymbolFlags Flags;
1120 uint8_t State : 6;
1121 uint8_t MaterializerAttached : 1;
1122 uint8_t PendingRemoval : 1;
1123 };
1124
1125 using SymbolTable = DenseMap<SymbolStringPtr, SymbolTableEntry>;
1126
1127 JITDylib(ExecutionSession &ES, std::string Name);
1128
1129 ResourceTrackerSP getTracker(MaterializationResponsibility &MR);
1130 std::pair<AsynchronousSymbolQuerySet, std::shared_ptr<SymbolDependenceMap>>
1131 removeTracker(ResourceTracker &RT);
1132
1133 void transferTracker(ResourceTracker &DstRT, ResourceTracker &SrcRT);
1134
1135 Error defineImpl(MaterializationUnit &MU);
1136
1137 void installMaterializationUnit(std::unique_ptr<MaterializationUnit> MU,
1138 ResourceTracker &RT);
1139
1140 void detachQueryHelper(AsynchronousSymbolQuery &Q,
1141 const SymbolNameSet &QuerySymbols);
1142
1143 void transferEmittedNodeDependencies(MaterializingInfo &DependantMI,
1144 const SymbolStringPtr &DependantName,
1145 MaterializingInfo &EmittedMI);
1146
1147 Expected<SymbolFlagsMap> defineMaterializing(SymbolFlagsMap SymbolFlags);
1148
1149 Error replace(MaterializationResponsibility &FromMR,
1150 std::unique_ptr<MaterializationUnit> MU);
1151
1152 Expected<std::unique_ptr<MaterializationResponsibility>>
1153 delegate(MaterializationResponsibility &FromMR, SymbolFlagsMap SymbolFlags,
1154 SymbolStringPtr InitSymbol);
1155
1156 SymbolNameSet getRequestedSymbols(const SymbolFlagsMap &SymbolFlags) const;
1157
1158 void addDependencies(const SymbolStringPtr &Name,
1159 const SymbolDependenceMap &Dependants);
1160
1161 Error resolve(MaterializationResponsibility &MR, const SymbolMap &Resolved);
1162
1163 Error emit(MaterializationResponsibility &MR, const SymbolFlagsMap &Emitted);
1164
1165 void unlinkMaterializationResponsibility(MaterializationResponsibility &MR);
1166
1167 using FailedSymbolsWorklist =
1168 std::vector<std::pair<JITDylib *, SymbolStringPtr>>;
1169
1170 static std::pair<AsynchronousSymbolQuerySet,
1171 std::shared_ptr<SymbolDependenceMap>>
1172 failSymbols(FailedSymbolsWorklist);
1173
1174 ExecutionSession &ES;
1175 std::string JITDylibName;
1176 std::mutex GeneratorsMutex;
1177 bool Open = true;
1178 SymbolTable Symbols;
1179 UnmaterializedInfosMap UnmaterializedInfos;
1180 MaterializingInfosMap MaterializingInfos;
1181 std::vector<std::shared_ptr<DefinitionGenerator>> DefGenerators;
1182 JITDylibSearchOrder LinkOrder;
1183 ResourceTrackerSP DefaultTracker;
1184
1185 // Map trackers to sets of symbols tracked.
1186 DenseMap<ResourceTracker *, SymbolNameVector> TrackerSymbols;
1187 DenseMap<MaterializationResponsibility *, ResourceTracker *> MRTrackers;
1188};
1189
1190/// Platforms set up standard symbols and mediate interactions between dynamic
1191/// initializers (e.g. C++ static constructors) and ExecutionSession state.
1192/// Note that Platforms do not automatically run initializers: clients are still
1193/// responsible for doing this.
1194class Platform {
1195public:
1196 virtual ~Platform();
1197
1198 /// This method will be called outside the session lock each time a JITDylib
1199 /// is created (unless it is created with EmptyJITDylib set) to allow the
1200 /// Platform to install any JITDylib specific standard symbols (e.g
1201 /// __dso_handle).
1202 virtual Error setupJITDylib(JITDylib &JD) = 0;
1203
1204 /// This method will be called under the ExecutionSession lock each time a
1205 /// MaterializationUnit is added to a JITDylib.
1206 virtual Error notifyAdding(ResourceTracker &RT,
1207 const MaterializationUnit &MU) = 0;
1208
1209 /// This method will be called under the ExecutionSession lock when a
1210 /// ResourceTracker is removed.
1211 virtual Error notifyRemoving(ResourceTracker &RT) = 0;
1212
1213 /// A utility function for looking up initializer symbols. Performs a blocking
1214 /// lookup for the given symbols in each of the given JITDylibs.
1215 static Expected<DenseMap<JITDylib *, SymbolMap>>
1216 lookupInitSymbols(ExecutionSession &ES,
1217 const DenseMap<JITDylib *, SymbolLookupSet> &InitSyms);
1218};
1219
1220/// An ExecutionSession represents a running JIT program.
1221class ExecutionSession {
1222 friend class InProgressLookupFlagsState;
1223 friend class InProgressFullLookupState;
1224 friend class JITDylib;
1225 friend class LookupState;
1226 friend class MaterializationResponsibility;
1227 friend class ResourceTracker;
1228
1229public:
1230 /// For reporting errors.
1231 using ErrorReporter = std::function<void(Error)>;
1232
1233 /// For dispatching MaterializationUnit::materialize calls.
1234 using DispatchMaterializationFunction =
1235 std::function<void(std::unique_ptr<MaterializationUnit> MU,
1236 std::unique_ptr<MaterializationResponsibility> MR)>;
1237
1238 /// Construct an ExecutionSession.
1239 ///
1240 /// SymbolStringPools may be shared between ExecutionSessions.
1241 ExecutionSession(std::shared_ptr<SymbolStringPool> SSP = nullptr);
1242
1243 /// End the session. Closes all JITDylibs.
1244 Error endSession();
1245
1246 /// Add a symbol name to the SymbolStringPool and return a pointer to it.
1247 SymbolStringPtr intern(StringRef SymName) { return SSP->intern(SymName); }
1248
1249 /// Returns a shared_ptr to the SymbolStringPool for this ExecutionSession.
1250 std::shared_ptr<SymbolStringPool> getSymbolStringPool() const { return SSP; }
1251
1252 /// Set the Platform for this ExecutionSession.
1253 void setPlatform(std::unique_ptr<Platform> P) { this->P = std::move(P); }
1254
1255 /// Get the Platform for this session.
1256 /// Will return null if no Platform has been set for this ExecutionSession.
1257 Platform *getPlatform() { return P.get(); }
1258
1259 /// Run the given lambda with the session mutex locked.
1260 template <typename Func> decltype(auto) runSessionLocked(Func &&F) {
1261 std::lock_guard<std::recursive_mutex> Lock(SessionMutex);
1262 return F();
1263 }
1264
1265 /// Register the given ResourceManager with this ExecutionSession.
1266 /// Managers will be notified of events in reverse order of registration.
1267 void registerResourceManager(ResourceManager &RM);
1268
1269 /// Deregister the given ResourceManager with this ExecutionSession.
1270 /// Manager must have been previously registered.
1271 void deregisterResourceManager(ResourceManager &RM);
1272
1273 /// Return a pointer to the "name" JITDylib.
1274 /// Ownership of JITDylib remains within Execution Session
1275 JITDylib *getJITDylibByName(StringRef Name);
1276
1277 /// Add a new bare JITDylib to this ExecutionSession.
1278 ///
1279 /// The JITDylib Name is required to be unique. Clients should verify that
1280 /// names are not being re-used (E.g. by calling getJITDylibByName) if names
1281 /// are based on user input.
1282 ///
1283 /// This call does not install any library code or symbols into the newly
1284 /// created JITDylib. The client is responsible for all configuration.
1285 JITDylib &createBareJITDylib(std::string Name);
1286
1287 /// Add a new JITDylib to this ExecutionSession.
1288 ///
1289 /// The JITDylib Name is required to be unique. Clients should verify that
1290 /// names are not being re-used (e.g. by calling getJITDylibByName) if names
1291 /// are based on user input.
1292 ///
1293 /// If a Platform is attached then Platform::setupJITDylib will be called to
1294 /// install standard platform symbols (e.g. standard library interposes).
1295 /// If no Platform is attached this call is equivalent to createBareJITDylib.
1296 Expected<JITDylib &> createJITDylib(std::string Name);
1297
1298 /// Set the error reporter function.
1299 ExecutionSession &setErrorReporter(ErrorReporter ReportError) {
1300 this->ReportError = std::move(ReportError);
1301 return *this;
1302 }
1303
1304 /// Report a error for this execution session.
1305 ///
1306 /// Unhandled errors can be sent here to log them.
1307 void reportError(Error Err) { ReportError(std::move(Err)); }
1308
1309 /// Set the materialization dispatch function.
1310 ExecutionSession &setDispatchMaterialization(
1311 DispatchMaterializationFunction DispatchMaterialization) {
1312 this->DispatchMaterialization = std::move(DispatchMaterialization);
1313 return *this;
1314 }
1315
1316 /// Search the given JITDylibs to find the flags associated with each of the
1317 /// given symbols.
1318 void lookupFlags(LookupKind K, JITDylibSearchOrder SearchOrder,
1319 SymbolLookupSet Symbols,
1320 unique_function<void(Expected<SymbolFlagsMap>)> OnComplete);
1321
1322 /// Blocking version of lookupFlags.
1323 Expected<SymbolFlagsMap> lookupFlags(LookupKind K,
1324 JITDylibSearchOrder SearchOrder,
1325 SymbolLookupSet Symbols);
1326
1327 /// Search the given JITDylibs for the given symbols.
1328 ///
1329 /// SearchOrder lists the JITDylibs to search. For each dylib, the associated
1330 /// boolean indicates whether the search should match against non-exported
1331 /// (hidden visibility) symbols in that dylib (true means match against
1332 /// non-exported symbols, false means do not match).
1333 ///
1334 /// The NotifyComplete callback will be called once all requested symbols
1335 /// reach the required state.
1336 ///
1337 /// If all symbols are found, the RegisterDependencies function will be called
1338 /// while the session lock is held. This gives clients a chance to register
1339 /// dependencies for on the queried symbols for any symbols they are
1340 /// materializing (if a MaterializationResponsibility instance is present,
1341 /// this can be implemented by calling
1342 /// MaterializationResponsibility::addDependencies). If there are no
1343 /// dependenant symbols for this query (e.g. it is being made by a top level
1344 /// client to get an address to call) then the value NoDependenciesToRegister
1345 /// can be used.
1346 void lookup(LookupKind K, const JITDylibSearchOrder &SearchOrder,
1347 SymbolLookupSet Symbols, SymbolState RequiredState,
1348 SymbolsResolvedCallback NotifyComplete,
1349 RegisterDependenciesFunction RegisterDependencies);
1350
1351 /// Blocking version of lookup above. Returns the resolved symbol map.
1352 /// If WaitUntilReady is true (the default), will not return until all
1353 /// requested symbols are ready (or an error occurs). If WaitUntilReady is
1354 /// false, will return as soon as all requested symbols are resolved,
1355 /// or an error occurs. If WaitUntilReady is false and an error occurs
1356 /// after resolution, the function will return a success value, but the
1357 /// error will be reported via reportErrors.
1358 Expected<SymbolMap> lookup(const JITDylibSearchOrder &SearchOrder,
1359 const SymbolLookupSet &Symbols,
1360 LookupKind K = LookupKind::Static,
1361 SymbolState RequiredState = SymbolState::Ready,
1362 RegisterDependenciesFunction RegisterDependencies =
1363 NoDependenciesToRegister);
1364
1365 /// Convenience version of blocking lookup.
1366 /// Searches each of the JITDylibs in the search order in turn for the given
1367 /// symbol.
1368 Expected<JITEvaluatedSymbol>
1369 lookup(const JITDylibSearchOrder &SearchOrder, SymbolStringPtr Symbol,
1370 SymbolState RequiredState = SymbolState::Ready);
1371
1372 /// Convenience version of blocking lookup.
1373 /// Searches each of the JITDylibs in the search order in turn for the given
1374 /// symbol. The search will not find non-exported symbols.
1375 Expected<JITEvaluatedSymbol>
1376 lookup(ArrayRef<JITDylib *> SearchOrder, SymbolStringPtr Symbol,
1377 SymbolState RequiredState = SymbolState::Ready);
1378
1379 /// Convenience version of blocking lookup.
1380 /// Searches each of the JITDylibs in the search order in turn for the given
1381 /// symbol. The search will not find non-exported symbols.
1382 Expected<JITEvaluatedSymbol>
1383 lookup(ArrayRef<JITDylib *> SearchOrder, StringRef Symbol,
1384 SymbolState RequiredState = SymbolState::Ready);
1385
1386 /// Materialize the given unit.
1387 void
1388 dispatchMaterialization(std::unique_ptr<MaterializationUnit> MU,
1389 std::unique_ptr<MaterializationResponsibility> MR) {
1390 assert(MU && "MU must be non-null");
1391 DEBUG_WITH_TYPE("orc", dumpDispatchInfo(MR->getTargetJITDylib(), *MU));
1392 DispatchMaterialization(std::move(MU), std::move(MR));
1393 }
1394
1395 /// Dump the state of all the JITDylibs in this session.
1396 void dump(raw_ostream &OS);
1397
1398private:
1399 static void logErrorsToStdErr(Error Err) {
1400 logAllUnhandledErrors(std::move(Err), errs(), "JIT session error: ");
1401 }
1402
1403 static void materializeOnCurrentThread(
1404 std::unique_ptr<MaterializationUnit> MU,
1405 std::unique_ptr<MaterializationResponsibility> MR) {
1406 MU->materialize(std::move(MR));
1407 }
1408
1409 void dispatchOutstandingMUs();
1410
1411 static std::unique_ptr<MaterializationResponsibility>
1412 createMaterializationResponsibility(ResourceTracker &RT,
1413 SymbolFlagsMap Symbols,
1414 SymbolStringPtr InitSymbol) {
1415 auto &JD = RT.getJITDylib();
1416 std::unique_ptr<MaterializationResponsibility> MR(
1417 new MaterializationResponsibility(&JD, std::move(Symbols),
1418 std::move(InitSymbol)));
1419 JD.MRTrackers[MR.get()] = &RT;
1420 return MR;
1421 }
1422
1423 Error removeResourceTracker(ResourceTracker &RT);
1424 void transferResourceTracker(ResourceTracker &DstRT, ResourceTracker &SrcRT);
1425 void destroyResourceTracker(ResourceTracker &RT);
1426
1427 // State machine functions for query application..
1428
1429 /// IL_updateCandidatesFor is called to remove already-defined symbols that
1430 /// match a given query from the set of candidate symbols to generate
1431 /// definitions for (no need to generate a definition if one already exists).
1432 Error IL_updateCandidatesFor(JITDylib &JD, JITDylibLookupFlags JDLookupFlags,
1433 SymbolLookupSet &Candidates,
1434 SymbolLookupSet *NonCandidates);
1435
1436 /// OL_applyQueryPhase1 is an optionally re-startable loop for triggering
1437 /// definition generation. It is called when a lookup is performed, and again
1438 /// each time that LookupState::continueLookup is called.
1439 void OL_applyQueryPhase1(std::unique_ptr<InProgressLookupState> IPLS,
1440 Error Err);
1441
1442 /// OL_completeLookup is run once phase 1 successfully completes for a lookup
1443 /// call. It attempts to attach the symbol to all symbol table entries and
1444 /// collect all MaterializationUnits to dispatch. If this method fails then
1445 /// all MaterializationUnits will be left un-materialized.
1446 void OL_completeLookup(std::unique_ptr<InProgressLookupState> IPLS,
1447 std::shared_ptr<AsynchronousSymbolQuery> Q,
1448 RegisterDependenciesFunction RegisterDependencies);
1449
1450 /// OL_completeLookupFlags is run once phase 1 successfully completes for a
1451 /// lookupFlags call.
1452 void OL_completeLookupFlags(
1453 std::unique_ptr<InProgressLookupState> IPLS,
1454 unique_function<void(Expected<SymbolFlagsMap>)> OnComplete);
1455
1456 // State machine functions for MaterializationResponsibility.
1457 void OL_destroyMaterializationResponsibility(
1458 MaterializationResponsibility &MR);
1459 SymbolNameSet OL_getRequestedSymbols(const MaterializationResponsibility &MR);
1460 Error OL_notifyResolved(MaterializationResponsibility &MR,
1461 const SymbolMap &Symbols);
1462 Error OL_notifyEmitted(MaterializationResponsibility &MR);
1463 Error OL_defineMaterializing(MaterializationResponsibility &MR,
1464 SymbolFlagsMap SymbolFlags);
1465 void OL_notifyFailed(MaterializationResponsibility &MR);
1466 Error OL_replace(MaterializationResponsibility &MR,
1467 std::unique_ptr<MaterializationUnit> MU);
1468 Expected<std::unique_ptr<MaterializationResponsibility>>
1469 OL_delegate(MaterializationResponsibility &MR, const SymbolNameSet &Symbols);
1470 void OL_addDependencies(MaterializationResponsibility &MR,
1471 const SymbolStringPtr &Name,
1472 const SymbolDependenceMap &Dependencies);
1473 void OL_addDependenciesForAll(MaterializationResponsibility &MR,
1474 const SymbolDependenceMap &Dependencies);
1475
1476#ifndef NDEBUG
1477 void dumpDispatchInfo(JITDylib &JD, MaterializationUnit &MU);
1478#endif // NDEBUG
1479
1480 mutable std::recursive_mutex SessionMutex;
1481 bool SessionOpen = true;
1482 std::shared_ptr<SymbolStringPool> SSP;
1483 std::unique_ptr<Platform> P;
1484 ErrorReporter ReportError = logErrorsToStdErr;
1485 DispatchMaterializationFunction DispatchMaterialization =
1486 materializeOnCurrentThread;
1487
1488 std::vector<ResourceManager *> ResourceManagers;
1489
1490 std::vector<JITDylibSP> JDs;
1491
1492 // FIXME: Remove this (and runOutstandingMUs) once the linking layer works
1493 // with callbacks from asynchronous queries.
1494 mutable std::recursive_mutex OutstandingMUsMutex;
1495 std::vector<std::pair<std::unique_ptr<MaterializationUnit>,
1496 std::unique_ptr<MaterializationResponsibility>>>
1497 OutstandingMUs;
1498};
1499
1500inline ExecutionSession &MaterializationResponsibility::getExecutionSession() {
1501 return JD->getExecutionSession();
1502}
1503
1504template <typename Func>
1505Error MaterializationResponsibility::withResourceKeyDo(Func &&F) const {
1506 return JD->getExecutionSession().runSessionLocked([&]() -> Error {
1507 auto I = JD->MRTrackers.find(this);
1508 assert(I != JD->MRTrackers.end() && "No tracker for this MR");
1509 if (I->second->isDefunct())
1510 return make_error<ResourceTrackerDefunct>(I->second);
1511 F(I->second->getKeyUnsafe());
1512 return Error::success();
1513 });
1514}
1515
1516template <typename GeneratorT>
1517GeneratorT &JITDylib::addGenerator(std::unique_ptr<GeneratorT> DefGenerator) {
1518 auto &G = *DefGenerator;
1519 std::lock_guard<std::mutex> Lock(GeneratorsMutex);
1520 DefGenerators.push_back(std::move(DefGenerator));
1521 return G;
1522}
1523
1524template <typename Func>
1525auto JITDylib::withLinkOrderDo(Func &&F)
1526 -> decltype(F(std::declval<const JITDylibSearchOrder &>())) {
1527 return ES.runSessionLocked([&]() { return F(LinkOrder); });
1528}
1529
1530template <typename MaterializationUnitType>
1531Error JITDylib::define(std::unique_ptr<MaterializationUnitType> &&MU,
1532 ResourceTrackerSP RT) {
1533 assert(MU && "Can not define with a null MU");
1534
1535 if (MU->getSymbols().empty()) {
1536 // Empty MUs are allowable but pathological, so issue a warning.
1537 DEBUG_WITH_TYPE("orc", {
1538 dbgs() << "Warning: Discarding empty MU " << MU->getName() << " for "
1539 << getName() << "\n";
1540 });
1541 return Error::success();
1542 } else
1543 DEBUG_WITH_TYPE("orc", {
1544 dbgs() << "Defining MU " << MU->getName() << " for " << getName()
1545 << " (tracker: ";
1546 if (RT == getDefaultResourceTracker())
1547 dbgs() << "default)";
1548 else if (RT)
1549 dbgs() << RT.get() << ")\n";
1550 else
1551 dbgs() << "0x0, default will be used)\n";
1552 });
1553
1554 return ES.runSessionLocked([&, this]() -> Error {
1555 if (auto Err = defineImpl(*MU))
1556 return Err;
1557
1558 if (!RT)
1559 RT = getDefaultResourceTracker();
1560
1561 if (auto *P = ES.getPlatform()) {
1562 if (auto Err = P->notifyAdding(*RT, *MU))
1563 return Err;
1564 }
1565
1566 installMaterializationUnit(std::move(MU), *RT);
1567 return Error::success();
1568 });
1569}
1570
1571template <typename MaterializationUnitType>
1572Error JITDylib::define(std::unique_ptr<MaterializationUnitType> &MU,
1573 ResourceTrackerSP RT) {
1574 assert(MU && "Can not define with a null MU");
1575
1576 if (MU->getSymbols().empty()) {
1577 // Empty MUs are allowable but pathological, so issue a warning.
1578 DEBUG_WITH_TYPE("orc", {
1579 dbgs() << "Warning: Discarding empty MU " << MU->getName() << getName()
1580 << "\n";
1581 });
1582 return Error::success();
1583 } else
1584 DEBUG_WITH_TYPE("orc", {
1585 dbgs() << "Defining MU " << MU->getName() << " for " << getName()
1586 << " (tracker: ";
1587 if (RT == getDefaultResourceTracker())
1588 dbgs() << "default)";
1589 else if (RT)
1590 dbgs() << RT.get() << ")\n";
1591 else
1592 dbgs() << "0x0, default will be used)\n";
1593 });
1594
1595 return ES.runSessionLocked([&, this]() -> Error {
1596 if (auto Err = defineImpl(*MU))
1597 return Err;
1598
1599 if (!RT)
1600 RT = getDefaultResourceTracker();
1601
1602 if (auto *P = ES.getPlatform()) {
1603 if (auto Err = P->notifyAdding(*RT, *MU))
1604 return Err;
1605 }
1606
1607 installMaterializationUnit(std::move(MU), *RT);
1608 return Error::success();
1609 });
1610}
1611
1612/// ReexportsGenerator can be used with JITDylib::addGenerator to automatically
1613/// re-export a subset of the source JITDylib's symbols in the target.
1614class ReexportsGenerator : public DefinitionGenerator {
1615public:
1616 using SymbolPredicate = std::function<bool(SymbolStringPtr)>;
1617
1618 /// Create a reexports generator. If an Allow predicate is passed, only
1619 /// symbols for which the predicate returns true will be reexported. If no
1620 /// Allow predicate is passed, all symbols will be exported.
1621 ReexportsGenerator(JITDylib &SourceJD,
1622 JITDylibLookupFlags SourceJDLookupFlags,
1623 SymbolPredicate Allow = SymbolPredicate());
1624
1625 Error tryToGenerate(LookupState &LS, LookupKind K, JITDylib &JD,
1626 JITDylibLookupFlags JDLookupFlags,
1627 const SymbolLookupSet &LookupSet) override;
1628
1629private:
1630 JITDylib &SourceJD;
1631 JITDylibLookupFlags SourceJDLookupFlags;
1632 SymbolPredicate Allow;
1633};
1634
1635// --------------- IMPLEMENTATION --------------
1636// Implementations for inline functions/methods.
1637// ---------------------------------------------
1638
1639inline MaterializationResponsibility::~MaterializationResponsibility() {
1640 JD->getExecutionSession().OL_destroyMaterializationResponsibility(*this);
1641}
1642
1643inline SymbolNameSet MaterializationResponsibility::getRequestedSymbols() const {
1644 return JD->getExecutionSession().OL_getRequestedSymbols(*this);
1645}
1646
1647inline Error MaterializationResponsibility::notifyResolved(
1648 const SymbolMap &Symbols) {
1649 return JD->getExecutionSession().OL_notifyResolved(*this, Symbols);
1650}
1651
1652inline Error MaterializationResponsibility::notifyEmitted() {
1653 return JD->getExecutionSession().OL_notifyEmitted(*this);
1654}
1655
1656inline Error MaterializationResponsibility::defineMaterializing(
1657 SymbolFlagsMap SymbolFlags) {
1658 return JD->getExecutionSession().OL_defineMaterializing(
1659 *this, std::move(SymbolFlags));
1660}
1661
1662inline void MaterializationResponsibility::failMaterialization() {
1663 JD->getExecutionSession().OL_notifyFailed(*this);
1664}
1665
1666inline Error MaterializationResponsibility::replace(
1667 std::unique_ptr<MaterializationUnit> MU) {
1668 return JD->getExecutionSession().OL_replace(*this, std::move(MU));
1669}
1670
1671inline Expected<std::unique_ptr<MaterializationResponsibility>>
1672MaterializationResponsibility::delegate(const SymbolNameSet &Symbols) {
1673 return JD->getExecutionSession().OL_delegate(*this, Symbols);
1674}
1675
1676inline void MaterializationResponsibility::addDependencies(
1677 const SymbolStringPtr &Name, const SymbolDependenceMap &Dependencies) {
1678 JD->getExecutionSession().OL_addDependencies(*this, Name, Dependencies);
1679}
1680
1681inline void MaterializationResponsibility::addDependenciesForAll(
1682 const SymbolDependenceMap &Dependencies) {
1683 JD->getExecutionSession().OL_addDependenciesForAll(*this, Dependencies);
1684}
1685
1686} // End namespace orc
1687} // End namespace llvm
1688
1689#endif // LLVM_EXECUTIONENGINE_ORC_CORE_H
1690