LLVM  10.0.0svn
Core.h
Go to the documentation of this file.
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"
20 #include "llvm/IR/Module.h"
21 #include "llvm/Support/Debug.h"
22 
23 #include <memory>
24 #include <vector>
25 
26 #define DEBUG_TYPE "orc"
27 
28 namespace llvm {
29 namespace orc {
30 
31 // Forward declare some classes.
32 class AsynchronousSymbolQuery;
33 class ExecutionSession;
34 class MaterializationUnit;
35 class MaterializationResponsibility;
36 class JITDylib;
37 enum class SymbolState : uint8_t;
38 
39 /// VModuleKey provides a unique identifier (allocated and managed by
40 /// ExecutionSessions) for a module added to the JIT.
41 using VModuleKey = uint64_t;
42 
43 /// A set of symbol names (represented by SymbolStringPtrs for
44 // efficiency).
45 using SymbolNameSet = DenseSet<SymbolStringPtr>;
46 
47 /// A map from symbol names (as SymbolStringPtrs) to JITSymbols
48 /// (address/flags pairs).
49 using SymbolMap = DenseMap<SymbolStringPtr, JITEvaluatedSymbol>;
50 
51 /// A map from symbol names (as SymbolStringPtrs) to JITSymbolFlags.
52 using SymbolFlagsMap = DenseMap<SymbolStringPtr, JITSymbolFlags>;
53 
54 /// A base class for materialization failures that allows the failing
55 /// symbols to be obtained for logging.
56 using SymbolDependenceMap = DenseMap<JITDylib *, SymbolNameSet>;
57 
58 /// A list of (JITDylib*, bool) pairs.
59 using JITDylibSearchList = std::vector<std::pair<JITDylib *, bool>>;
60 
62  SymbolAliasMapEntry() = default;
64  : Aliasee(std::move(Aliasee)), AliasFlags(AliasFlags) {}
65 
68 };
69 
70 /// A map of Symbols to (Symbol, Flags) pairs.
72 
73 /// Render a SymbolStringPtr.
75 
76 /// Render a SymbolNameSet.
77 raw_ostream &operator<<(raw_ostream &OS, const SymbolNameSet &Symbols);
78 
79 /// Render a SymbolFlagsMap entry.
81 
82 /// Render a SymbolMap entry.
84 
85 /// Render a SymbolFlagsMap.
87 
88 /// Render a SymbolMap.
89 raw_ostream &operator<<(raw_ostream &OS, const SymbolMap &Symbols);
90 
91 /// Render a SymbolDependenceMap entry.
94 
95 /// Render a SymbolDependendeMap.
97 
98 /// Render a MaterializationUnit.
100 
101 /// Render a JITDylibSearchList.
103 
104 /// Render a SymbolAliasMap.
105 raw_ostream &operator<<(raw_ostream &OS, const SymbolAliasMap &Aliases);
106 
107 /// Render a SymbolState.
109 
110 /// Callback to notify client that symbols have been resolved.
111 using SymbolsResolvedCallback = std::function<void(Expected<SymbolMap>)>;
112 
113 /// Callback to register the dependencies for a given query.
115  std::function<void(const SymbolDependenceMap &)>;
116 
117 /// This can be used as the value for a RegisterDependenciesFunction if there
118 /// are no dependants to register with.
120 
121 /// Used to notify a JITDylib that the given set of symbols failed to
122 /// materialize.
123 class FailedToMaterialize : public ErrorInfo<FailedToMaterialize> {
124 public:
125  static char ID;
126 
128  std::error_code convertToErrorCode() const override;
129  void log(raw_ostream &OS) const override;
130  const SymbolNameSet &getSymbols() const { return Symbols; }
131 
132 private:
133  SymbolNameSet Symbols;
134 };
135 
136 /// Used to notify clients when symbols can not be found during a lookup.
137 class SymbolsNotFound : public ErrorInfo<SymbolsNotFound> {
138 public:
139  static char ID;
140 
142  std::error_code convertToErrorCode() const override;
143  void log(raw_ostream &OS) const override;
144  const SymbolNameSet &getSymbols() const { return Symbols; }
145 
146 private:
147  SymbolNameSet Symbols;
148 };
149 
150 /// Used to notify clients that a set of symbols could not be removed.
151 class SymbolsCouldNotBeRemoved : public ErrorInfo<SymbolsCouldNotBeRemoved> {
152 public:
153  static char ID;
154 
156  std::error_code convertToErrorCode() const override;
157  void log(raw_ostream &OS) const override;
158  const SymbolNameSet &getSymbols() const { return Symbols; }
159 
160 private:
161  SymbolNameSet Symbols;
162 };
163 
164 /// Tracks responsibility for materialization, and mediates interactions between
165 /// MaterializationUnits and JDs.
166 ///
167 /// An instance of this class is passed to MaterializationUnits when their
168 /// materialize method is called. It allows MaterializationUnits to resolve and
169 /// emit symbols, or abandon materialization by notifying any unmaterialized
170 /// symbols of an error.
172  friend class MaterializationUnit;
173 public:
176  operator=(MaterializationResponsibility &&) = delete;
177 
178  /// Destruct a MaterializationResponsibility instance. In debug mode
179  /// this asserts that all symbols being tracked have been either
180  /// emitted or notified of an error.
182 
183  /// Returns the target JITDylib that these symbols are being materialized
184  /// into.
185  JITDylib &getTargetJITDylib() const { return JD; }
186 
187  /// Returns the VModuleKey for this instance.
188  VModuleKey getVModuleKey() const { return K; }
189 
190  /// Returns the symbol flags map for this responsibility instance.
191  /// Note: The returned flags may have transient flags (Lazy, Materializing)
192  /// set. These should be stripped with JITSymbolFlags::stripTransientFlags
193  /// before using.
194  const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }
195 
196  /// Returns the names of any symbols covered by this
197  /// MaterializationResponsibility object that have queries pending. This
198  /// information can be used to return responsibility for unrequested symbols
199  /// back to the JITDylib via the delegate method.
200  SymbolNameSet getRequestedSymbols() const;
201 
202  /// Notifies the target JITDylib that the given symbols have been resolved.
203  /// This will update the given symbols' addresses in the JITDylib, and notify
204  /// any pending queries on the given symbols of their resolution. The given
205  /// symbols must be ones covered by this MaterializationResponsibility
206  /// instance. Individual calls to this method may resolve a subset of the
207  /// symbols, but all symbols must have been resolved prior to calling emit.
208  void notifyResolved(const SymbolMap &Symbols);
209 
210  /// Notifies the target JITDylib (and any pending queries on that JITDylib)
211  /// that all symbols covered by this MaterializationResponsibility instance
212  /// have been emitted.
213  void notifyEmitted();
214 
215  /// Adds new symbols to the JITDylib and this responsibility instance.
216  /// JITDylib entries start out in the materializing state.
217  ///
218  /// This method can be used by materialization units that want to add
219  /// additional symbols at materialization time (e.g. stubs, compile
220  /// callbacks, metadata).
221  Error defineMaterializing(const SymbolFlagsMap &SymbolFlags);
222 
223  /// Notify all not-yet-emitted covered by this MaterializationResponsibility
224  /// instance that an error has occurred.
225  /// This will remove all symbols covered by this MaterializationResponsibilty
226  /// from the target JITDylib, and send an error to any queries waiting on
227  /// these symbols.
228  void failMaterialization();
229 
230  /// Transfers responsibility to the given MaterializationUnit for all
231  /// symbols defined by that MaterializationUnit. This allows
232  /// materializers to break up work based on run-time information (e.g.
233  /// by introspecting which symbols have actually been looked up and
234  /// materializing only those).
235  void replace(std::unique_ptr<MaterializationUnit> MU);
236 
237  /// Delegates responsibility for the given symbols to the returned
238  /// materialization responsibility. Useful for breaking up work between
239  /// threads, or different kinds of materialization processes.
240  MaterializationResponsibility delegate(const SymbolNameSet &Symbols,
241  VModuleKey NewKey = VModuleKey());
242 
243  void addDependencies(const SymbolStringPtr &Name,
244  const SymbolDependenceMap &Dependencies);
245 
246  /// Add dependencies that apply to all symbols covered by this instance.
247  void addDependenciesForAll(const SymbolDependenceMap &Dependencies);
248 
249 private:
250  /// Create a MaterializationResponsibility for the given JITDylib and
251  /// initial symbols.
253  VModuleKey K);
254 
255  JITDylib &JD;
257  VModuleKey K;
258 };
259 
260 /// A MaterializationUnit represents a set of symbol definitions that can
261 /// be materialized as a group, or individually discarded (when
262 /// overriding definitions are encountered).
263 ///
264 /// MaterializationUnits are used when providing lazy definitions of symbols to
265 /// JITDylibs. The JITDylib will call materialize when the address of a symbol
266 /// is requested via the lookup method. The JITDylib will call discard if a
267 /// stronger definition is added or already present.
269 public:
271  : SymbolFlags(std::move(InitalSymbolFlags)), K(std::move(K)) {}
272 
273  virtual ~MaterializationUnit() {}
274 
275  /// Return the name of this materialization unit. Useful for debugging
276  /// output.
277  virtual StringRef getName() const = 0;
278 
279  /// Return the set of symbols that this source provides.
280  const SymbolFlagsMap &getSymbols() const { return SymbolFlags; }
281 
282  /// Called by materialization dispatchers (see
283  /// ExecutionSession::DispatchMaterializationFunction) to trigger
284  /// materialization of this MaterializationUnit.
286  materialize(MaterializationResponsibility(JD, std::move(SymbolFlags),
287  std::move(K)));
288  }
289 
290  /// Called by JITDylibs to notify MaterializationUnits that the given symbol
291  /// has been overridden.
292  void doDiscard(const JITDylib &JD, const SymbolStringPtr &Name) {
293  SymbolFlags.erase(Name);
294  discard(JD, std::move(Name));
295  }
296 
297 protected:
300 
301 private:
302  virtual void anchor();
303 
304  /// Implementations of this method should materialize all symbols
305  /// in the materialzation unit, except for those that have been
306  /// previously discarded.
307  virtual void materialize(MaterializationResponsibility R) = 0;
308 
309  /// Implementations of this method should discard the given symbol
310  /// from the source (e.g. if the source is an LLVM IR Module and the
311  /// symbol is a function, delete the function body or mark it available
312  /// externally).
313  virtual void discard(const JITDylib &JD, const SymbolStringPtr &Name) = 0;
314 };
315 
317  std::vector<std::unique_ptr<MaterializationUnit>>;
318 
319 /// A MaterializationUnit implementation for pre-existing absolute symbols.
320 ///
321 /// All symbols will be resolved and marked ready as soon as the unit is
322 /// materialized.
324 public:
326 
327  StringRef getName() const override;
328 
329 private:
330  void materialize(MaterializationResponsibility R) override;
331  void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;
332  static SymbolFlagsMap extractFlags(const SymbolMap &Symbols);
333 
334  SymbolMap Symbols;
335 };
336 
337 /// Create an AbsoluteSymbolsMaterializationUnit with the given symbols.
338 /// Useful for inserting absolute symbols into a JITDylib. E.g.:
339 /// \code{.cpp}
340 /// JITDylib &JD = ...;
341 /// SymbolStringPtr Foo = ...;
342 /// JITEvaluatedSymbol FooSym = ...;
343 /// if (auto Err = JD.define(absoluteSymbols({{Foo, FooSym}})))
344 /// return Err;
345 /// \endcode
346 ///
347 inline std::unique_ptr<AbsoluteSymbolsMaterializationUnit>
349  return llvm::make_unique<AbsoluteSymbolsMaterializationUnit>(
350  std::move(Symbols), std::move(K));
351 }
352 
353 /// A materialization unit for symbol aliases. Allows existing symbols to be
354 /// aliased with alternate flags.
356 public:
357  /// SourceJD is allowed to be nullptr, in which case the source JITDylib is
358  /// taken to be whatever JITDylib these definitions are materialized in (and
359  /// MatchNonExported has no effect). This is useful for defining aliases
360  /// within a JITDylib.
361  ///
362  /// Note: Care must be taken that no sets of aliases form a cycle, as such
363  /// a cycle will result in a deadlock when any symbol in the cycle is
364  /// resolved.
365  ReExportsMaterializationUnit(JITDylib *SourceJD, bool MatchNonExported,
366  SymbolAliasMap Aliases, VModuleKey K);
367 
368  StringRef getName() const override;
369 
370 private:
371  void materialize(MaterializationResponsibility R) override;
372  void discard(const JITDylib &JD, const SymbolStringPtr &Name) override;
373  static SymbolFlagsMap extractFlags(const SymbolAliasMap &Aliases);
374 
375  JITDylib *SourceJD = nullptr;
376  bool MatchNonExported = false;
377  SymbolAliasMap Aliases;
378 };
379 
380 /// Create a ReExportsMaterializationUnit with the given aliases.
381 /// Useful for defining symbol aliases.: E.g., given a JITDylib JD containing
382 /// symbols "foo" and "bar", we can define aliases "baz" (for "foo") and "qux"
383 /// (for "bar") with: \code{.cpp}
384 /// SymbolStringPtr Baz = ...;
385 /// SymbolStringPtr Qux = ...;
386 /// if (auto Err = JD.define(symbolAliases({
387 /// {Baz, { Foo, JITSymbolFlags::Exported }},
388 /// {Qux, { Bar, JITSymbolFlags::Weak }}}))
389 /// return Err;
390 /// \endcode
391 inline std::unique_ptr<ReExportsMaterializationUnit>
393  return llvm::make_unique<ReExportsMaterializationUnit>(
394  nullptr, true, std::move(Aliases), std::move(K));
395 }
396 
397 /// Create a materialization unit for re-exporting symbols from another JITDylib
398 /// with alternative names/flags.
399 /// If MatchNonExported is true then non-exported symbols from SourceJD can be
400 /// re-exported. If it is false, attempts to re-export a non-exported symbol
401 /// will result in a "symbol not found" error.
402 inline std::unique_ptr<ReExportsMaterializationUnit>
403 reexports(JITDylib &SourceJD, SymbolAliasMap Aliases,
404  bool MatchNonExported = false, VModuleKey K = VModuleKey()) {
405  return llvm::make_unique<ReExportsMaterializationUnit>(
406  &SourceJD, MatchNonExported, std::move(Aliases), std::move(K));
407 }
408 
409 /// Build a SymbolAliasMap for the common case where you want to re-export
410 /// symbols from another JITDylib with the same linkage/flags.
412 buildSimpleReexportsAliasMap(JITDylib &SourceJD, const SymbolNameSet &Symbols);
413 
414 /// ReexportsGenerator can be used with JITDylib::setGenerator to automatically
415 /// re-export a subset of the source JITDylib's symbols in the target.
417 public:
418  using SymbolPredicate = std::function<bool(SymbolStringPtr)>;
419 
420  /// Create a reexports generator. If an Allow predicate is passed, only
421  /// symbols for which the predicate returns true will be reexported. If no
422  /// Allow predicate is passed, all symbols will be exported.
423  ReexportsGenerator(JITDylib &SourceJD, bool MatchNonExported = false,
424  SymbolPredicate Allow = SymbolPredicate());
425 
426  Expected<SymbolNameSet> operator()(JITDylib &JD, const SymbolNameSet &Names);
427 
428 private:
429  JITDylib &SourceJD;
430  bool MatchNonExported = false;
431  SymbolPredicate Allow;
432 };
433 
434 /// Represents the state that a symbol has reached during materialization.
435 enum class SymbolState : uint8_t {
436  Invalid, /// No symbol should be in this state.
437  NeverSearched, /// Added to the symbol table, never queried.
438  Materializing, /// Queried, materialization begun.
439  Resolved, /// Assigned address, still materializing.
440  Ready = 0x3f /// Ready and safe for clients to access.
441 };
442 
443 /// A symbol query that returns results via a callback when results are
444 /// ready.
445 ///
446 /// makes a callback when all symbols are available.
448  friend class ExecutionSession;
449  friend class JITDylib;
451 
452 public:
453  /// Create a query for the given symbols. The NotifyComplete
454  /// callback will be called once all queried symbols reach the given
455  /// minimum state.
456  AsynchronousSymbolQuery(const SymbolNameSet &Symbols,
457  SymbolState RequiredState,
458  SymbolsResolvedCallback NotifyComplete);
459 
460  /// Notify the query that a requested symbol has reached the required state.
461  void notifySymbolMetRequiredState(const SymbolStringPtr &Name,
462  JITEvaluatedSymbol Sym);
463 
464  /// Returns true if all symbols covered by this query have been
465  /// resolved.
466  bool isComplete() const { return OutstandingSymbolsCount == 0; }
467 
468  /// Call the NotifyComplete callback.
469  ///
470  /// This should only be called if all symbols covered by the query have
471  /// reached the specified state.
472  void handleComplete();
473 
474 private:
475  SymbolState getRequiredState() { return RequiredState; }
476 
477  void addQueryDependence(JITDylib &JD, SymbolStringPtr Name);
478 
479  void removeQueryDependence(JITDylib &JD, const SymbolStringPtr &Name);
480 
481  bool canStillFail();
482 
483  void handleFailed(Error Err);
484 
485  void detach();
486 
487  SymbolsResolvedCallback NotifyComplete;
488  SymbolDependenceMap QueryRegistrations;
489  SymbolMap ResolvedSymbols;
490  size_t OutstandingSymbolsCount;
491  SymbolState RequiredState;
492 };
493 
494 /// A symbol table that supports asynchoronous symbol queries.
495 ///
496 /// Represents a virtual shared object. Instances can not be copied or moved, so
497 /// their addresses may be used as keys for resource management.
498 /// JITDylib state changes must be made via an ExecutionSession to guarantee
499 /// that they are synchronized with respect to other JITDylib operations.
500 class JITDylib {
502  friend class ExecutionSession;
504 public:
505  using GeneratorFunction = std::function<Expected<SymbolNameSet>(
506  JITDylib &Parent, const SymbolNameSet &Names)>;
507 
509  std::set<std::shared_ptr<AsynchronousSymbolQuery>>;
510 
511  JITDylib(const JITDylib &) = delete;
512  JITDylib &operator=(const JITDylib &) = delete;
513  JITDylib(JITDylib &&) = delete;
514  JITDylib &operator=(JITDylib &&) = delete;
515 
516  /// Get the name for this JITDylib.
517  const std::string &getName() const { return JITDylibName; }
518 
519  /// Get a reference to the ExecutionSession for this JITDylib.
520  ExecutionSession &getExecutionSession() const { return ES; }
521 
522  /// Set a definition generator. If set, whenever a symbol fails to resolve
523  /// within this JITDylib, lookup and lookupFlags will pass the unresolved
524  /// symbols set to the definition generator. The generator can optionally
525  /// add a definition for the unresolved symbols to the dylib.
526  void setGenerator(GeneratorFunction DefGenerator) {
527  this->DefGenerator = std::move(DefGenerator);
528  }
529 
530  /// Set the search order to be used when fixing up definitions in JITDylib.
531  /// This will replace the previous search order, and apply to any symbol
532  /// resolutions made for definitions in this JITDylib after the call to
533  /// setSearchOrder (even if the definition itself was added before the
534  /// call).
535  ///
536  /// If SearchThisJITDylibFirst is set, which by default it is, then this
537  /// JITDylib will add itself to the beginning of the SearchOrder (Clients
538  /// should *not* put this JITDylib in the list in this case, to avoid
539  /// redundant lookups).
540  ///
541  /// If SearchThisJITDylibFirst is false then the search order will be used as
542  /// given. The main motivation for this feature is to support deliberate
543  /// shadowing of symbols in this JITDylib by a facade JITDylib. For example,
544  /// the facade may resolve function names to stubs, and the stubs may compile
545  /// lazily by looking up symbols in this dylib. Adding the facade dylib
546  /// as the first in the search order (instead of this dylib) ensures that
547  /// definitions within this dylib resolve to the lazy-compiling stubs,
548  /// rather than immediately materializing the definitions in this dylib.
549  void setSearchOrder(JITDylibSearchList NewSearchOrder,
550  bool SearchThisJITDylibFirst = true,
551  bool MatchNonExportedInThisDylib = true);
552 
553  /// Add the given JITDylib to the search order for definitions in this
554  /// JITDylib.
555  void addToSearchOrder(JITDylib &JD, bool MatcNonExported = false);
556 
557  /// Replace OldJD with NewJD in the search order if OldJD is present.
558  /// Otherwise this operation is a no-op.
559  void replaceInSearchOrder(JITDylib &OldJD, JITDylib &NewJD,
560  bool MatchNonExported = false);
561 
562  /// Remove the given JITDylib from the search order for this JITDylib if it is
563  /// present. Otherwise this operation is a no-op.
564  void removeFromSearchOrder(JITDylib &JD);
565 
566  /// Do something with the search order (run under the session lock).
567  template <typename Func>
568  auto withSearchOrderDo(Func &&F)
569  -> decltype(F(std::declval<const JITDylibSearchList &>()));
570 
571  /// Define all symbols provided by the materialization unit to be part of this
572  /// JITDylib.
573  ///
574  /// This overload always takes ownership of the MaterializationUnit. If any
575  /// errors occur, the MaterializationUnit consumed.
576  template <typename MaterializationUnitType>
577  Error define(std::unique_ptr<MaterializationUnitType> &&MU);
578 
579  /// Define all symbols provided by the materialization unit to be part of this
580  /// JITDylib.
581  ///
582  /// This overload only takes ownership of the MaterializationUnit no error is
583  /// generated. If an error occurs, ownership remains with the caller. This
584  /// may allow the caller to modify the MaterializationUnit to correct the
585  /// issue, then re-call define.
586  template <typename MaterializationUnitType>
587  Error define(std::unique_ptr<MaterializationUnitType> &MU);
588 
589  /// Tries to remove the given symbols.
590  ///
591  /// If any symbols are not defined in this JITDylib this method will return
592  /// a SymbolsNotFound error covering the missing symbols.
593  ///
594  /// If all symbols are found but some symbols are in the process of being
595  /// materialized this method will return a SymbolsCouldNotBeRemoved error.
596  ///
597  /// On success, all symbols are removed. On failure, the JITDylib state is
598  /// left unmodified (no symbols are removed).
599  Error remove(const SymbolNameSet &Names);
600 
601  /// Search the given JITDylib for the symbols in Symbols. If found, store
602  /// the flags for each symbol in Flags. Returns any unresolved symbols.
603  Expected<SymbolFlagsMap> lookupFlags(const SymbolNameSet &Names);
604 
605  /// Dump current JITDylib state to OS.
606  void dump(raw_ostream &OS);
607 
608  /// FIXME: Remove this when we remove the old ORC layers.
609  /// Search the given JITDylibs in order for the symbols in Symbols. Results
610  /// (once they become available) will be returned via the given Query.
611  ///
612  /// If any symbol is not found then the unresolved symbols will be returned,
613  /// and the query will not be applied. The Query is not failed and can be
614  /// re-used in a subsequent lookup once the symbols have been added, or
615  /// manually failed.
617  legacyLookup(std::shared_ptr<AsynchronousSymbolQuery> Q, SymbolNameSet Names);
618 
619 private:
620  using AsynchronousSymbolQueryList =
621  std::vector<std::shared_ptr<AsynchronousSymbolQuery>>;
622 
623  struct UnmaterializedInfo {
624  UnmaterializedInfo(std::unique_ptr<MaterializationUnit> MU)
625  : MU(std::move(MU)) {}
626 
627  std::unique_ptr<MaterializationUnit> MU;
628  };
629 
630  using UnmaterializedInfosMap =
632 
633  struct MaterializingInfo {
634  SymbolDependenceMap Dependants;
635  SymbolDependenceMap UnemittedDependencies;
636  bool IsEmitted = false;
637 
638  void addQuery(std::shared_ptr<AsynchronousSymbolQuery> Q);
639  void removeQuery(const AsynchronousSymbolQuery &Q);
640  AsynchronousSymbolQueryList takeQueriesMeeting(SymbolState RequiredState);
641  AsynchronousSymbolQueryList takeAllQueries();
642  bool hasQueriesPending() const { return !PendingQueries.empty(); }
643  const AsynchronousSymbolQueryList &pendingQueries() const {
644  return PendingQueries;
645  }
646 
647  private:
648  AsynchronousSymbolQueryList PendingQueries;
649  };
650 
652 
653  class SymbolTableEntry {
654  public:
655  SymbolTableEntry() = default;
656  SymbolTableEntry(JITSymbolFlags Flags)
657  : Flags(Flags), State(static_cast<uint8_t>(SymbolState::NeverSearched)),
658  MaterializerAttached(false), PendingRemoval(false) {}
659 
660  JITTargetAddress getAddress() const { return Addr; }
661  JITSymbolFlags getFlags() const { return Flags; }
662  SymbolState getState() const { return static_cast<SymbolState>(State); }
663 
664  bool isInMaterializationPhase() const {
665  return getState() == SymbolState::Materializing ||
666  getState() == SymbolState::Resolved;
667  }
668 
669  bool hasMaterializerAttached() const { return MaterializerAttached; }
670  bool isPendingRemoval() const { return PendingRemoval; }
671 
672  void setAddress(JITTargetAddress Addr) { this->Addr = Addr; }
673  void setFlags(JITSymbolFlags Flags) { this->Flags = Flags; }
674  void setState(SymbolState State) {
675  assert(static_cast<uint8_t>(State) < (1 << 6) &&
676  "State does not fit in bitfield");
677  this->State = static_cast<uint8_t>(State);
678  }
679 
680  void setMaterializerAttached(bool MaterializerAttached) {
681  this->MaterializerAttached = MaterializerAttached;
682  }
683 
684  void setPendingRemoval(bool PendingRemoval) {
685  this->PendingRemoval = PendingRemoval;
686  }
687 
688  JITEvaluatedSymbol getSymbol() const {
689  return JITEvaluatedSymbol(Addr, Flags);
690  }
691 
692  private:
693  JITTargetAddress Addr = 0;
694  JITSymbolFlags Flags;
695  uint8_t State : 6;
696  uint8_t MaterializerAttached : 1;
697  uint8_t PendingRemoval : 1;
698  };
699 
701 
702  JITDylib(ExecutionSession &ES, std::string Name);
703 
704  Error defineImpl(MaterializationUnit &MU);
705 
706  Expected<SymbolNameSet> lookupFlagsImpl(SymbolFlagsMap &Flags,
707  const SymbolNameSet &Names);
708 
709  Error lodgeQuery(std::shared_ptr<AsynchronousSymbolQuery> &Q,
710  SymbolNameSet &Unresolved, bool MatchNonExported,
712 
713  void lodgeQueryImpl(std::shared_ptr<AsynchronousSymbolQuery> &Q,
714  SymbolNameSet &Unresolved, bool MatchNonExported,
716 
717  bool lookupImpl(std::shared_ptr<AsynchronousSymbolQuery> &Q,
718  std::vector<std::unique_ptr<MaterializationUnit>> &MUs,
719  SymbolNameSet &Unresolved);
720 
721  void detachQueryHelper(AsynchronousSymbolQuery &Q,
722  const SymbolNameSet &QuerySymbols);
723 
724  void transferEmittedNodeDependencies(MaterializingInfo &DependantMI,
725  const SymbolStringPtr &DependantName,
726  MaterializingInfo &EmittedMI);
727 
728  Error defineMaterializing(const SymbolFlagsMap &SymbolFlags);
729 
730  void replace(std::unique_ptr<MaterializationUnit> MU);
731 
732  SymbolNameSet getRequestedSymbols(const SymbolFlagsMap &SymbolFlags) const;
733 
734  void addDependencies(const SymbolStringPtr &Name,
735  const SymbolDependenceMap &Dependants);
736 
737  void resolve(const SymbolMap &Resolved);
738 
739  void emit(const SymbolFlagsMap &Emitted);
740 
741  void notifyFailed(const SymbolNameSet &FailedSymbols);
742 
743  ExecutionSession &ES;
744  std::string JITDylibName;
745  SymbolTable Symbols;
746  UnmaterializedInfosMap UnmaterializedInfos;
747  MaterializingInfosMap MaterializingInfos;
748  GeneratorFunction DefGenerator;
749  JITDylibSearchList SearchOrder;
750 };
751 
752 /// An ExecutionSession represents a running JIT program.
754  // FIXME: Remove this when we remove the old ORC layers.
755  friend class JITDylib;
756 
757 public:
758  /// For reporting errors.
759  using ErrorReporter = std::function<void(Error)>;
760 
761  /// For dispatching MaterializationUnit::materialize calls.
763  JITDylib &JD, std::unique_ptr<MaterializationUnit> MU)>;
764 
765  /// Construct an ExecutionSession.
766  ///
767  /// SymbolStringPools may be shared between ExecutionSessions.
768  ExecutionSession(std::shared_ptr<SymbolStringPool> SSP = nullptr);
769 
770  /// Add a symbol name to the SymbolStringPool and return a pointer to it.
771  SymbolStringPtr intern(StringRef SymName) { return SSP->intern(SymName); }
772 
773  /// Returns a shared_ptr to the SymbolStringPool for this ExecutionSession.
774  std::shared_ptr<SymbolStringPool> getSymbolStringPool() const { return SSP; }
775 
776  /// Run the given lambda with the session mutex locked.
777  template <typename Func> auto runSessionLocked(Func &&F) -> decltype(F()) {
778  std::lock_guard<std::recursive_mutex> Lock(SessionMutex);
779  return F();
780  }
781 
782  /// Get the "main" JITDylib, which is created automatically on construction of
783  /// the ExecutionSession.
784  JITDylib &getMainJITDylib();
785 
786  /// Return a pointer to the "name" JITDylib.
787  /// Ownership of JITDylib remains within Execution Session
788  JITDylib *getJITDylibByName(StringRef Name);
789 
790  /// Add a new JITDylib to this ExecutionSession.
791  ///
792  /// The JITDylib Name is required to be unique. Clients should verify that
793  /// names are not being re-used (e.g. by calling getJITDylibByName) if names
794  /// are based on user input.
795  JITDylib &createJITDylib(std::string Name,
796  bool AddToMainDylibSearchOrder = true);
797 
798  /// Allocate a module key for a new module to add to the JIT.
800  return runSessionLocked([this]() { return ++LastKey; });
801  }
802 
803  /// Return a module key to the ExecutionSession so that it can be
804  /// re-used. This should only be done once all resources associated
805  /// with the original key have been released.
806  void releaseVModule(VModuleKey Key) { /* FIXME: Recycle keys */
807  }
808 
809  /// Set the error reporter function.
811  this->ReportError = std::move(ReportError);
812  return *this;
813  }
814 
815  /// Report a error for this execution session.
816  ///
817  /// Unhandled errors can be sent here to log them.
818  void reportError(Error Err) { ReportError(std::move(Err)); }
819 
820  /// Set the materialization dispatch function.
822  DispatchMaterializationFunction DispatchMaterialization) {
823  this->DispatchMaterialization = std::move(DispatchMaterialization);
824  return *this;
825  }
826 
827  void legacyFailQuery(AsynchronousSymbolQuery &Q, Error Err);
828 
830  std::shared_ptr<AsynchronousSymbolQuery> Q, SymbolNameSet Names)>;
831 
832  /// A legacy lookup function for JITSymbolResolverAdapter.
833  /// Do not use -- this will be removed soon.
835  legacyLookup(LegacyAsyncLookupFunction AsyncLookup, SymbolNameSet Names,
836  SymbolState RequiredState,
837  RegisterDependenciesFunction RegisterDependencies);
838 
839  /// Search the given JITDylib list for the given symbols.
840  ///
841  /// SearchOrder lists the JITDylibs to search. For each dylib, the associated
842  /// boolean indicates whether the search should match against non-exported
843  /// (hidden visibility) symbols in that dylib (true means match against
844  /// non-exported symbols, false means do not match).
845  ///
846  /// The NotifyComplete callback will be called once all requested symbols
847  /// reach the required state.
848  ///
849  /// If all symbols are found, the RegisterDependencies function will be called
850  /// while the session lock is held. This gives clients a chance to register
851  /// dependencies for on the queried symbols for any symbols they are
852  /// materializing (if a MaterializationResponsibility instance is present,
853  /// this can be implemented by calling
854  /// MaterializationResponsibility::addDependencies). If there are no
855  /// dependenant symbols for this query (e.g. it is being made by a top level
856  /// client to get an address to call) then the value NoDependenciesToRegister
857  /// can be used.
858  void lookup(const JITDylibSearchList &SearchOrder, SymbolNameSet Symbols,
859  SymbolState RequiredState, SymbolsResolvedCallback NotifyComplete,
860  RegisterDependenciesFunction RegisterDependencies);
861 
862  /// Blocking version of lookup above. Returns the resolved symbol map.
863  /// If WaitUntilReady is true (the default), will not return until all
864  /// requested symbols are ready (or an error occurs). If WaitUntilReady is
865  /// false, will return as soon as all requested symbols are resolved,
866  /// or an error occurs. If WaitUntilReady is false and an error occurs
867  /// after resolution, the function will return a success value, but the
868  /// error will be reported via reportErrors.
869  Expected<SymbolMap> lookup(const JITDylibSearchList &SearchOrder,
870  const SymbolNameSet &Symbols,
871  SymbolState RequiredState = SymbolState::Ready,
872  RegisterDependenciesFunction RegisterDependencies =
873  NoDependenciesToRegister);
874 
875  /// Convenience version of blocking lookup.
876  /// Searches each of the JITDylibs in the search order in turn for the given
877  /// symbol.
880 
881  /// Convenience version of blocking lookup.
882  /// Searches each of the JITDylibs in the search order in turn for the given
883  /// symbol. The search will not find non-exported symbols.
886 
887  /// Convenience version of blocking lookup.
888  /// Searches each of the JITDylibs in the search order in turn for the given
889  /// symbol. The search will not find non-exported symbols.
891  StringRef Symbol);
892 
893  /// Materialize the given unit.
895  std::unique_ptr<MaterializationUnit> MU) {
896  LLVM_DEBUG({
897  runSessionLocked([&]() {
898  dbgs() << "Dispatching " << *MU << " for " << JD.getName() << "\n";
899  });
900  });
901  DispatchMaterialization(JD, std::move(MU));
902  }
903 
904  /// Dump the state of all the JITDylibs in this session.
905  void dump(raw_ostream &OS);
906 
907 private:
908  static void logErrorsToStdErr(Error Err) {
909  logAllUnhandledErrors(std::move(Err), errs(), "JIT session error: ");
910  }
911 
912  static void
913  materializeOnCurrentThread(JITDylib &JD,
914  std::unique_ptr<MaterializationUnit> MU) {
915  MU->doMaterialize(JD);
916  }
917 
918  void runOutstandingMUs();
919 
920  mutable std::recursive_mutex SessionMutex;
921  std::shared_ptr<SymbolStringPool> SSP;
922  VModuleKey LastKey = 0;
923  ErrorReporter ReportError = logErrorsToStdErr;
924  DispatchMaterializationFunction DispatchMaterialization =
925  materializeOnCurrentThread;
926 
927  std::vector<std::unique_ptr<JITDylib>> JDs;
928 
929  // FIXME: Remove this (and runOutstandingMUs) once the linking layer works
930  // with callbacks from asynchronous queries.
931  mutable std::recursive_mutex OutstandingMUsMutex;
932  std::vector<std::pair<JITDylib *, std::unique_ptr<MaterializationUnit>>>
933  OutstandingMUs;
934 };
935 
936 template <typename Func>
938  -> decltype(F(std::declval<const JITDylibSearchList &>())) {
939  return ES.runSessionLocked([&]() { return F(SearchOrder); });
940 }
941 
942 template <typename MaterializationUnitType>
943 Error JITDylib::define(std::unique_ptr<MaterializationUnitType> &&MU) {
944  assert(MU && "Can not define with a null MU");
945  return ES.runSessionLocked([&, this]() -> Error {
946  if (auto Err = defineImpl(*MU))
947  return Err;
948 
949  /// defineImpl succeeded.
950  auto UMI = std::make_shared<UnmaterializedInfo>(std::move(MU));
951  for (auto &KV : UMI->MU->getSymbols())
952  UnmaterializedInfos[KV.first] = UMI;
953 
954  return Error::success();
955  });
956 }
957 
958 template <typename MaterializationUnitType>
959 Error JITDylib::define(std::unique_ptr<MaterializationUnitType> &MU) {
960  assert(MU && "Can not define with a null MU");
961 
962  return ES.runSessionLocked([&, this]() -> Error {
963  if (auto Err = defineImpl(*MU))
964  return Err;
965 
966  /// defineImpl succeeded.
967  auto UMI = std::make_shared<UnmaterializedInfo>(std::move(MU));
968  for (auto &KV : UMI->MU->getSymbols())
969  UnmaterializedInfos[KV.first] = UMI;
970 
971  return Error::success();
972  });
973 }
974 
975 /// Mangles symbol names then uniques them in the context of an
976 /// ExecutionSession.
978 public:
980  SymbolStringPtr operator()(StringRef Name);
981 
982 private:
983  ExecutionSession &ES;
984  const DataLayout &DL;
985 };
986 
987 } // End namespace orc
988 } // End namespace llvm
989 
990 #undef DEBUG_TYPE // "orc"
991 
992 #endif // LLVM_EXECUTIONENGINE_ORC_CORE_H
JITSymbolFlags AliasFlags
Definition: Core.h:67
Queried, materialization begun.
A parsed version of the target data layout string in and methods for querying it. ...
Definition: DataLayout.h:110
std::shared_ptr< SymbolStringPool > getSymbolStringPool() const
Returns a shared_ptr to the SymbolStringPool for this ExecutionSession.
Definition: Core.h:774
const SymbolNameSet & getSymbols() const
Definition: Core.h:130
ExecutionSession & setDispatchMaterialization(DispatchMaterializationFunction DispatchMaterialization)
Set the materialization dispatch function.
Definition: Core.h:821
raw_ostream & errs()
This returns a reference to a raw_ostream for standard error.
Added to the symbol table, never queried.
This class represents lattice values for constants.
Definition: AllocatorList.h:23
void dispatchMaterialization(JITDylib &JD, std::unique_ptr< MaterializationUnit > MU)
Materialize the given unit.
Definition: Core.h:894
amdgpu Simplify well known AMD library false FunctionCallee Value const Twine & Name
Implements a dense probed hash-table based set.
Definition: DenseSet.h:249
std::function< void(const SymbolDependenceMap &)> RegisterDependenciesFunction
Callback to register the dependencies for a given query.
Definition: Core.h:115
void doDiscard(const JITDylib &JD, const SymbolStringPtr &Name)
Called by JITDylibs to notify MaterializationUnits that the given symbol has been overridden...
Definition: Core.h:292
bool isComplete() const
Returns true if all symbols covered by this query have been resolved.
Definition: Core.h:466
SymbolState
Represents the state that a symbol has reached during materialization.
Definition: Core.h:435
void replace(Container &Cont, typename Container::iterator ContIt, typename Container::iterator ContEnd, RandomAccessIterator ValIt, RandomAccessIterator ValEnd)
Given a sequence container Cont, replace the range [ContIt, ContEnd) with the range [ValIt...
Definition: STLExtras.h:1366
static sys::Mutex Lock
F(f)
void setGenerator(GeneratorFunction DefGenerator)
Set a definition generator.
Definition: Core.h:526
Used to notify a JITDylib that the given set of symbols failed to materialize.
Definition: Core.h:123
std::function< bool(SymbolStringPtr)> SymbolPredicate
Definition: Core.h:418
std::unique_ptr< AbsoluteSymbolsMaterializationUnit > absoluteSymbols(SymbolMap Symbols, VModuleKey K=VModuleKey())
Create an AbsoluteSymbolsMaterializationUnit with the given symbols.
Definition: Core.h:348
void doMaterialize(JITDylib &JD)
Called by materialization dispatchers (see ExecutionSession::DispatchMaterializationFunction) to trig...
Definition: Core.h:285
Definition: BitVector.h:937
SymbolStringPtr intern(StringRef SymName)
Add a symbol name to the SymbolStringPool and return a pointer to it.
Definition: Core.h:771
std::vector< std::pair< JITDylib *, bool > > JITDylibSearchList
A list of (JITDylib*, bool) pairs.
Definition: Core.h:59
SymbolFlagsMap SymbolFlags
Definition: Core.h:298
Error define(std::unique_ptr< MaterializationUnitType > &&MU)
Define all symbols provided by the materialization unit to be part of this JITDylib.
Definition: Core.h:943
SymbolFlags
Symbol flags.
Definition: Symbol.h:24
Mangles symbol names then uniques them in the context of an ExecutionSession.
Definition: Core.h:977
static StringRef getName(Value *V)
raw_ostream & operator<<(raw_ostream &OS, const SymbolStringPtr &Sym)
Render a SymbolStringPtr.
Definition: Core.cpp:145
Tagged union holding either a T or a Error.
Definition: CachePruning.h:22
std::function< SymbolNameSet(std::shared_ptr< AsynchronousSymbolQuery > Q, SymbolNameSet Names)> LegacyAsyncLookupFunction
Definition: Core.h:830
static const uint16_t * lookup(unsigned opcode, unsigned domain, ArrayRef< uint16_t[3]> Table)
Tracks responsibility for materialization, and mediates interactions between MaterializationUnits and...
Definition: Core.h:171
virtual ~MaterializationUnit()
Definition: Core.h:273
void releaseVModule(VModuleKey Key)
Return a module key to the ExecutionSession so that it can be re-used.
Definition: Core.h:806
Key
PAL metadata keys.
auto withSearchOrderDo(Func &&F) -> decltype(F(std::declval< const JITDylibSearchList &>()))
Do something with the search order (run under the session lock).
Definition: Core.h:937
std::set< std::shared_ptr< AsynchronousSymbolQuery > > AsynchronousSymbolQuerySet
Definition: Core.h:509
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory)...
Definition: APInt.h:32
Legacy adapter. Remove once we kill off the old ORC layers.
Definition: Legacy.h:93
JITDylib & getTargetJITDylib() const
Returns the target JITDylib that these symbols are being materialized into.
Definition: Core.h:185
uint64_t JITTargetAddress
Represents an address in the target process&#39;s address space.
Definition: JITSymbol.h:40
ExecutionSession & getExecutionSession() const
Get a reference to the ExecutionSession for this JITDylib.
Definition: Core.h:520
std::unique_ptr< ReExportsMaterializationUnit > reexports(JITDylib &SourceJD, SymbolAliasMap Aliases, bool MatchNonExported=false, VModuleKey K=VModuleKey())
Create a materialization unit for re-exporting symbols from another JITDylib with alternative names/f...
Definition: Core.h:403
Expected< SymbolAliasMap > buildSimpleReexportsAliasMap(JITDylib &SourceJD, const SymbolNameSet &Symbols)
Build a SymbolAliasMap for the common case where you want to re-export symbols from another JITDylib ...
Definition: Core.cpp:668
std::unique_ptr< ReExportsMaterializationUnit > symbolAliases(SymbolAliasMap Aliases, VModuleKey K=VModuleKey())
Create a ReExportsMaterializationUnit with the given aliases.
Definition: Core.h:392
Pointer to a pooled string representing a symbol name.
DenseSet< SymbolStringPtr > SymbolNameSet
A set of symbol names (represented by SymbolStringPtrs for.
Definition: Core.h:45
void dump(const SparseBitVector< ElementSize > &LHS, raw_ostream &out)
VModuleKey getVModuleKey() const
Returns the VModuleKey for this instance.
Definition: Core.h:188
A materialization unit for symbol aliases.
Definition: Core.h:355
const SymbolNameSet & getSymbols() const
Definition: Core.h:158
VModuleKey allocateVModule()
Allocate a module key for a new module to add to the JIT.
Definition: Core.h:799
std::function< void(Expected< SymbolMap >)> SymbolsResolvedCallback
Callback to notify client that symbols have been resolved.
Definition: Core.h:111
Flags for symbols in the JIT.
Definition: JITSymbol.h:55
Used to notify clients when symbols can not be found during a lookup.
Definition: Core.h:137
void logAllUnhandledErrors(Error E, raw_ostream &OS, Twine ErrorBanner={})
Log all errors (if any) in E to OS.
Definition: Error.cpp:61
No symbol should be in this state.
A MaterializationUnit represents a set of symbol definitions that can be materialized as a group...
Definition: Core.h:268
static ErrorSuccess success()
Create a success value.
Definition: Error.h:326
Module.h This file contains the declarations for the Module class.
Assigned address, still materializing.
SymbolStringPtr Aliasee
Definition: Core.h:66
An ExecutionSession represents a running JIT program.
Definition: Core.h:753
raw_ostream & dbgs()
dbgs() - This returns a reference to a raw_ostream for debugging messages.
Definition: Debug.cpp:132
const SymbolFlagsMap & getSymbols() const
Returns the symbol flags map for this responsibility instance.
Definition: Core.h:194
Represents a symbol that has been evaluated to an address already.
Definition: JITSymbol.h:189
Base class for user error types.
Definition: Error.h:344
A symbol query that returns results via a callback when results are ready.
Definition: Core.h:447
std::vector< std::unique_ptr< MaterializationUnit > > MaterializationUnitList
Definition: Core.h:317
uint8_t uint64_t VModuleKey
VModuleKey provides a unique identifier (allocated and managed by ExecutionSessions) for a module add...
Definition: Core.h:41
const SymbolFlagsMap & getSymbols() const
Return the set of symbols that this source provides.
Definition: Core.h:280
void reportError(Error Err)
Report a error for this execution session.
Definition: Core.h:818
auto runSessionLocked(Func &&F) -> decltype(F())
Run the given lambda with the session mutex locked.
Definition: Core.h:777
A MaterializationUnit implementation for pre-existing absolute symbols.
Definition: Core.h:323
const std::string & getName() const
Get the name for this JITDylib.
Definition: Core.h:517
ExecutionSession & setErrorReporter(ErrorReporter ReportError)
Set the error reporter function.
Definition: Core.h:810
const SymbolNameSet & getSymbols() const
Definition: Core.h:144
MaterializationUnit(SymbolFlagsMap InitalSymbolFlags, VModuleKey K)
Definition: Core.h:270
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
Used to notify clients that a set of symbols could not be removed.
Definition: Core.h:151
std::function< void(Error)> ErrorReporter
For reporting errors.
Definition: Core.h:759
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:45
print Print MemDeps of function
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48
RegisterDependenciesFunction NoDependenciesToRegister
This can be used as the value for a RegisterDependenciesFunction if there are no dependants to regist...
Definition: Core.cpp:140
SymbolAliasMapEntry(SymbolStringPtr Aliasee, JITSymbolFlags AliasFlags)
Definition: Core.h:63
#define LLVM_DEBUG(X)
Definition: Debug.h:122
static void LLVM_ATTRIBUTE_NORETURN ReportError(uint32_t StartOffset, const char *ErrorMsg)
std::function< void(JITDylib &JD, std::unique_ptr< MaterializationUnit > MU)> DispatchMaterializationFunction
For dispatching MaterializationUnit::materialize calls.
Definition: Core.h:763
std::function< Expected< SymbolNameSet >(JITDylib &Parent, const SymbolNameSet &Names)> GeneratorFunction
Definition: Core.h:506
A symbol table that supports asynchoronous symbol queries.
Definition: Core.h:500
ReexportsGenerator can be used with JITDylib::setGenerator to automatically re-export a subset of the...
Definition: Core.h:416