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  * Represents an address in the target process.
  38  */
  39 typedef uint64_t LLVMOrcJITTargetAddress;
  40
  41 /**
  42  * Represents generic linkage flags for a symbol definition.
  43  */
  44 typedef enum {
  45   LLVMJITSymbolGenericFlagsExported = 1U << 0,
  46   LLVMJITSymbolGenericFlagsWeak = 1U << 1
  47 } LLVMJITSymbolGenericFlags;
  48
  49 /**
  50  * Represents target specific flags for a symbol definition.
  51  */
  52 typedef uint8_t LLVMJITTargetSymbolFlags;
  53
  54 /**
  55  * Represents the linkage flags for a symbol definition.
  56  */
  57 typedef struct {
  58   uint8_t GenericFlags;
  59   uint8_t TargetFlags;
  60 } LLVMJITSymbolFlags;
  61
  62 /**
  63  * Represents an evaluated symbol address and flags.
  64  */
  65 typedef struct {
  66   LLVMOrcJITTargetAddress Address;
  67   LLVMJITSymbolFlags Flags;
  68 } LLVMJITEvaluatedSymbol;
  69
  70 /**
  71  * A reference to an orc::ExecutionSession instance.
  72  */
  73 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
  74
  75 /**
  76  * Error reporter function.
  77  */
  78 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err);
  79
  80 /**
  81  * A reference to an orc::SymbolStringPool.
  82  */
  83 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef;
  84
  85 /**
  86  * A reference to an orc::SymbolStringPool table entry.
  87  */
  88 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry
  89     *LLVMOrcSymbolStringPoolEntryRef;
  90
  91 /**
  92  * Represents a pair of a symbol name and an evaluated symbol.
  93  */
  94 typedef struct {
  95   LLVMOrcSymbolStringPoolEntryRef Name;
  96   LLVMJITEvaluatedSymbol Sym;
  97 } LLVMJITCSymbolMapPair;
  98
  99 /**
 100  * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be
 101  * used to construct a SymbolMap.
 102  */
 103 typedef LLVMJITCSymbolMapPair *LLVMOrcCSymbolMapPairs;
 104
 105 /**
 106  * Lookup kind. This can be used by definition generators when deciding whether
 107  * to produce a definition for a requested symbol.
 108  *
 109  * This enum should be kept in sync with llvm::orc::LookupKind.
 110  */
 111 typedef enum {
 112   LLVMOrcLookupKindStatic,
 113   LLVMOrcLookupKindDLSym
 114 } LLVMOrcLookupKind;
 115
 116 /**
 117  * JITDylib lookup flags. This can be used by definition generators when
 118  * deciding whether to produce a definition for a requested symbol.
 119  *
 120  * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags.
 121  */
 122 typedef enum {
 123   LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly,
 124   LLVMOrcJITDylibLookupFlagsMatchAllSymbols
 125 } LLVMOrcJITDylibLookupFlags;
 126
 127 /**
 128  * Symbol lookup flags for lookup sets. This should be kept in sync with
 129  * llvm::orc::SymbolLookupFlags.
 130  */
 131 typedef enum {
 132   LLVMOrcSymbolLookupFlagsRequiredSymbol,
 133   LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol
 134 } LLVMOrcSymbolLookupFlags;
 135
 136 /**
 137  * An element type for a symbol lookup set.
 138  */
 139 typedef struct {
 140   LLVMOrcSymbolStringPoolEntryRef Name;
 141   LLVMOrcSymbolLookupFlags LookupFlags;
 142 } LLVMOrcCLookupSetElement;
 143
 144 /**
 145  * A set of symbols to look up / generate.
 146  *
 147  * The list is terminated with an element containing a null pointer for the
 148  * Name field.
 149  *
 150  * If a client creates an instance of this type then they are responsible for
 151  * freeing it, and for ensuring that all strings have been retained over the
 152  * course of its life. Clients receiving a copy from a callback are not
 153  * responsible for managing lifetime or retain counts.
 154  */
 155 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet;
 156
 157 /**
 158  * A reference to an orc::MaterializationUnit.
 159  */
 160 typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef;
 161
 162 /**
 163  * A reference to an orc::JITDylib instance.
 164  */
 165 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
 166
 167 /**
 168  * A reference to an orc::ResourceTracker instance.
 169  */
 170 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef;
 171
 172 /**
 173  * A reference to an orc::DefinitionGenerator.
 174  */
 175 typedef struct LLVMOrcOpaqueDefinitionGenerator
 176     *LLVMOrcDefinitionGeneratorRef;
 177
 178 /**
 179  * An opaque lookup state object. Instances of this type can be captured to
 180  * suspend a lookup while a custom generator function attempts to produce a
 181  * definition.
 182  *
 183  * If a client captures a lookup state object then they must eventually call
 184  * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required
 185  * in order to release memory allocated for the lookup state, even if errors
 186  * have occurred while the lookup was suspended (if these errors have made the
 187  * lookup impossible to complete then it will issue its own error before
 188  * destruction).
 189  */
 190 typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef;
 191
 192 /**
 193  * A custom generator function. This can be used to create a custom generator
 194  * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting
 195  * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to
 196  * receive callbacks when lookups fail to match existing definitions.
 197  *
 198  * GeneratorObj will contain the address of the custom generator object.
 199  *
 200  * Ctx will contain the context object passed to
 201  * LLVMOrcCreateCustomCAPIDefinitionGenerator.
 202  *
 203  * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This
 204  * can optionally be modified to make the definition generation process
 205  * asynchronous: If the LookupStateRef value is copied, and the original
 206  * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the
 207  * asynchronous definition process has been completed clients must call
 208  * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be
 209  * done unconditionally, even if errors have occurred in the mean time, to
 210  * free the lookup state memory and notify the query object of the failures. If
 211  * LookupState is captured this function must return LLVMErrorSuccess.
 212  *
 213  * The Kind argument can be inspected to determine the lookup kind (e.g.
 214  * as-if-during-static-link, or as-if-during-dlsym).
 215  *
 216  * The JD argument specifies which JITDylib the definitions should be generated
 217  * into.
 218  *
 219  * The JDLookupFlags argument can be inspected to determine whether the original
 220  * lookup included non-exported symobls.
 221  *
 222  * Finally, the LookupSet argument contains the set of symbols that could not
 223  * be found in JD already (the set of generation candidates).
 224  */
 225 typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)(
 226     LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx,
 227     LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind,
 228     LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags,
 229     LLVMOrcCLookupSet LookupSet, size_t LookupSetSize);
 230
 231 /**
 232  * Predicate function for SymbolStringPoolEntries.
 233  */
 234 typedef int (*LLVMOrcSymbolPredicate)(LLVMOrcSymbolStringPoolEntryRef Sym,
 235                                       void *Ctx);
 236
 237 /**
 238  * A reference to an orc::ThreadSafeContext instance.
 239  */
 240 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
 241
 242 /**
 243  * A reference to an orc::ThreadSafeModule instance.
 244  */
 245 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
 246
 247 /**
 248  * A reference to an orc::JITTargetMachineBuilder instance.
 249  */
 250 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
 251     *LLVMOrcJITTargetMachineBuilderRef;
 252
 253 /**
 254  * A reference to an orc::LLJITBuilder instance.
 255  */
 256 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef;
 257
 258 /**
 259  * A reference to an orc::LLJIT instance.
 260  */
 261 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef;
 262
 263 /**
 264  * Attach a custom error reporter function to the ExecutionSession.
 265  *
 266  * The error reporter will be called to deliver failure notices that can not be
 267  * directly reported to a caller. For example, failure to resolve symbols in
 268  * the JIT linker is typically reported via the error reporter (callers
 269  * requesting definitions from the JIT will typically be delivered a
 270  * FailureToMaterialize error instead).
 271  */
 272 void LLVMOrcExecutionSessionSetErrorReporter(
 273     LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError,
 274     void *Ctx);
 275
 276 /**
 277  * Return a reference to the SymbolStringPool for an ExecutionSession.
 278  *
 279  * Ownership of the pool remains with the ExecutionSession: The caller is
 280  * not required to free the pool.
 281  */
 282 LLVMOrcSymbolStringPoolRef
 283 LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES);
 284
 285 /**
 286  * Clear all unreferenced symbol string pool entries.
 287  *
 288  * This can be called at any time to release unused entries in the
 289  * ExecutionSession's string pool. Since it locks the pool (preventing
 290  * interning of any new strings) it is recommended that it only be called
 291  * infrequently, ideally when the caller has reason to believe that some
 292  * entries will have become unreferenced, e.g. after removing a module or
 293  * closing a JITDylib.
 294  */
 295 void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP);
 296
 297 /**
 298  * Intern a string in the ExecutionSession's SymbolStringPool and return a
 299  * reference to it. This increments the ref-count of the pool entry, and the
 300  * returned value should be released once the client is done with it by
 301  * calling LLVMOrReleaseSymbolStringPoolEntry.
 302  *
 303  * Since strings are uniqued within the SymbolStringPool
 304  * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
 305  * equality.
 306  *
 307  * Note that this function does not perform linker-mangling on the string.
 308  */
 309 LLVMOrcSymbolStringPoolEntryRef
 310 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
 311
 312 /**
 313  * Increments the ref-count for a SymbolStringPool entry.
 314  */
 315 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
 316
 317 /**
 318  * Reduces the ref-count for of a SymbolStringPool entry.
 319  */
 320 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
 321
 322 /**
 323  * Reduces the ref-count of a ResourceTracker.
 324  */
 325 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT);
 326
 327 /**
 328  * Transfers tracking of all resources associated with resource tracker SrcRT
 329  * to resource tracker DstRT.
 330  */
 331 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT,
 332                                       LLVMOrcResourceTrackerRef DstRT);
 333
 334 /**
 335  * Remove all resources associated with the given tracker. See
 336  * ResourceTracker::remove().
 337  */
 338 LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT);
 339
 340 /**
 341  * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
 342  * ownership has not been passed to a JITDylib (e.g. because some error
 343  * prevented the client from calling LLVMOrcJITDylibAddGenerator).
 344  */
 345 void LLVMOrcDisposeDefinitionGenerator(
 346     LLVMOrcDefinitionGeneratorRef DG);
 347
 348 /**
 349  * Dispose of a MaterializationUnit.
 350  */
 351 void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU);
 352
 353 /**
 354  * Create a MaterializationUnit to define the given symbols as pointing to
 355  * the corresponding raw addresses.
 356  */
 357 LLVMOrcMaterializationUnitRef
 358 LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs);
 359
 360 /**
 361  * Create a "bare" JITDylib.
 362  *
 363  * The client is responsible for ensuring that the JITDylib's name is unique,
 364  * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
 365  *
 366  * This call does not install any library code or symbols into the newly
 367  * created JITDylib. The client is responsible for all configuration.
 368  */
 369 LLVMOrcJITDylibRef
 370 LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES,
 371                                           const char *Name);
 372
 373 /**
 374  * Create a JITDylib.
 375  *
 376  * The client is responsible for ensuring that the JITDylib's name is unique,
 377  * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
 378  *
 379  * If a Platform is attached to the ExecutionSession then
 380  * Platform::setupJITDylib will be called to install standard platform symbols
 381  * (e.g. standard library interposes). If no Platform is installed then this
 382  * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will
 383  * always return success.
 384  */
 385 LLVMErrorRef
 386 LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES,
 387                                       LLVMOrcJITDylibRef *Result,
 388                                       const char *Name);
 389
 390 /**
 391  * Returns the JITDylib with the given name, or NULL if no such JITDylib
 392  * exists.
 393  */
 394 LLVMOrcJITDylibRef LLVMOrcExecutionSessionGetJITDylibByName(const char *Name);
 395
 396 /**
 397  * Return a reference to a newly created resource tracker associated with JD.
 398  * The tracker is returned with an initial ref-count of 1, and must be released
 399  * with LLVMOrcReleaseResourceTracker when no longer needed.
 400  */
 401 LLVMOrcResourceTrackerRef
 402 LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD);
 403
 404 /**
 405  * Return a reference to the default resource tracker for the given JITDylib.
 406  * This operation will increase the retain count of the tracker: Clients should
 407  * call LLVMOrcReleaseResourceTracker when the result is no longer needed.
 408  */
 409 LLVMOrcResourceTrackerRef
 410 LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD);
 411
 412 /**
 413  * Add the given MaterializationUnit to the given JITDylib.
 414  *
 415  * If this operation succeeds then JITDylib JD will take ownership of MU.
 416  * If the operation fails then ownership remains with the caller who should
 417  * call LLVMOrcDisposeMaterializationUnit to destroy it.
 418  */
 419 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD,
 420                                    LLVMOrcMaterializationUnitRef MU);
 421
 422 /**
 423  * Calls remove on all trackers associated with this JITDylib, see
 424  * JITDylib::clear().
 425  */
 426 LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD);
 427
 428 /**
 429  * Add a DefinitionGenerator to the given JITDylib.
 430  *
 431  * The JITDylib will take ownership of the given generator: The client is no
 432  * longer responsible for managing its memory.
 433  */
 434 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
 435                                  LLVMOrcDefinitionGeneratorRef DG);
 436
 437 /**
 438  * Create a custom generator.
 439  */
 440 LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator(
 441     void *Ctx, LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F);
 442
 443 /**
 444  * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
 445  * the JITDylib. On success the resulting generator is owned by the client.
 446  * Ownership is typically transferred by adding the instance to a JITDylib
 447  * using LLVMOrcJITDylibAddGenerator,
 448  *
 449  * The GlobalPrefix argument specifies the character that appears on the front
 450  * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
 451  * If non-null, this character will be stripped from the start of all symbol
 452  * strings before passing the remaining substring to dlsym.
 453  *
 454  * The optional Filter and Ctx arguments can be used to supply a symbol name
 455  * filter: Only symbols for which the filter returns true will be visible to
 456  * JIT'd code. If the Filter argument is null then all process symbols will
 457  * be visible to JIT'd code. Note that the symbol name passed to the Filter
 458  * function is the full mangled symbol: The client is responsible for stripping
 459  * the global prefix if present.
 460  */
 461 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
 462     LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx,
 463     LLVMOrcSymbolPredicate Filter, void *FilterCtx);
 464
 465 /**
 466  * Create a ThreadSafeContext containing a new LLVMContext.
 467  *
 468  * Ownership of the underlying ThreadSafeContext data is shared: Clients
 469  * can and should dispose of their ThreadSafeContext as soon as they no longer
 470  * need to refer to it directly. Other references (e.g. from ThreadSafeModules)
 471  * will keep the data alive as long as it is needed.
 472  */
 473 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
 474
 475 /**
 476  * Get a reference to the wrapped LLVMContext.
 477  */
 478 LLVMContextRef
 479 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);
 480
 481 /**
 482  * Dispose of a ThreadSafeContext.
 483  */
 484 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
 485
 486 /**
 487  * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
 488  * ownership of the M argument which should not be disposed of or referenced
 489  * after this function returns.
 490  *
 491  * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
 492  * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer
 493  * responsible for it. If it is not transferred to the JIT then the client
 494  * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
 495  */
 496 LLVMOrcThreadSafeModuleRef
 497 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
 498                                  LLVMOrcThreadSafeContextRef TSCtx);
 499
 500 /**
 501  * Dispose of a ThreadSafeModule. This should only be called if ownership has
 502  * not been passed to LLJIT (e.g. because some error prevented the client from
 503  * adding this to the JIT).
 504  */
 505 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
 506
 507 /**
 508  * Create a JITTargetMachineBuilder by detecting the host.
 509  *
 510  * On success the client owns the resulting JITTargetMachineBuilder. It must be
 511  * passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) or disposed
 512  * of by calling LLVMOrcDisposeJITTargetMachineBuilder.
 513  */
 514 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
 515     LLVMOrcJITTargetMachineBuilderRef *Result);
 516
 517 /**
 518  * Create a JITTargetMachineBuilder from the given TargetMachine template.
 519  *
 520  * This operation takes ownership of the given TargetMachine and destroys it
 521  * before returing. The resulting JITTargetMachineBuilder is owned by the client
 522  * and must be passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder)
 523  * or disposed of by calling LLVMOrcDisposeJITTargetMachineBuilder.
 524  */
 525 LLVMOrcJITTargetMachineBuilderRef
 526 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
 527
 528 /**
 529  * Dispose of a JITTargetMachineBuilder.
 530  */
 531 void LLVMOrcDisposeJITTargetMachineBuilder(
 532     LLVMOrcJITTargetMachineBuilderRef JTMB);
 533
 534 /**
 535  * Create an LLJITTargetMachineBuilder.
 536  *
 537  * The client owns the resulting LLJITBuilder and should dispose of it using
 538  * LLVMOrcDisposeLLJITBuilder once they are done with it.
 539  */
 540 LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void);
 541
 542 /**
 543  * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership
 544  * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented
 545  * that function from being called).
 546  */
 547 void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder);
 548
 549 /**
 550  * Set the JITTargetMachineBuilder to be used when constructing the LLJIT
 551  * instance. Calling this function is optional: if it is not called then the
 552  * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a
 553  * JITTargetMachineBuilder.
 554  */
 555 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder(
 556     LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB);
 557
 558 /**
 559  * Create an LLJIT instance from an LLJITBuilder.
 560  *
 561  * This operation takes ownership of the Builder argument: clients should not
 562  * dispose of the builder after calling this function (even if the function
 563  * returns an error). If a null Builder argument is provided then a
 564  * default-constructed LLJITBuilder will be used.
 565  *
 566  * On success the resulting LLJIT instance is uniquely owned by the client and
 567  * automatically manages the memory of all JIT'd code and all modules that are
 568  * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the
 569  * LLJIT instance will free all memory managed by the JIT, including JIT'd code
 570  * and not-yet compiled modules.
 571  */
 572 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result,
 573                                 LLVMOrcLLJITBuilderRef Builder);
 574
 575 /**
 576  * Dispose of an LLJIT instance.
 577  */
 578 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J);
 579
 580 /**
 581  * Get a reference to the ExecutionSession for this LLJIT instance.
 582  *
 583  * The ExecutionSession is owned by the LLJIT instance. The client is not
 584  * responsible for managing its memory.
 585  */
 586 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J);
 587
 588 /**
 589  * Return a reference to the Main JITDylib.
 590  *
 591  * The JITDylib is owned by the LLJIT instance. The client is not responsible
 592  * for managing its memory.
 593  */
 594 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J);
 595
 596 /**
 597  * Return the target triple for this LLJIT instance. This string is owned by
 598  * the LLJIT instance and should not be freed by the client.
 599  */
 600 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J);
 601
 602 /**
 603  * Returns the global prefix character according to the LLJIT's DataLayout.
 604  */
 605 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J);
 606
 607 /**
 608  * Mangles the given string according to the LLJIT instance's DataLayout, then
 609  * interns the result in the SymbolStringPool and returns a reference to the
 610  * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to
 611  * decrement the ref-count on the pool entry once they are finished with this
 612  * value.
 613  */
 614 LLVMOrcSymbolStringPoolEntryRef
 615 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName);
 616
 617 /**
 618  * Add a buffer representing an object file to the given JITDylib in the given
 619  * LLJIT instance. This operation transfers ownership of the buffer to the
 620  * LLJIT instance. The buffer should not be disposed of or referenced once this
 621  * function returns.
 622  *
 623  * Resources associated with the given object will be tracked by the given
 624  * JITDylib's default resource tracker.
 625  */
 626 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD,
 627                                        LLVMMemoryBufferRef ObjBuffer);
 628
 629 /**
 630  * Add a buffer representing an object file to the given ResourceTracker's
 631  * JITDylib in the given LLJIT instance. This operation transfers ownership of
 632  * the buffer to the LLJIT instance. The buffer should not be disposed of or
 633  * referenced once this function returns.
 634  *
 635  * Resources associated with the given object will be tracked by ResourceTracker
 636  * RT.
 637  */
 638 LLVMErrorRef LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J,
 639                                              LLVMOrcResourceTrackerRef RT,
 640                                              LLVMMemoryBufferRef ObjBuffer);
 641
 642 /**
 643  * Add an IR module to the given JITDylib in the given LLJIT instance. This
 644  * operation transfers ownership of the TSM argument to the LLJIT instance.
 645  * The TSM argument should not be disposed of or referenced once this
 646  * function returns.
 647  *
 648  * Resources associated with the given Module will be tracked by the given
 649  * JITDylib's default resource tracker.
 650  */
 651 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J,
 652                                          LLVMOrcJITDylibRef JD,
 653                                          LLVMOrcThreadSafeModuleRef TSM);
 654
 655 /**
 656  * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT
 657  * instance. This operation transfers ownership of the TSM argument to the LLJIT
 658  * instance. The TSM argument should not be disposed of or referenced once this
 659  * function returns.
 660  *
 661  * Resources associated with the given Module will be tracked by ResourceTracker
 662  * RT.
 663  */
 664 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(LLVMOrcLLJITRef J,
 665                                                LLVMOrcResourceTrackerRef JD,
 666                                                LLVMOrcThreadSafeModuleRef TSM);
 667
 668 /**
 669  * Look up the given symbol in the main JITDylib of the given LLJIT instance.
 670  *
 671  * This operation does not take ownership of the Name argument.
 672  */
 673 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J,
 674                                 LLVMOrcJITTargetAddress *Result,
 675                                 const char *Name);
 676
 677 LLVM_C_EXTERN_C_END
 678
 679 #endif /* LLVM_C_ORC_H */