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