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