llvm/include/llvm-c/Orc.h

   1 /*===---------------- llvm-c/Orc.h - OrcV2 C bindings -----------*- C++ -*-===*\
   2 |*                                                                            *|
   3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
   4 |* Exceptions.                                                                *|
   5 |* See https://llvm.org/LICENSE.txt for license information.                  *|
   6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
   7 |*                                                                            *|
   8 |*===----------------------------------------------------------------------===*|
   9 |*                                                                            *|
  10 |* This header declares the C interface to libLLVMOrcJIT.a, which implements  *|
  11 |* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *|
  12 |* (especially memory ownership rules) is provided. Core Orc concepts are     *|
  13 |* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++       *|
  14 |* headers                                                                    *|
  15 |*                                                                            *|
  16 |* Many exotic languages can interoperate with C code but have a harder time  *|
  17 |* with C++ due to name mangling. So in addition to C, this interface enables *|
  18 |* tools written in such languages.                                           *|
  19 |*                                                                            *|
  20 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
  21 |*       changed without warning. Only C API usage documentation is           *|
  22 |*       provided. See the C++ documentation for all higher level ORC API     *|
  23 |*       details.                                                             *|
  24 |*                                                                            *|
  25 \*===----------------------------------------------------------------------===*/
  26
  27 #ifndef LLVM_C_ORC_H
  28 #define LLVM_C_ORC_H
  29
  30 #include "llvm-c/Error.h"
  31 #include "llvm-c/TargetMachine.h"
  32 #include "llvm-c/Types.h"
  33
  34 LLVM_C_EXTERN_C_BEGIN
  35
  36 /**
  37  * @defgroup LLVMCExecutionEngineORC On-Request-Compilation
  38  * @ingroup LLVMCExecutionEngine
  39  *
  40  * @{
  41  */
  42
  43 /**
  44  * Represents an address in the executor process.
  45  */
  46 typedef uint64_t LLVMOrcJITTargetAddress;
  47
  48 /**
  49  * Represents an address in the executor process.
  50  */
  51 typedef uint64_t LLVMOrcExecutorAddress;
  52
  53 /**
  54  * Represents generic linkage flags for a symbol definition.
  55  */
  56 typedef enum {
  57   LLVMJITSymbolGenericFlagsNone = 0,
  58   LLVMJITSymbolGenericFlagsExported = 1U << 0,
  59   LLVMJITSymbolGenericFlagsWeak = 1U << 1,
  60   LLVMJITSymbolGenericFlagsCallable = 1U << 2,
  61   LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly = 1U << 3
  62 } LLVMJITSymbolGenericFlags;
  63
  64 /**
  65  * Represents target specific flags for a symbol definition.
  66  */
  67 typedef uint8_t LLVMJITSymbolTargetFlags;
  68
  69 /**
  70  * Represents the linkage flags for a symbol definition.
  71  */
  72 typedef struct {
  73   uint8_t GenericFlags;
  74   uint8_t TargetFlags;
  75 } LLVMJITSymbolFlags;
  76
  77 /**
  78  * Represents an evaluated symbol address and flags.
  79  */
  80 typedef struct {
  81   LLVMOrcExecutorAddress Address;
  82   LLVMJITSymbolFlags Flags;
  83 } LLVMJITEvaluatedSymbol;
  84
  85 /**
  86  * A reference to an orc::ExecutionSession instance.
  87  */
  88 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
  89
  90 /**
  91  * Error reporter function.
  92  */
  93 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err);
  94
  95 /**
  96  * A reference to an orc::SymbolStringPool.
  97  */
  98 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef;
  99
 100 /**
 101  * A reference to an orc::SymbolStringPool table entry.
 102  */
 103 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry
 104     *LLVMOrcSymbolStringPoolEntryRef;
 105
 106 /**
 107  * Represents a pair of a symbol name and LLVMJITSymbolFlags.
 108  */
 109 typedef struct {
 110   LLVMOrcSymbolStringPoolEntryRef Name;
 111   LLVMJITSymbolFlags Flags;
 112 } LLVMOrcCSymbolFlagsMapPair;
 113
 114 /**
 115  * Represents a list of (SymbolStringPtr, JITSymbolFlags) pairs that can be used
 116  * to construct a SymbolFlagsMap.
 117  */
 118 typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs;
 119
 120 /**
 121  * Represents a pair of a symbol name and an evaluated symbol.
 122  */
 123 typedef struct {
 124   LLVMOrcSymbolStringPoolEntryRef Name;
 125   LLVMJITEvaluatedSymbol Sym;
 126 } LLVMOrcCSymbolMapPair;
 127
 128 /**
 129  * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be
 130  * used to construct a SymbolMap.
 131  */
 132 typedef LLVMOrcCSymbolMapPair *LLVMOrcCSymbolMapPairs;
 133
 134 /**
 135  * Represents a SymbolAliasMapEntry
 136  */
 137 typedef struct {
 138   LLVMOrcSymbolStringPoolEntryRef Name;
 139   LLVMJITSymbolFlags Flags;
 140 } LLVMOrcCSymbolAliasMapEntry;
 141
 142 /**
 143  * Represents a pair of a symbol name and SymbolAliasMapEntry.
 144  */
 145 typedef struct {
 146   LLVMOrcSymbolStringPoolEntryRef Name;
 147   LLVMOrcCSymbolAliasMapEntry Entry;
 148 } LLVMOrcCSymbolAliasMapPair;
 149
 150 /**
 151  * Represents a list of (SymbolStringPtr, (SymbolStringPtr, JITSymbolFlags))
 152  * pairs that can be used to construct a SymbolFlagsMap.
 153  */
 154 typedef LLVMOrcCSymbolAliasMapPair *LLVMOrcCSymbolAliasMapPairs;
 155
 156 /**
 157  * A reference to an orc::JITDylib instance.
 158  */
 159 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
 160
 161 /**
 162  * Represents a list of LLVMOrcSymbolStringPoolEntryRef and the associated
 163  * length.
 164  */
 165 typedef struct {
 166   LLVMOrcSymbolStringPoolEntryRef *Symbols;
 167   size_t Length;
 168 } LLVMOrcCSymbolsList;
 169
 170 /**
 171  * Represents a pair of a JITDylib and LLVMOrcCSymbolsList.
 172  */
 173 typedef struct {
 174   LLVMOrcJITDylibRef JD;
 175   LLVMOrcCSymbolsList Names;
 176 } LLVMOrcCDependenceMapPair;
 177
 178 /**
 179  * Represents a list of (JITDylibRef, (LLVMOrcSymbolStringPoolEntryRef*,
 180  * size_t)) pairs that can be used to construct a SymbolDependenceMap.
 181  */
 182 typedef LLVMOrcCDependenceMapPair *LLVMOrcCDependenceMapPairs;
 183
 184 /**
 185  * A set of symbols that share dependencies.
 186  */
 187 typedef struct {
 188   LLVMOrcCSymbolsList Symbols;
 189   LLVMOrcCDependenceMapPairs Dependencies;
 190   size_t NumDependencies;
 191 } LLVMOrcCSymbolDependenceGroup;
 192
 193 /**
 194  * Lookup kind. This can be used by definition generators when deciding whether
 195  * to produce a definition for a requested symbol.
 196  *
 197  * This enum should be kept in sync with llvm::orc::LookupKind.
 198  */
 199 typedef enum {
 200   LLVMOrcLookupKindStatic,
 201   LLVMOrcLookupKindDLSym
 202 } LLVMOrcLookupKind;
 203
 204 /**
 205  * JITDylib lookup flags. This can be used by definition generators when
 206  * deciding whether to produce a definition for a requested symbol.
 207  *
 208  * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags.
 209  */
 210 typedef enum {
 211   LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly,
 212   LLVMOrcJITDylibLookupFlagsMatchAllSymbols
 213 } LLVMOrcJITDylibLookupFlags;
 214
 215 /**
 216  * An element type for a JITDylib search order.
 217  */
 218 typedef struct {
 219   LLVMOrcJITDylibRef JD;
 220   LLVMOrcJITDylibLookupFlags JDLookupFlags;
 221 } LLVMOrcCJITDylibSearchOrderElement;
 222
 223 /**
 224  * A JITDylib search order.
 225  *
 226  * The list is terminated with an element containing a null pointer for the JD
 227  * field.
 228  */
 229 typedef LLVMOrcCJITDylibSearchOrderElement *LLVMOrcCJITDylibSearchOrder;
 230
 231 /**
 232  * Symbol lookup flags for lookup sets. This should be kept in sync with
 233  * llvm::orc::SymbolLookupFlags.
 234  */
 235 typedef enum {
 236   LLVMOrcSymbolLookupFlagsRequiredSymbol,
 237   LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol
 238 } LLVMOrcSymbolLookupFlags;
 239
 240 /**
 241  * An element type for a symbol lookup set.
 242  */
 243 typedef struct {
 244   LLVMOrcSymbolStringPoolEntryRef Name;
 245   LLVMOrcSymbolLookupFlags LookupFlags;
 246 } LLVMOrcCLookupSetElement;
 247
 248 /**
 249  * A set of symbols to look up / generate.
 250  *
 251  * The list is terminated with an element containing a null pointer for the
 252  * Name field.
 253  *
 254  * If a client creates an instance of this type then they are responsible for
 255  * freeing it, and for ensuring that all strings have been retained over the
 256  * course of its life. Clients receiving a copy from a callback are not
 257  * responsible for managing lifetime or retain counts.
 258  */
 259 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet;
 260
 261 /**
 262  * A reference to a uniquely owned orc::MaterializationUnit instance.
 263  */
 264 typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef;
 265
 266 /**
 267  * A reference to a uniquely owned orc::MaterializationResponsibility instance.
 268  *
 269  * Ownership must be passed to a lower-level layer in a JIT stack.
 270  */
 271 typedef struct LLVMOrcOpaqueMaterializationResponsibility
 272     *LLVMOrcMaterializationResponsibilityRef;
 273
 274 /**
 275  * A MaterializationUnit materialize callback.
 276  *
 277  * Ownership of the Ctx and MR arguments passes to the callback which must
 278  * adhere to the LLVMOrcMaterializationResponsibilityRef contract (see comment
 279  * for that type).
 280  *
 281  * If this callback is called then the LLVMOrcMaterializationUnitDestroy
 282  * callback will NOT be called.
 283  */
 284 typedef void (*LLVMOrcMaterializationUnitMaterializeFunction)(
 285     void *Ctx, LLVMOrcMaterializationResponsibilityRef MR);
 286
 287 /**
 288  * A MaterializationUnit discard callback.
 289  *
 290  * Ownership of JD and Symbol remain with the caller: These arguments should
 291  * not be disposed of or released.
 292  */
 293 typedef void (*LLVMOrcMaterializationUnitDiscardFunction)(
 294     void *Ctx, LLVMOrcJITDylibRef JD, LLVMOrcSymbolStringPoolEntryRef Symbol);
 295
 296 /**
 297  * A MaterializationUnit destruction callback.
 298  *
 299  * If a custom MaterializationUnit is destroyed before its Materialize
 300  * function is called then this function will be called to provide an
 301  * opportunity for the underlying program representation to be destroyed.
 302  */
 303 typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx);
 304
 305 /**
 306  * A reference to an orc::ResourceTracker instance.
 307  */
 308 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef;
 309
 310 /**
 311  * A reference to an orc::DefinitionGenerator.
 312  */
 313 typedef struct LLVMOrcOpaqueDefinitionGenerator
 314     *LLVMOrcDefinitionGeneratorRef;
 315
 316 /**
 317  * An opaque lookup state object. Instances of this type can be captured to
 318  * suspend a lookup while a custom generator function attempts to produce a
 319  * definition.
 320  *
 321  * If a client captures a lookup state object then they must eventually call
 322  * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required
 323  * in order to release memory allocated for the lookup state, even if errors
 324  * have occurred while the lookup was suspended (if these errors have made the
 325  * lookup impossible to complete then it will issue its own error before
 326  * destruction).
 327  */
 328 typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef;
 329
 330 /**
 331  * A custom generator function. This can be used to create a custom generator
 332  * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting
 333  * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to
 334  * receive callbacks when lookups fail to match existing definitions.
 335  *
 336  * GeneratorObj will contain the address of the custom generator object.
 337  *
 338  * Ctx will contain the context object passed to
 339  * LLVMOrcCreateCustomCAPIDefinitionGenerator.
 340  *
 341  * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This
 342  * can optionally be modified to make the definition generation process
 343  * asynchronous: If the LookupStateRef value is copied, and the original
 344  * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the
 345  * asynchronous definition process has been completed clients must call
 346  * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be
 347  * done unconditionally, even if errors have occurred in the mean time, to
 348  * free the lookup state memory and notify the query object of the failures).
 349  * If LookupState is captured this function must return LLVMErrorSuccess.
 350  *
 351  * The Kind argument can be inspected to determine the lookup kind (e.g.
 352  * as-if-during-static-link, or as-if-during-dlsym).
 353  *
 354  * The JD argument specifies which JITDylib the definitions should be generated
 355  * into.
 356  *
 357  * The JDLookupFlags argument can be inspected to determine whether the original
 358  * lookup included non-exported symbols.
 359  *
 360  * Finally, the LookupSet argument contains the set of symbols that could not
 361  * be found in JD already (the set of generation candidates).
 362  */
 363 typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)(
 364     LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx,
 365     LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind,
 366     LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags,
 367     LLVMOrcCLookupSet LookupSet, size_t LookupSetSize);
 368
 369 /**
 370  * Disposer for a custom generator.
 371  *
 372  * Will be called by ORC when the JITDylib that the generator is attached to
 373  * is destroyed.
 374  */
 375 typedef void (*LLVMOrcDisposeCAPIDefinitionGeneratorFunction)(void *Ctx);
 376
 377 /**
 378  * Predicate function for SymbolStringPoolEntries.
 379  */
 380 typedef int (*LLVMOrcSymbolPredicate)(void *Ctx,
 381                                       LLVMOrcSymbolStringPoolEntryRef Sym);
 382
 383 /**
 384  * A reference to an orc::ThreadSafeContext instance.
 385  */
 386 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
 387
 388 /**
 389  * A reference to an orc::ThreadSafeModule instance.
 390  */
 391 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
 392
 393 /**
 394  * A function for inspecting/mutating IR modules, suitable for use with
 395  * LLVMOrcThreadSafeModuleWithModuleDo.
 396  */
 397 typedef LLVMErrorRef (*LLVMOrcGenericIRModuleOperationFunction)(
 398     void *Ctx, LLVMModuleRef M);
 399
 400 /**
 401  * A reference to an orc::JITTargetMachineBuilder instance.
 402  */
 403 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
 404     *LLVMOrcJITTargetMachineBuilderRef;
 405
 406 /**
 407  * A reference to an orc::ObjectLayer instance.
 408  */
 409 typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef;
 410
 411 /**
 412  * A reference to an orc::ObjectLinkingLayer instance.
 413  */
 414 typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef;
 415
 416 /**
 417  * A reference to an orc::IRTransformLayer instance.
 418  */
 419 typedef struct LLVMOrcOpaqueIRTransformLayer *LLVMOrcIRTransformLayerRef;
 420
 421 /**
 422  * A function for applying transformations as part of an transform layer.
 423  *
 424  * Implementations of this type are responsible for managing the lifetime
 425  * of the Module pointed to by ModInOut: If the LLVMModuleRef value is
 426  * overwritten then the function is responsible for disposing of the incoming
 427  * module. If the module is simply accessed/mutated in-place then ownership
 428  * returns to the caller and the function does not need to do any lifetime
 429  * management.
 430  *
 431  * Clients can call LLVMOrcLLJITGetIRTransformLayer to obtain the transform
 432  * layer of a LLJIT instance, and use LLVMOrcIRTransformLayerSetTransform
 433  * to set the function. This can be used to override the default transform
 434  * layer.
 435  */
 436 typedef LLVMErrorRef (*LLVMOrcIRTransformLayerTransformFunction)(
 437     void *Ctx, LLVMOrcThreadSafeModuleRef *ModInOut,
 438     LLVMOrcMaterializationResponsibilityRef MR);
 439
 440 /**
 441  * A reference to an orc::ObjectTransformLayer instance.
 442  */
 443 typedef struct LLVMOrcOpaqueObjectTransformLayer
 444     *LLVMOrcObjectTransformLayerRef;
 445
 446 /**
 447  * A function for applying transformations to an object file buffer.
 448  *
 449  * Implementations of this type are responsible for managing the lifetime
 450  * of the memory buffer pointed to by ObjInOut: If the LLVMMemoryBufferRef
 451  * value is overwritten then the function is responsible for disposing of the
 452  * incoming buffer. If the buffer is simply accessed/mutated in-place then
 453  * ownership returns to the caller and the function does not need to do any
 454  * lifetime management.
 455  *
 456  * The transform is allowed to return an error, in which case the ObjInOut
 457  * buffer should be disposed of and set to null.
 458  */
 459 typedef LLVMErrorRef (*LLVMOrcObjectTransformLayerTransformFunction)(
 460     void *Ctx, LLVMMemoryBufferRef *ObjInOut);
 461
 462 /**
 463  * A reference to an orc::IndirectStubsManager instance.
 464  */
 465 typedef struct LLVMOrcOpaqueIndirectStubsManager
 466     *LLVMOrcIndirectStubsManagerRef;
 467
 468 /**
 469  * A reference to an orc::LazyCallThroughManager instance.
 470  */
 471 typedef struct LLVMOrcOpaqueLazyCallThroughManager
 472     *LLVMOrcLazyCallThroughManagerRef;
 473
 474 /**
 475  * A reference to an orc::DumpObjects object.
 476  *
 477  * Can be used to dump object files to disk with unique names. Useful as an
 478  * ObjectTransformLayer transform.
 479  */
 480 typedef struct LLVMOrcOpaqueDumpObjects *LLVMOrcDumpObjectsRef;
 481
 482 /**
 483  * Attach a custom error reporter function to the ExecutionSession.
 484  *
 485  * The error reporter will be called to deliver failure notices that can not be
 486  * directly reported to a caller. For example, failure to resolve symbols in
 487  * the JIT linker is typically reported via the error reporter (callers
 488  * requesting definitions from the JIT will typically be delivered a
 489  * FailureToMaterialize error instead).
 490  */
 491 void LLVMOrcExecutionSessionSetErrorReporter(
 492     LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError,
 493     void *Ctx);
 494
 495 /**
 496  * Return a reference to the SymbolStringPool for an ExecutionSession.
 497  *
 498  * Ownership of the pool remains with the ExecutionSession: The caller is
 499  * not required to free the pool.
 500  */
 501 LLVMOrcSymbolStringPoolRef
 502 LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES);
 503
 504 /**
 505  * Clear all unreferenced symbol string pool entries.
 506  *
 507  * This can be called at any time to release unused entries in the
 508  * ExecutionSession's string pool. Since it locks the pool (preventing
 509  * interning of any new strings) it is recommended that it only be called
 510  * infrequently, ideally when the caller has reason to believe that some
 511  * entries will have become unreferenced, e.g. after removing a module or
 512  * closing a JITDylib.
 513  */
 514 void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP);
 515
 516 /**
 517  * Intern a string in the ExecutionSession's SymbolStringPool and return a
 518  * reference to it. This increments the ref-count of the pool entry, and the
 519  * returned value should be released once the client is done with it by
 520  * calling LLVMOrcReleaseSymbolStringPoolEntry.
 521  *
 522  * Since strings are uniqued within the SymbolStringPool
 523  * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
 524  * equality.
 525  *
 526  * Note that this function does not perform linker-mangling on the string.
 527  */
 528 LLVMOrcSymbolStringPoolEntryRef
 529 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
 530
 531 /**
 532  * Callback type for ExecutionSession lookups.
 533  *
 534  * If Err is LLVMErrorSuccess then Result will contain a pointer to a
 535  * list of ( SymbolStringPtr, JITEvaluatedSymbol ) pairs of length NumPairs.
 536  *
 537  * If Err is a failure value then Result and Ctx are undefined and should
 538  * not be accessed. The Callback is responsible for handling the error
 539  * value (e.g. by calling LLVMGetErrorMessage + LLVMDisposeErrorMessage).
 540  *
 541  * The caller retains ownership of the Result array and will release all
 542  * contained symbol names. Clients are responsible for retaining any symbol
 543  * names that they wish to hold after the function returns.
 544  */
 545 typedef void (*LLVMOrcExecutionSessionLookupHandleResultFunction)(
 546     LLVMErrorRef Err, LLVMOrcCSymbolMapPairs Result, size_t NumPairs,
 547     void *Ctx);
 548
 549 /**
 550  * Look up symbols in an execution session.
 551  *
 552  * This is a wrapper around the general ExecutionSession::lookup function.
 553  *
 554  * The SearchOrder argument contains a list of (JITDylibs, JITDylibSearchFlags)
 555  * pairs that describe the search order. The JITDylibs will be searched in the
 556  * given order to try to find the symbols in the Symbols argument.
 557  *
 558  * The Symbols argument should contain a null-terminated array of
 559  * (SymbolStringPtr, SymbolLookupFlags) pairs describing the symbols to be
 560  * searched for. This function takes ownership of the elements of the Symbols
 561  * array. The Name fields of the Symbols elements are taken to have been
 562  * retained by the client for this function. The client should *not* release the
 563  * Name fields, but are still responsible for destroying the array itself.
 564  *
 565  * The HandleResult function will be called once all searched for symbols have
 566  * been found, or an error occurs. The HandleResult function will be passed an
 567  * LLVMErrorRef indicating success or failure, and (on success) a
 568  * null-terminated LLVMOrcCSymbolMapPairs array containing the function result,
 569  * and the Ctx value passed to the lookup function.
 570  *
 571  * The client is fully responsible for managing the lifetime of the Ctx object.
 572  * A common idiom is to allocate the context prior to the lookup and deallocate
 573  * it in the handler.
 574  *
 575  * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
 576  */
 577 void LLVMOrcExecutionSessionLookup(
 578     LLVMOrcExecutionSessionRef ES, LLVMOrcLookupKind K,
 579     LLVMOrcCJITDylibSearchOrder SearchOrder, size_t SearchOrderSize,
 580     LLVMOrcCLookupSet Symbols, size_t SymbolsSize,
 581     LLVMOrcExecutionSessionLookupHandleResultFunction HandleResult, void *Ctx);
 582
 583 /**
 584  * Increments the ref-count for a SymbolStringPool entry.
 585  */
 586 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
 587
 588 /**
 589  * Reduces the ref-count for of a SymbolStringPool entry.
 590  */
 591 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
 592
 593 /**
 594  * Return the c-string for the given symbol. This string will remain valid until
 595  * the entry is freed (once all LLVMOrcSymbolStringPoolEntryRefs have been
 596  * released).
 597  */
 598 const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S);
 599
 600 /**
 601  * Reduces the ref-count of a ResourceTracker.
 602  */
 603 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT);
 604
 605 /**
 606  * Transfers tracking of all resources associated with resource tracker SrcRT
 607  * to resource tracker DstRT.
 608  */
 609 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT,
 610                                       LLVMOrcResourceTrackerRef DstRT);
 611
 612 /**
 613  * Remove all resources associated with the given tracker. See
 614  * ResourceTracker::remove().
 615  */
 616 LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT);
 617
 618 /**
 619  * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
 620  * ownership has not been passed to a JITDylib (e.g. because some error
 621  * prevented the client from calling LLVMOrcJITDylibAddGenerator).
 622  */
 623 void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG);
 624
 625 /**
 626  * Dispose of a MaterializationUnit.
 627  */
 628 void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU);
 629
 630 /**
 631  * Create a custom MaterializationUnit.
 632  *
 633  * Name is a name for this MaterializationUnit to be used for identification
 634  * and logging purposes (e.g. if this MaterializationUnit produces an
 635  * object buffer then the name of that buffer will be derived from this name).
 636  *
 637  * The Syms list contains the names and linkages of the symbols provided by this
 638  * unit. This function takes ownership of the elements of the Syms array. The
 639  * Name fields of the array elements are taken to have been retained for this
 640  * function. The client should *not* release the elements of the array, but is
 641  * still responsible for destroying the array itself.
 642  *
 643  * The InitSym argument indicates whether or not this MaterializationUnit
 644  * contains static initializers. If three are no static initializers (the common
 645  * case) then this argument should be null. If there are static initializers
 646  * then InitSym should be set to a unique name that also appears in the Syms
 647  * list with the LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly flag
 648  * set. This function takes ownership of the InitSym, which should have been
 649  * retained twice on behalf of this function: once for the Syms entry and once
 650  * for InitSym. If clients wish to use the InitSym value after this function
 651  * returns they must retain it once more for themselves.
 652  *
 653  * If any of the symbols in the Syms list is looked up then the Materialize
 654  * function will be called.
 655  *
 656  * If any of the symbols in the Syms list is overridden then the Discard
 657  * function will be called.
 658  *
 659  * The caller owns the underling MaterializationUnit and is responsible for
 660  * either passing it to a JITDylib (via LLVMOrcJITDylibDefine) or disposing
 661  * of it by calling LLVMOrcDisposeMaterializationUnit.
 662  */
 663 LLVMOrcMaterializationUnitRef LLVMOrcCreateCustomMaterializationUnit(
 664     const char *Name, void *Ctx, LLVMOrcCSymbolFlagsMapPairs Syms,
 665     size_t NumSyms, LLVMOrcSymbolStringPoolEntryRef InitSym,
 666     LLVMOrcMaterializationUnitMaterializeFunction Materialize,
 667     LLVMOrcMaterializationUnitDiscardFunction Discard,
 668     LLVMOrcMaterializationUnitDestroyFunction Destroy);
 669
 670 /**
 671  * Create a MaterializationUnit to define the given symbols as pointing to
 672  * the corresponding raw addresses.
 673  *
 674  * This function takes ownership of the elements of the Syms array. The Name
 675  * fields of the array elements are taken to have been retained for this
 676  * function. This allows the following pattern...
 677  *
 678  *   size_t NumPairs;
 679  *   LLVMOrcCSymbolMapPairs Sym;
 680  *   -- Build Syms array --
 681  *   LLVMOrcMaterializationUnitRef MU =
 682  *       LLVMOrcAbsoluteSymbols(Syms, NumPairs);
 683  *
 684  * ... without requiring cleanup of the elements of the Sym array afterwards.
 685  *
 686  * The client is still responsible for deleting the Sym array itself.
 687  *
 688  * If a client wishes to reuse elements of the Sym array after this call they
 689  * must explicitly retain each of the elements for themselves.
 690  */
 691 LLVMOrcMaterializationUnitRef
 692 LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs);
 693
 694 /**
 695  * Create a MaterializationUnit to define lazy re-expots. These are callable
 696  * entry points that call through to the given symbols.
 697  *
 698  * This function takes ownership of the CallableAliases array. The Name
 699  * fields of the array elements are taken to have been retained for this
 700  * function. This allows the following pattern...
 701  *
 702  *   size_t NumPairs;
 703  *   LLVMOrcCSymbolAliasMapPairs CallableAliases;
 704  *   -- Build CallableAliases array --
 705  *   LLVMOrcMaterializationUnitRef MU =
 706  *      LLVMOrcLazyReexports(LCTM, ISM, JD, CallableAliases, NumPairs);
 707  *
 708  * ... without requiring cleanup of the elements of the CallableAliases array afterwards.
 709  *
 710  * The client is still responsible for deleting the CallableAliases array itself.
 711  *
 712  * If a client wishes to reuse elements of the CallableAliases array after this call they
 713  * must explicitly retain each of the elements for themselves.
 714  */
 715 LLVMOrcMaterializationUnitRef LLVMOrcLazyReexports(
 716     LLVMOrcLazyCallThroughManagerRef LCTM, LLVMOrcIndirectStubsManagerRef ISM,
 717     LLVMOrcJITDylibRef SourceRef, LLVMOrcCSymbolAliasMapPairs CallableAliases,
 718     size_t NumPairs);
 719 // TODO: ImplSymbolMad SrcJDLoc
 720
 721 /**
 722  * Disposes of the passed MaterializationResponsibility object.
 723  *
 724  * This should only be done after the symbols covered by the object have either
 725  * been resolved and emitted (via
 726  * LLVMOrcMaterializationResponsibilityNotifyResolved and
 727  * LLVMOrcMaterializationResponsibilityNotifyEmitted) or failed (via
 728  * LLVMOrcMaterializationResponsibilityFailMaterialization).
 729  */
 730 void LLVMOrcDisposeMaterializationResponsibility(
 731     LLVMOrcMaterializationResponsibilityRef MR);
 732
 733 /**
 734  * Returns the target JITDylib that these symbols are being materialized into.
 735  */
 736 LLVMOrcJITDylibRef LLVMOrcMaterializationResponsibilityGetTargetDylib(
 737     LLVMOrcMaterializationResponsibilityRef MR);
 738
 739 /**
 740  * Returns the ExecutionSession for this MaterializationResponsibility.
 741  */
 742 LLVMOrcExecutionSessionRef
 743 LLVMOrcMaterializationResponsibilityGetExecutionSession(
 744     LLVMOrcMaterializationResponsibilityRef MR);
 745
 746 /**
 747  * Returns the symbol flags map for this responsibility instance.
 748  *
 749  * The length of the array is returned in NumPairs and the caller is responsible
 750  * for the returned memory and needs to call LLVMOrcDisposeCSymbolFlagsMap.
 751  *
 752  * To use the returned symbols beyond the livetime of the
 753  * MaterializationResponsibility requires the caller to retain the symbols
 754  * explicitly.
 755  */
 756 LLVMOrcCSymbolFlagsMapPairs LLVMOrcMaterializationResponsibilityGetSymbols(
 757     LLVMOrcMaterializationResponsibilityRef MR, size_t *NumPairs);
 758
 759 /**
 760  * Disposes of the passed LLVMOrcCSymbolFlagsMap.
 761  *
 762  * Does not release the entries themselves.
 763  */
 764 void LLVMOrcDisposeCSymbolFlagsMap(LLVMOrcCSymbolFlagsMapPairs Pairs);
 765
 766 /**
 767  * Returns the initialization pseudo-symbol, if any. This symbol will also
 768  * be present in the SymbolFlagsMap for this MaterializationResponsibility
 769  * object.
 770  *
 771  * The returned symbol is not retained over any mutating operation of the
 772  * MaterializationResponsbility or beyond the lifetime thereof.
 773  */
 774 LLVMOrcSymbolStringPoolEntryRef
 775 LLVMOrcMaterializationResponsibilityGetInitializerSymbol(
 776     LLVMOrcMaterializationResponsibilityRef MR);
 777
 778 /**
 779  * Returns the names of any symbols covered by this
 780  * MaterializationResponsibility object that have queries pending. This
 781  * information can be used to return responsibility for unrequested symbols
 782  * back to the JITDylib via the delegate method.
 783  */
 784 LLVMOrcSymbolStringPoolEntryRef *
 785 LLVMOrcMaterializationResponsibilityGetRequestedSymbols(
 786     LLVMOrcMaterializationResponsibilityRef MR, size_t *NumSymbols);
 787
 788 /**
 789  * Disposes of the passed LLVMOrcSymbolStringPoolEntryRef* .
 790  *
 791  * Does not release the symbols themselves.
 792  */
 793 void LLVMOrcDisposeSymbols(LLVMOrcSymbolStringPoolEntryRef *Symbols);
 794
 795 /**
 796  * Notifies the target JITDylib that the given symbols have been resolved.
 797  * This will update the given symbols' addresses in the JITDylib, and notify
 798  * any pending queries on the given symbols of their resolution. The given
 799  * symbols must be ones covered by this MaterializationResponsibility
 800  * instance. Individual calls to this method may resolve a subset of the
 801  * symbols, but all symbols must have been resolved prior to calling emit.
 802  *
 803  * This method will return an error if any symbols being resolved have been
 804  * moved to the error state due to the failure of a dependency. If this
 805  * method returns an error then clients should log it and call
 806  * LLVMOrcMaterializationResponsibilityFailMaterialization. If no dependencies
 807  * have been registered for the symbols covered by this
 808  * MaterializationResponsibility then this method is guaranteed to return
 809  * LLVMErrorSuccess.
 810  */
 811 LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyResolved(
 812     LLVMOrcMaterializationResponsibilityRef MR, LLVMOrcCSymbolMapPairs Symbols,
 813     size_t NumPairs);
 814
 815 /**
 816  * Notifies the target JITDylib (and any pending queries on that JITDylib)
 817  * that all symbols covered by this MaterializationResponsibility instance
 818  * have been emitted.
 819  *
 820  * This function takes ownership of the symbols in the Dependencies struct.
 821  * This allows the following pattern...
 822  *
 823  *   LLVMOrcSymbolStringPoolEntryRef Names[] = {...};
 824  *   LLVMOrcCDependenceMapPair Dependence = {JD, {Names, sizeof(Names)}}
 825  *   LLVMOrcMaterializationResponsibilityAddDependencies(JD, Name, &Dependence,
 826  * 1);
 827  *
 828  * ... without requiring cleanup of the elements of the Names array afterwards.
 829  *
 830  * The client is still responsible for deleting the Dependencies.Names arrays,
 831  * and the Dependencies array itself.
 832  *
 833  * This method will return an error if any symbols being resolved have been
 834  * moved to the error state due to the failure of a dependency. If this
 835  * method returns an error then clients should log it and call
 836  * LLVMOrcMaterializationResponsibilityFailMaterialization.
 837  * If no dependencies have been registered for the symbols covered by this
 838  * MaterializationResponsibility then this method is guaranteed to return
 839  * LLVMErrorSuccess.
 840  */
 841 LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyEmitted(
 842     LLVMOrcMaterializationResponsibilityRef MR,
 843     LLVMOrcCSymbolDependenceGroup *SymbolDepGroups, size_t NumSymbolDepGroups);
 844
 845 /**
 846  * Attempt to claim responsibility for new definitions. This method can be
 847  * used to claim responsibility for symbols that are added to a
 848  * materialization unit during the compilation process (e.g. literal pool
 849  * symbols). Symbol linkage rules are the same as for symbols that are
 850  * defined up front: duplicate strong definitions will result in errors.
 851  * Duplicate weak definitions will be discarded (in which case they will
 852  * not be added to this responsibility instance).
 853  *
 854  * This method can be used by materialization units that want to add
 855  * additional symbols at materialization time (e.g. stubs, compile
 856  * callbacks, metadata)
 857  */
 858 LLVMErrorRef LLVMOrcMaterializationResponsibilityDefineMaterializing(
 859     LLVMOrcMaterializationResponsibilityRef MR,
 860     LLVMOrcCSymbolFlagsMapPairs Pairs, size_t NumPairs);
 861
 862 /**
 863  * Notify all not-yet-emitted covered by this MaterializationResponsibility
 864  * instance that an error has occurred.
 865  * This will remove all symbols covered by this MaterializationResponsibility
 866  * from the target JITDylib, and send an error to any queries waiting on
 867  * these symbols.
 868  */
 869 void LLVMOrcMaterializationResponsibilityFailMaterialization(
 870     LLVMOrcMaterializationResponsibilityRef MR);
 871
 872 /**
 873  * Transfers responsibility to the given MaterializationUnit for all
 874  * symbols defined by that MaterializationUnit. This allows
 875  * materializers to break up work based on run-time information (e.g.
 876  * by introspecting which symbols have actually been looked up and
 877  * materializing only those).
 878  */
 879 LLVMErrorRef LLVMOrcMaterializationResponsibilityReplace(
 880     LLVMOrcMaterializationResponsibilityRef MR,
 881     LLVMOrcMaterializationUnitRef MU);
 882
 883 /**
 884  * Delegates responsibility for the given symbols to the returned
 885  * materialization responsibility. Useful for breaking up work between
 886  * threads, or different kinds of materialization processes.
 887  *
 888  * The caller retains responsibility of the the passed
 889  * MaterializationResponsibility.
 890  */
 891 LLVMErrorRef LLVMOrcMaterializationResponsibilityDelegate(
 892     LLVMOrcMaterializationResponsibilityRef MR,
 893     LLVMOrcSymbolStringPoolEntryRef *Symbols, size_t NumSymbols,
 894     LLVMOrcMaterializationResponsibilityRef *Result);
 895
 896 /**
 897  * Create a "bare" JITDylib.
 898  *
 899  * The client is responsible for ensuring that the JITDylib's name is unique,
 900  * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
 901  *
 902  * This call does not install any library code or symbols into the newly
 903  * created JITDylib. The client is responsible for all configuration.
 904  */
 905 LLVMOrcJITDylibRef
 906 LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES,
 907                                           const char *Name);
 908
 909 /**
 910  * Create a JITDylib.
 911  *
 912  * The client is responsible for ensuring that the JITDylib's name is unique,
 913  * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
 914  *
 915  * If a Platform is attached to the ExecutionSession then
 916  * Platform::setupJITDylib will be called to install standard platform symbols
 917  * (e.g. standard library interposes). If no Platform is installed then this
 918  * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will
 919  * always return success.
 920  */
 921 LLVMErrorRef
 922 LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES,
 923                                       LLVMOrcJITDylibRef *Result,
 924                                       const char *Name);
 925
 926 /**
 927  * Returns the JITDylib with the given name, or NULL if no such JITDylib
 928  * exists.
 929  */
 930 LLVMOrcJITDylibRef
 931 LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES,
 932                                          const char *Name);
 933
 934 /**
 935  * Return a reference to a newly created resource tracker associated with JD.
 936  * The tracker is returned with an initial ref-count of 1, and must be released
 937  * with LLVMOrcReleaseResourceTracker when no longer needed.
 938  */
 939 LLVMOrcResourceTrackerRef
 940 LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD);
 941
 942 /**
 943  * Return a reference to the default resource tracker for the given JITDylib.
 944  * This operation will increase the retain count of the tracker: Clients should
 945  * call LLVMOrcReleaseResourceTracker when the result is no longer needed.
 946  */
 947 LLVMOrcResourceTrackerRef
 948 LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD);
 949
 950 /**
 951  * Add the given MaterializationUnit to the given JITDylib.
 952  *
 953  * If this operation succeeds then JITDylib JD will take ownership of MU.
 954  * If the operation fails then ownership remains with the caller who should
 955  * call LLVMOrcDisposeMaterializationUnit to destroy it.
 956  */
 957 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD,
 958                                    LLVMOrcMaterializationUnitRef MU);
 959
 960 /**
 961  * Calls remove on all trackers associated with this JITDylib, see
 962  * JITDylib::clear().
 963  */
 964 LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD);
 965
 966 /**
 967  * Add a DefinitionGenerator to the given JITDylib.
 968  *
 969  * The JITDylib will take ownership of the given generator: The client is no
 970  * longer responsible for managing its memory.
 971  */
 972 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
 973                                  LLVMOrcDefinitionGeneratorRef DG);
 974
 975 /**
 976  * Create a custom generator.
 977  *
 978  * The F argument will be used to implement the DefinitionGenerator's
 979  * tryToGenerate method (see
 980  * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction).
 981  *
 982  * Ctx is a context object that will be passed to F. This argument is
 983  * permitted to be null.
 984  *
 985  * Dispose is the disposal function for Ctx. This argument is permitted to be
 986  * null (in which case the client is responsible for the lifetime of Ctx).
 987  */
 988 LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator(
 989     LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx,
 990     LLVMOrcDisposeCAPIDefinitionGeneratorFunction Dispose);
 991
 992 /**
 993  * Continue a lookup that was suspended in a generator (see
 994  * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction).
 995  */
 996 void LLVMOrcLookupStateContinueLookup(LLVMOrcLookupStateRef S,
 997                                       LLVMErrorRef Err);
 998
 999 /**
1000  * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
1001  * the JITDylib. On success the resulting generator is owned by the client.
1002  * Ownership is typically transferred by adding the instance to a JITDylib
1003  * using LLVMOrcJITDylibAddGenerator,
1004  *
1005  * The GlobalPrefix argument specifies the character that appears on the front
1006  * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
1007  * If non-null, this character will be stripped from the start of all symbol
1008  * strings before passing the remaining substring to dlsym.
1009  *
1010  * The optional Filter and Ctx arguments can be used to supply a symbol name
1011  * filter: Only symbols for which the filter returns true will be visible to
1012  * JIT'd code. If the Filter argument is null then all process symbols will
1013  * be visible to JIT'd code. Note that the symbol name passed to the Filter
1014  * function is the full mangled symbol: The client is responsible for stripping
1015  * the global prefix if present.
1016  */
1017 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
1018     LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx,
1019     LLVMOrcSymbolPredicate Filter, void *FilterCtx);
1020
1021 /**
1022  * Get a LLVMOrcCreateDynamicLibararySearchGeneratorForPath that will reflect
1023  * library symbols into the JITDylib. On success the resulting generator is
1024  * owned by the client. Ownership is typically transferred by adding the
1025  * instance to a JITDylib using LLVMOrcJITDylibAddGenerator,
1026  *
1027  * The GlobalPrefix argument specifies the character that appears on the front
1028  * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
1029  * If non-null, this character will be stripped from the start of all symbol
1030  * strings before passing the remaining substring to dlsym.
1031  *
1032  * The optional Filter and Ctx arguments can be used to supply a symbol name
1033  * filter: Only symbols for which the filter returns true will be visible to
1034  * JIT'd code. If the Filter argument is null then all library symbols will
1035  * be visible to JIT'd code. Note that the symbol name passed to the Filter
1036  * function is the full mangled symbol: The client is responsible for stripping
1037  * the global prefix if present.
1038  *
1039  * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
1040  *
1041  */
1042 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForPath(
1043     LLVMOrcDefinitionGeneratorRef *Result, const char *FileName,
1044     char GlobalPrefix, LLVMOrcSymbolPredicate Filter, void *FilterCtx);
1045
1046 /**
1047  * Get a LLVMOrcCreateStaticLibrarySearchGeneratorForPath that will reflect
1048  * static library symbols into the JITDylib. On success the resulting
1049  * generator is owned by the client. Ownership is typically transferred by
1050  * adding the instance to a JITDylib using LLVMOrcJITDylibAddGenerator,
1051  *
1052  * Call with the optional TargetTriple argument will succeed if the file at
1053  * the given path is a static library or a MachO universal binary containing a
1054  * static library that is compatible with the given triple. Otherwise it will
1055  * return an error.
1056  *
1057  * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
1058  *
1059  */
1060 LLVMErrorRef LLVMOrcCreateStaticLibrarySearchGeneratorForPath(
1061     LLVMOrcDefinitionGeneratorRef *Result, LLVMOrcObjectLayerRef ObjLayer,
1062     const char *FileName, const char *TargetTriple);
1063
1064 /**
1065  * Create a ThreadSafeContext containing a new LLVMContext.
1066  *
1067  * Ownership of the underlying ThreadSafeContext data is shared: Clients
1068  * can and should dispose of their ThreadSafeContext as soon as they no longer
1069  * need to refer to it directly. Other references (e.g. from ThreadSafeModules)
1070  * will keep the data alive as long as it is needed.
1071  */
1072 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
1073
1074 /**
1075  * Get a reference to the wrapped LLVMContext.
1076  */
1077 LLVMContextRef
1078 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);
1079
1080 /**
1081  * Dispose of a ThreadSafeContext.
1082  */
1083 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
1084
1085 /**
1086  * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
1087  * ownership of the M argument which should not be disposed of or referenced
1088  * after this function returns.
1089  *
1090  * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
1091  * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer
1092  * responsible for it. If it is not transferred to the JIT then the client
1093  * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
1094  */
1095 LLVMOrcThreadSafeModuleRef
1096 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
1097                                  LLVMOrcThreadSafeContextRef TSCtx);
1098
1099 /**
1100  * Dispose of a ThreadSafeModule. This should only be called if ownership has
1101  * not been passed to LLJIT (e.g. because some error prevented the client from
1102  * adding this to the JIT).
1103  */
1104 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
1105
1106 /**
1107  * Apply the given function to the module contained in this ThreadSafeModule.
1108  */
1109 LLVMErrorRef
1110 LLVMOrcThreadSafeModuleWithModuleDo(LLVMOrcThreadSafeModuleRef TSM,
1111                                     LLVMOrcGenericIRModuleOperationFunction F,
1112                                     void *Ctx);
1113
1114 /**
1115  * Create a JITTargetMachineBuilder by detecting the host.
1116  *
1117  * On success the client owns the resulting JITTargetMachineBuilder. It must be
1118  * passed to a consuming operation (e.g.
1119  * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
1120  * LLVMOrcDisposeJITTargetMachineBuilder.
1121  */
1122 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
1123     LLVMOrcJITTargetMachineBuilderRef *Result);
1124
1125 /**
1126  * Create a JITTargetMachineBuilder from the given TargetMachine template.
1127  *
1128  * This operation takes ownership of the given TargetMachine and destroys it
1129  * before returing. The resulting JITTargetMachineBuilder is owned by the client
1130  * and must be passed to a consuming operation (e.g.
1131  * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
1132  * LLVMOrcDisposeJITTargetMachineBuilder.
1133  */
1134 LLVMOrcJITTargetMachineBuilderRef
1135 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
1136
1137 /**
1138  * Dispose of a JITTargetMachineBuilder.
1139  */
1140 void LLVMOrcDisposeJITTargetMachineBuilder(
1141     LLVMOrcJITTargetMachineBuilderRef JTMB);
1142
1143 /**
1144  * Returns the target triple for the given JITTargetMachineBuilder as a string.
1145  *
1146  * The caller owns the resulting string as must dispose of it by calling
1147  * LLVMDisposeMessage
1148  */
1149 char *LLVMOrcJITTargetMachineBuilderGetTargetTriple(
1150     LLVMOrcJITTargetMachineBuilderRef JTMB);
1151
1152 /**
1153  * Sets the target triple for the given JITTargetMachineBuilder to the given
1154  * string.
1155  */
1156 void LLVMOrcJITTargetMachineBuilderSetTargetTriple(
1157     LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple);
1158
1159 /**
1160  * Add an object to an ObjectLayer to the given JITDylib.
1161  *
1162  * Adds a buffer representing an object file to the given JITDylib using the
1163  * given ObjectLayer instance. This operation transfers ownership of the buffer
1164  * to the ObjectLayer instance. The buffer should not be disposed of or
1165  * referenced once this function returns.
1166  *
1167  * Resources associated with the given object will be tracked by the given
1168  * JITDylib's default ResourceTracker.
1169  */
1170 LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer,
1171                                              LLVMOrcJITDylibRef JD,
1172                                              LLVMMemoryBufferRef ObjBuffer);
1173
1174 /**
1175  * Add an object to an ObjectLayer using the given ResourceTracker.
1176  *
1177  * Adds a buffer representing an object file to the given ResourceTracker's
1178  * JITDylib using the given ObjectLayer instance. This operation transfers
1179  * ownership of the buffer to the ObjectLayer instance. The buffer should not
1180  * be disposed of or referenced once this function returns.
1181  *
1182  * Resources associated with the given object will be tracked by
1183  * ResourceTracker RT.
1184  */
1185 LLVMErrorRef
1186 LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer,
1187                                       LLVMOrcResourceTrackerRef RT,
1188                                       LLVMMemoryBufferRef ObjBuffer);
1189
1190 /**
1191  * Emit an object buffer to an ObjectLayer.
1192  *
1193  * Ownership of the responsibility object and object buffer pass to this
1194  * function. The client is not responsible for cleanup.
1195  */
1196 void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer,
1197                             LLVMOrcMaterializationResponsibilityRef R,
1198                             LLVMMemoryBufferRef ObjBuffer);
1199
1200 /**
1201  * Dispose of an ObjectLayer.
1202  */
1203 void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer);
1204
1205 void LLVMOrcIRTransformLayerEmit(LLVMOrcIRTransformLayerRef IRTransformLayer,
1206                                  LLVMOrcMaterializationResponsibilityRef MR,
1207                                  LLVMOrcThreadSafeModuleRef TSM);
1208
1209 /**
1210  * Set the transform function of the provided transform layer, passing through a
1211  * pointer to user provided context.
1212  */
1213 void LLVMOrcIRTransformLayerSetTransform(
1214     LLVMOrcIRTransformLayerRef IRTransformLayer,
1215     LLVMOrcIRTransformLayerTransformFunction TransformFunction, void *Ctx);
1216
1217 /**
1218  * Set the transform function on an LLVMOrcObjectTransformLayer.
1219  */
1220 void LLVMOrcObjectTransformLayerSetTransform(
1221     LLVMOrcObjectTransformLayerRef ObjTransformLayer,
1222     LLVMOrcObjectTransformLayerTransformFunction TransformFunction, void *Ctx);
1223
1224 /**
1225  * Create a LocalIndirectStubsManager from the given target triple.
1226  *
1227  * The resulting IndirectStubsManager is owned by the client
1228  * and must be disposed of by calling LLVMOrcDisposeDisposeIndirectStubsManager.
1229  */
1230 LLVMOrcIndirectStubsManagerRef
1231 LLVMOrcCreateLocalIndirectStubsManager(const char *TargetTriple);
1232
1233 /**
1234  * Dispose of an IndirectStubsManager.
1235  */
1236 void LLVMOrcDisposeIndirectStubsManager(LLVMOrcIndirectStubsManagerRef ISM);
1237
1238 LLVMErrorRef LLVMOrcCreateLocalLazyCallThroughManager(
1239     const char *TargetTriple, LLVMOrcExecutionSessionRef ES,
1240     LLVMOrcJITTargetAddress ErrorHandlerAddr,
1241     LLVMOrcLazyCallThroughManagerRef *LCTM);
1242
1243 /**
1244  * Dispose of an LazyCallThroughManager.
1245  */
1246 void LLVMOrcDisposeLazyCallThroughManager(
1247     LLVMOrcLazyCallThroughManagerRef LCTM);
1248
1249 /**
1250  * Create a DumpObjects instance.
1251  *
1252  * DumpDir specifies the path to write dumped objects to. DumpDir may be empty
1253  * in which case files will be dumped to the working directory.
1254  *
1255  * IdentifierOverride specifies a file name stem to use when dumping objects.
1256  * If empty then each MemoryBuffer's identifier will be used (with a .o suffix
1257  * added if not already present). If an identifier override is supplied it will
1258  * be used instead, along with an incrementing counter (since all buffers will
1259  * use the same identifier, the resulting files will be named <ident>.o,
1260  * <ident>.2.o, <ident>.3.o, and so on). IdentifierOverride should not contain
1261  * an extension, as a .o suffix will be added by DumpObjects.
1262  */
1263 LLVMOrcDumpObjectsRef LLVMOrcCreateDumpObjects(const char *DumpDir,
1264                                                const char *IdentifierOverride);
1265
1266 /**
1267  * Dispose of a DumpObjects instance.
1268  */
1269 void LLVMOrcDisposeDumpObjects(LLVMOrcDumpObjectsRef DumpObjects);
1270
1271 /**
1272  * Dump the contents of the given MemoryBuffer.
1273  */
1274 LLVMErrorRef LLVMOrcDumpObjects_CallOperator(LLVMOrcDumpObjectsRef DumpObjects,
1275                                              LLVMMemoryBufferRef *ObjBuffer);
1276
1277 /**
1278  * @}
1279  */
1280
1281 LLVM_C_EXTERN_C_END
1282
1283 #endif /* LLVM_C_ORC_H */