Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2026-05-10 08:43:01

0001 /*===---------------- llvm-c/Orc.h - OrcV2 C bindings -----------*- C++ -*-===*\
0002 |*                                                                            *|
0003 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
0004 |* Exceptions.                                                                *|
0005 |* See https://llvm.org/LICENSE.txt for license information.                  *|
0006 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
0007 |*                                                                            *|
0008 |*===----------------------------------------------------------------------===*|
0009 |*                                                                            *|
0010 |* This header declares the C interface to libLLVMOrcJIT.a, which implements  *|
0011 |* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *|
0012 |* (especially memory ownership rules) is provided. Core Orc concepts are     *|
0013 |* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++       *|
0014 |* headers                                                                    *|
0015 |*                                                                            *|
0016 |* Many exotic languages can interoperate with C code but have a harder time  *|
0017 |* with C++ due to name mangling. So in addition to C, this interface enables *|
0018 |* tools written in such languages.                                           *|
0019 |*                                                                            *|
0020 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
0021 |*       changed without warning. Only C API usage documentation is           *|
0022 |*       provided. See the C++ documentation for all higher level ORC API     *|
0023 |*       details.                                                             *|
0024 |*                                                                            *|
0025 \*===----------------------------------------------------------------------===*/
0026 
0027 #ifndef LLVM_C_ORC_H
0028 #define LLVM_C_ORC_H
0029 
0030 #include "llvm-c/Error.h"
0031 #include "llvm-c/TargetMachine.h"
0032 #include "llvm-c/Types.h"
0033 
0034 LLVM_C_EXTERN_C_BEGIN
0035 
0036 /**
0037  * @defgroup LLVMCExecutionEngineORC On-Request-Compilation
0038  * @ingroup LLVMCExecutionEngine
0039  *
0040  * @{
0041  */
0042 
0043 /**
0044  * Represents an address in the executor process.
0045  */
0046 typedef uint64_t LLVMOrcJITTargetAddress;
0047 
0048 /**
0049  * Represents an address in the executor process.
0050  */
0051 typedef uint64_t LLVMOrcExecutorAddress;
0052 
0053 /**
0054  * Represents generic linkage flags for a symbol definition.
0055  */
0056 typedef enum {
0057   LLVMJITSymbolGenericFlagsNone = 0,
0058   LLVMJITSymbolGenericFlagsExported = 1U << 0,
0059   LLVMJITSymbolGenericFlagsWeak = 1U << 1,
0060   LLVMJITSymbolGenericFlagsCallable = 1U << 2,
0061   LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly = 1U << 3
0062 } LLVMJITSymbolGenericFlags;
0063 
0064 /**
0065  * Represents target specific flags for a symbol definition.
0066  */
0067 typedef uint8_t LLVMJITSymbolTargetFlags;
0068 
0069 /**
0070  * Represents the linkage flags for a symbol definition.
0071  */
0072 typedef struct {
0073   uint8_t GenericFlags;
0074   uint8_t TargetFlags;
0075 } LLVMJITSymbolFlags;
0076 
0077 /**
0078  * Represents an evaluated symbol address and flags.
0079  */
0080 typedef struct {
0081   LLVMOrcExecutorAddress Address;
0082   LLVMJITSymbolFlags Flags;
0083 } LLVMJITEvaluatedSymbol;
0084 
0085 /**
0086  * A reference to an orc::ExecutionSession instance.
0087  */
0088 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
0089 
0090 /**
0091  * Error reporter function.
0092  */
0093 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err);
0094 
0095 /**
0096  * A reference to an orc::SymbolStringPool.
0097  */
0098 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef;
0099 
0100 /**
0101  * A reference to an orc::SymbolStringPool table entry.
0102  */
0103 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry
0104     *LLVMOrcSymbolStringPoolEntryRef;
0105 
0106 /**
0107  * Represents a pair of a symbol name and LLVMJITSymbolFlags.
0108  */
0109 typedef struct {
0110   LLVMOrcSymbolStringPoolEntryRef Name;
0111   LLVMJITSymbolFlags Flags;
0112 } LLVMOrcCSymbolFlagsMapPair;
0113 
0114 /**
0115  * Represents a list of (SymbolStringPtr, JITSymbolFlags) pairs that can be used
0116  * to construct a SymbolFlagsMap.
0117  */
0118 typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs;
0119 
0120 /**
0121  * Represents a pair of a symbol name and an evaluated symbol.
0122  */
0123 typedef struct {
0124   LLVMOrcSymbolStringPoolEntryRef Name;
0125   LLVMJITEvaluatedSymbol Sym;
0126 } LLVMOrcCSymbolMapPair;
0127 
0128 /**
0129  * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be
0130  * used to construct a SymbolMap.
0131  */
0132 typedef LLVMOrcCSymbolMapPair *LLVMOrcCSymbolMapPairs;
0133 
0134 /**
0135  * Represents a SymbolAliasMapEntry
0136  */
0137 typedef struct {
0138   LLVMOrcSymbolStringPoolEntryRef Name;
0139   LLVMJITSymbolFlags Flags;
0140 } LLVMOrcCSymbolAliasMapEntry;
0141 
0142 /**
0143  * Represents a pair of a symbol name and SymbolAliasMapEntry.
0144  */
0145 typedef struct {
0146   LLVMOrcSymbolStringPoolEntryRef Name;
0147   LLVMOrcCSymbolAliasMapEntry Entry;
0148 } LLVMOrcCSymbolAliasMapPair;
0149 
0150 /**
0151  * Represents a list of (SymbolStringPtr, (SymbolStringPtr, JITSymbolFlags))
0152  * pairs that can be used to construct a SymbolFlagsMap.
0153  */
0154 typedef LLVMOrcCSymbolAliasMapPair *LLVMOrcCSymbolAliasMapPairs;
0155 
0156 /**
0157  * A reference to an orc::JITDylib instance.
0158  */
0159 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
0160 
0161 /**
0162  * Represents a list of LLVMOrcSymbolStringPoolEntryRef and the associated
0163  * length.
0164  */
0165 typedef struct {
0166   LLVMOrcSymbolStringPoolEntryRef *Symbols;
0167   size_t Length;
0168 } LLVMOrcCSymbolsList;
0169 
0170 /**
0171  * Represents a pair of a JITDylib and LLVMOrcCSymbolsList.
0172  */
0173 typedef struct {
0174   LLVMOrcJITDylibRef JD;
0175   LLVMOrcCSymbolsList Names;
0176 } LLVMOrcCDependenceMapPair;
0177 
0178 /**
0179  * Represents a list of (JITDylibRef, (LLVMOrcSymbolStringPoolEntryRef*,
0180  * size_t)) pairs that can be used to construct a SymbolDependenceMap.
0181  */
0182 typedef LLVMOrcCDependenceMapPair *LLVMOrcCDependenceMapPairs;
0183 
0184 /**
0185  * A set of symbols that share dependencies.
0186  */
0187 typedef struct {
0188   LLVMOrcCSymbolsList Symbols;
0189   LLVMOrcCDependenceMapPairs Dependencies;
0190   size_t NumDependencies;
0191 } LLVMOrcCSymbolDependenceGroup;
0192 
0193 /**
0194  * Lookup kind. This can be used by definition generators when deciding whether
0195  * to produce a definition for a requested symbol.
0196  *
0197  * This enum should be kept in sync with llvm::orc::LookupKind.
0198  */
0199 typedef enum {
0200   LLVMOrcLookupKindStatic,
0201   LLVMOrcLookupKindDLSym
0202 } LLVMOrcLookupKind;
0203 
0204 /**
0205  * JITDylib lookup flags. This can be used by definition generators when
0206  * deciding whether to produce a definition for a requested symbol.
0207  *
0208  * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags.
0209  */
0210 typedef enum {
0211   LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly,
0212   LLVMOrcJITDylibLookupFlagsMatchAllSymbols
0213 } LLVMOrcJITDylibLookupFlags;
0214 
0215 /**
0216  * An element type for a JITDylib search order.
0217  */
0218 typedef struct {
0219   LLVMOrcJITDylibRef JD;
0220   LLVMOrcJITDylibLookupFlags JDLookupFlags;
0221 } LLVMOrcCJITDylibSearchOrderElement;
0222 
0223 /**
0224  * A JITDylib search order.
0225  *
0226  * The list is terminated with an element containing a null pointer for the JD
0227  * field.
0228  */
0229 typedef LLVMOrcCJITDylibSearchOrderElement *LLVMOrcCJITDylibSearchOrder;
0230 
0231 /**
0232  * Symbol lookup flags for lookup sets. This should be kept in sync with
0233  * llvm::orc::SymbolLookupFlags.
0234  */
0235 typedef enum {
0236   LLVMOrcSymbolLookupFlagsRequiredSymbol,
0237   LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol
0238 } LLVMOrcSymbolLookupFlags;
0239 
0240 /**
0241  * An element type for a symbol lookup set.
0242  */
0243 typedef struct {
0244   LLVMOrcSymbolStringPoolEntryRef Name;
0245   LLVMOrcSymbolLookupFlags LookupFlags;
0246 } LLVMOrcCLookupSetElement;
0247 
0248 /**
0249  * A set of symbols to look up / generate.
0250  *
0251  * The list is terminated with an element containing a null pointer for the
0252  * Name field.
0253  *
0254  * If a client creates an instance of this type then they are responsible for
0255  * freeing it, and for ensuring that all strings have been retained over the
0256  * course of its life. Clients receiving a copy from a callback are not
0257  * responsible for managing lifetime or retain counts.
0258  */
0259 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet;
0260 
0261 /**
0262  * A reference to a uniquely owned orc::MaterializationUnit instance.
0263  */
0264 typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef;
0265 
0266 /**
0267  * A reference to a uniquely owned orc::MaterializationResponsibility instance.
0268  *
0269  * Ownership must be passed to a lower-level layer in a JIT stack.
0270  */
0271 typedef struct LLVMOrcOpaqueMaterializationResponsibility
0272     *LLVMOrcMaterializationResponsibilityRef;
0273 
0274 /**
0275  * A MaterializationUnit materialize callback.
0276  *
0277  * Ownership of the Ctx and MR arguments passes to the callback which must
0278  * adhere to the LLVMOrcMaterializationResponsibilityRef contract (see comment
0279  * for that type).
0280  *
0281  * If this callback is called then the LLVMOrcMaterializationUnitDestroy
0282  * callback will NOT be called.
0283  */
0284 typedef void (*LLVMOrcMaterializationUnitMaterializeFunction)(
0285     void *Ctx, LLVMOrcMaterializationResponsibilityRef MR);
0286 
0287 /**
0288  * A MaterializationUnit discard callback.
0289  *
0290  * Ownership of JD and Symbol remain with the caller: These arguments should
0291  * not be disposed of or released.
0292  */
0293 typedef void (*LLVMOrcMaterializationUnitDiscardFunction)(
0294     void *Ctx, LLVMOrcJITDylibRef JD, LLVMOrcSymbolStringPoolEntryRef Symbol);
0295 
0296 /**
0297  * A MaterializationUnit destruction callback.
0298  *
0299  * If a custom MaterializationUnit is destroyed before its Materialize
0300  * function is called then this function will be called to provide an
0301  * opportunity for the underlying program representation to be destroyed.
0302  */
0303 typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx);
0304 
0305 /**
0306  * A reference to an orc::ResourceTracker instance.
0307  */
0308 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef;
0309 
0310 /**
0311  * A reference to an orc::DefinitionGenerator.
0312  */
0313 typedef struct LLVMOrcOpaqueDefinitionGenerator
0314     *LLVMOrcDefinitionGeneratorRef;
0315 
0316 /**
0317  * An opaque lookup state object. Instances of this type can be captured to
0318  * suspend a lookup while a custom generator function attempts to produce a
0319  * definition.
0320  *
0321  * If a client captures a lookup state object then they must eventually call
0322  * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required
0323  * in order to release memory allocated for the lookup state, even if errors
0324  * have occurred while the lookup was suspended (if these errors have made the
0325  * lookup impossible to complete then it will issue its own error before
0326  * destruction).
0327  */
0328 typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef;
0329 
0330 /**
0331  * A custom generator function. This can be used to create a custom generator
0332  * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting
0333  * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to
0334  * receive callbacks when lookups fail to match existing definitions.
0335  *
0336  * GeneratorObj will contain the address of the custom generator object.
0337  *
0338  * Ctx will contain the context object passed to
0339  * LLVMOrcCreateCustomCAPIDefinitionGenerator.
0340  *
0341  * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This
0342  * can optionally be modified to make the definition generation process
0343  * asynchronous: If the LookupStateRef value is copied, and the original
0344  * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the
0345  * asynchronous definition process has been completed clients must call
0346  * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be
0347  * done unconditionally, even if errors have occurred in the mean time, to
0348  * free the lookup state memory and notify the query object of the failures).
0349  * If LookupState is captured this function must return LLVMErrorSuccess.
0350  *
0351  * The Kind argument can be inspected to determine the lookup kind (e.g.
0352  * as-if-during-static-link, or as-if-during-dlsym).
0353  *
0354  * The JD argument specifies which JITDylib the definitions should be generated
0355  * into.
0356  *
0357  * The JDLookupFlags argument can be inspected to determine whether the original
0358  * lookup included non-exported symbols.
0359  *
0360  * Finally, the LookupSet argument contains the set of symbols that could not
0361  * be found in JD already (the set of generation candidates).
0362  */
0363 typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)(
0364     LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx,
0365     LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind,
0366     LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags,
0367     LLVMOrcCLookupSet LookupSet, size_t LookupSetSize);
0368 
0369 /**
0370  * Disposer for a custom generator.
0371  *
0372  * Will be called by ORC when the JITDylib that the generator is attached to
0373  * is destroyed.
0374  */
0375 typedef void (*LLVMOrcDisposeCAPIDefinitionGeneratorFunction)(void *Ctx);
0376 
0377 /**
0378  * Predicate function for SymbolStringPoolEntries.
0379  */
0380 typedef int (*LLVMOrcSymbolPredicate)(void *Ctx,
0381                                       LLVMOrcSymbolStringPoolEntryRef Sym);
0382 
0383 /**
0384  * A reference to an orc::ThreadSafeContext instance.
0385  */
0386 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
0387 
0388 /**
0389  * A reference to an orc::ThreadSafeModule instance.
0390  */
0391 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
0392 
0393 /**
0394  * A function for inspecting/mutating IR modules, suitable for use with
0395  * LLVMOrcThreadSafeModuleWithModuleDo.
0396  */
0397 typedef LLVMErrorRef (*LLVMOrcGenericIRModuleOperationFunction)(
0398     void *Ctx, LLVMModuleRef M);
0399 
0400 /**
0401  * A reference to an orc::JITTargetMachineBuilder instance.
0402  */
0403 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
0404     *LLVMOrcJITTargetMachineBuilderRef;
0405 
0406 /**
0407  * A reference to an orc::ObjectLayer instance.
0408  */
0409 typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef;
0410 
0411 /**
0412  * A reference to an orc::ObjectLinkingLayer instance.
0413  */
0414 typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef;
0415 
0416 /**
0417  * A reference to an orc::IRTransformLayer instance.
0418  */
0419 typedef struct LLVMOrcOpaqueIRTransformLayer *LLVMOrcIRTransformLayerRef;
0420 
0421 /**
0422  * A function for applying transformations as part of an transform layer.
0423  *
0424  * Implementations of this type are responsible for managing the lifetime
0425  * of the Module pointed to by ModInOut: If the LLVMModuleRef value is
0426  * overwritten then the function is responsible for disposing of the incoming
0427  * module. If the module is simply accessed/mutated in-place then ownership
0428  * returns to the caller and the function does not need to do any lifetime
0429  * management.
0430  *
0431  * Clients can call LLVMOrcLLJITGetIRTransformLayer to obtain the transform
0432  * layer of a LLJIT instance, and use LLVMOrcIRTransformLayerSetTransform
0433  * to set the function. This can be used to override the default transform
0434  * layer.
0435  */
0436 typedef LLVMErrorRef (*LLVMOrcIRTransformLayerTransformFunction)(
0437     void *Ctx, LLVMOrcThreadSafeModuleRef *ModInOut,
0438     LLVMOrcMaterializationResponsibilityRef MR);
0439 
0440 /**
0441  * A reference to an orc::ObjectTransformLayer instance.
0442  */
0443 typedef struct LLVMOrcOpaqueObjectTransformLayer
0444     *LLVMOrcObjectTransformLayerRef;
0445 
0446 /**
0447  * A function for applying transformations to an object file buffer.
0448  *
0449  * Implementations of this type are responsible for managing the lifetime
0450  * of the memory buffer pointed to by ObjInOut: If the LLVMMemoryBufferRef
0451  * value is overwritten then the function is responsible for disposing of the
0452  * incoming buffer. If the buffer is simply accessed/mutated in-place then
0453  * ownership returns to the caller and the function does not need to do any
0454  * lifetime management.
0455  *
0456  * The transform is allowed to return an error, in which case the ObjInOut
0457  * buffer should be disposed of and set to null.
0458  */
0459 typedef LLVMErrorRef (*LLVMOrcObjectTransformLayerTransformFunction)(
0460     void *Ctx, LLVMMemoryBufferRef *ObjInOut);
0461 
0462 /**
0463  * A reference to an orc::IndirectStubsManager instance.
0464  */
0465 typedef struct LLVMOrcOpaqueIndirectStubsManager
0466     *LLVMOrcIndirectStubsManagerRef;
0467 
0468 /**
0469  * A reference to an orc::LazyCallThroughManager instance.
0470  */
0471 typedef struct LLVMOrcOpaqueLazyCallThroughManager
0472     *LLVMOrcLazyCallThroughManagerRef;
0473 
0474 /**
0475  * A reference to an orc::DumpObjects object.
0476  *
0477  * Can be used to dump object files to disk with unique names. Useful as an
0478  * ObjectTransformLayer transform.
0479  */
0480 typedef struct LLVMOrcOpaqueDumpObjects *LLVMOrcDumpObjectsRef;
0481 
0482 /**
0483  * Attach a custom error reporter function to the ExecutionSession.
0484  *
0485  * The error reporter will be called to deliver failure notices that can not be
0486  * directly reported to a caller. For example, failure to resolve symbols in
0487  * the JIT linker is typically reported via the error reporter (callers
0488  * requesting definitions from the JIT will typically be delivered a
0489  * FailureToMaterialize error instead).
0490  */
0491 void LLVMOrcExecutionSessionSetErrorReporter(
0492     LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError,
0493     void *Ctx);
0494 
0495 /**
0496  * Return a reference to the SymbolStringPool for an ExecutionSession.
0497  *
0498  * Ownership of the pool remains with the ExecutionSession: The caller is
0499  * not required to free the pool.
0500  */
0501 LLVMOrcSymbolStringPoolRef
0502 LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES);
0503 
0504 /**
0505  * Clear all unreferenced symbol string pool entries.
0506  *
0507  * This can be called at any time to release unused entries in the
0508  * ExecutionSession's string pool. Since it locks the pool (preventing
0509  * interning of any new strings) it is recommended that it only be called
0510  * infrequently, ideally when the caller has reason to believe that some
0511  * entries will have become unreferenced, e.g. after removing a module or
0512  * closing a JITDylib.
0513  */
0514 void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP);
0515 
0516 /**
0517  * Intern a string in the ExecutionSession's SymbolStringPool and return a
0518  * reference to it. This increments the ref-count of the pool entry, and the
0519  * returned value should be released once the client is done with it by
0520  * calling LLVMOrcReleaseSymbolStringPoolEntry.
0521  *
0522  * Since strings are uniqued within the SymbolStringPool
0523  * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
0524  * equality.
0525  *
0526  * Note that this function does not perform linker-mangling on the string.
0527  */
0528 LLVMOrcSymbolStringPoolEntryRef
0529 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
0530 
0531 /**
0532  * Callback type for ExecutionSession lookups.
0533  *
0534  * If Err is LLVMErrorSuccess then Result will contain a pointer to a
0535  * list of ( SymbolStringPtr, JITEvaluatedSymbol ) pairs of length NumPairs.
0536  *
0537  * If Err is a failure value then Result and Ctx are undefined and should
0538  * not be accessed. The Callback is responsible for handling the error
0539  * value (e.g. by calling LLVMGetErrorMessage + LLVMDisposeErrorMessage).
0540  *
0541  * The caller retains ownership of the Result array and will release all
0542  * contained symbol names. Clients are responsible for retaining any symbol
0543  * names that they wish to hold after the function returns.
0544  */
0545 typedef void (*LLVMOrcExecutionSessionLookupHandleResultFunction)(
0546     LLVMErrorRef Err, LLVMOrcCSymbolMapPairs Result, size_t NumPairs,
0547     void *Ctx);
0548 
0549 /**
0550  * Look up symbols in an execution session.
0551  *
0552  * This is a wrapper around the general ExecutionSession::lookup function.
0553  *
0554  * The SearchOrder argument contains a list of (JITDylibs, JITDylibSearchFlags)
0555  * pairs that describe the search order. The JITDylibs will be searched in the
0556  * given order to try to find the symbols in the Symbols argument.
0557  *
0558  * The Symbols argument should contain a null-terminated array of
0559  * (SymbolStringPtr, SymbolLookupFlags) pairs describing the symbols to be
0560  * searched for. This function takes ownership of the elements of the Symbols
0561  * array. The Name fields of the Symbols elements are taken to have been
0562  * retained by the client for this function. The client should *not* release the
0563  * Name fields, but are still responsible for destroying the array itself.
0564  *
0565  * The HandleResult function will be called once all searched for symbols have
0566  * been found, or an error occurs. The HandleResult function will be passed an
0567  * LLVMErrorRef indicating success or failure, and (on success) a
0568  * null-terminated LLVMOrcCSymbolMapPairs array containing the function result,
0569  * and the Ctx value passed to the lookup function.
0570  *
0571  * The client is fully responsible for managing the lifetime of the Ctx object.
0572  * A common idiom is to allocate the context prior to the lookup and deallocate
0573  * it in the handler.
0574  *
0575  * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
0576  */
0577 void LLVMOrcExecutionSessionLookup(
0578     LLVMOrcExecutionSessionRef ES, LLVMOrcLookupKind K,
0579     LLVMOrcCJITDylibSearchOrder SearchOrder, size_t SearchOrderSize,
0580     LLVMOrcCLookupSet Symbols, size_t SymbolsSize,
0581     LLVMOrcExecutionSessionLookupHandleResultFunction HandleResult, void *Ctx);
0582 
0583 /**
0584  * Increments the ref-count for a SymbolStringPool entry.
0585  */
0586 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
0587 
0588 /**
0589  * Reduces the ref-count for of a SymbolStringPool entry.
0590  */
0591 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
0592 
0593 /**
0594  * Return the c-string for the given symbol. This string will remain valid until
0595  * the entry is freed (once all LLVMOrcSymbolStringPoolEntryRefs have been
0596  * released).
0597  */
0598 const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S);
0599 
0600 /**
0601  * Reduces the ref-count of a ResourceTracker.
0602  */
0603 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT);
0604 
0605 /**
0606  * Transfers tracking of all resources associated with resource tracker SrcRT
0607  * to resource tracker DstRT.
0608  */
0609 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT,
0610                                       LLVMOrcResourceTrackerRef DstRT);
0611 
0612 /**
0613  * Remove all resources associated with the given tracker. See
0614  * ResourceTracker::remove().
0615  */
0616 LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT);
0617 
0618 /**
0619  * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
0620  * ownership has not been passed to a JITDylib (e.g. because some error
0621  * prevented the client from calling LLVMOrcJITDylibAddGenerator).
0622  */
0623 void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG);
0624 
0625 /**
0626  * Dispose of a MaterializationUnit.
0627  */
0628 void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU);
0629 
0630 /**
0631  * Create a custom MaterializationUnit.
0632  *
0633  * Name is a name for this MaterializationUnit to be used for identification
0634  * and logging purposes (e.g. if this MaterializationUnit produces an
0635  * object buffer then the name of that buffer will be derived from this name).
0636  *
0637  * The Syms list contains the names and linkages of the symbols provided by this
0638  * unit. This function takes ownership of the elements of the Syms array. The
0639  * Name fields of the array elements are taken to have been retained for this
0640  * function. The client should *not* release the elements of the array, but is
0641  * still responsible for destroying the array itself.
0642  *
0643  * The InitSym argument indicates whether or not this MaterializationUnit
0644  * contains static initializers. If three are no static initializers (the common
0645  * case) then this argument should be null. If there are static initializers
0646  * then InitSym should be set to a unique name that also appears in the Syms
0647  * list with the LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly flag
0648  * set. This function takes ownership of the InitSym, which should have been
0649  * retained twice on behalf of this function: once for the Syms entry and once
0650  * for InitSym. If clients wish to use the InitSym value after this function
0651  * returns they must retain it once more for themselves.
0652  *
0653  * If any of the symbols in the Syms list is looked up then the Materialize
0654  * function will be called.
0655  *
0656  * If any of the symbols in the Syms list is overridden then the Discard
0657  * function will be called.
0658  *
0659  * The caller owns the underling MaterializationUnit and is responsible for
0660  * either passing it to a JITDylib (via LLVMOrcJITDylibDefine) or disposing
0661  * of it by calling LLVMOrcDisposeMaterializationUnit.
0662  */
0663 LLVMOrcMaterializationUnitRef LLVMOrcCreateCustomMaterializationUnit(
0664     const char *Name, void *Ctx, LLVMOrcCSymbolFlagsMapPairs Syms,
0665     size_t NumSyms, LLVMOrcSymbolStringPoolEntryRef InitSym,
0666     LLVMOrcMaterializationUnitMaterializeFunction Materialize,
0667     LLVMOrcMaterializationUnitDiscardFunction Discard,
0668     LLVMOrcMaterializationUnitDestroyFunction Destroy);
0669 
0670 /**
0671  * Create a MaterializationUnit to define the given symbols as pointing to
0672  * the corresponding raw addresses.
0673  *
0674  * This function takes ownership of the elements of the Syms array. The Name
0675  * fields of the array elements are taken to have been retained for this
0676  * function. This allows the following pattern...
0677  *
0678  *   size_t NumPairs;
0679  *   LLVMOrcCSymbolMapPairs Sym;
0680  *   -- Build Syms array --
0681  *   LLVMOrcMaterializationUnitRef MU =
0682  *       LLVMOrcAbsoluteSymbols(Syms, NumPairs);
0683  *
0684  * ... without requiring cleanup of the elements of the Sym array afterwards.
0685  *
0686  * The client is still responsible for deleting the Sym array itself.
0687  *
0688  * If a client wishes to reuse elements of the Sym array after this call they
0689  * must explicitly retain each of the elements for themselves.
0690  */
0691 LLVMOrcMaterializationUnitRef
0692 LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs);
0693 
0694 /**
0695  * Create a MaterializationUnit to define lazy re-expots. These are callable
0696  * entry points that call through to the given symbols.
0697  *
0698  * This function takes ownership of the CallableAliases array. The Name
0699  * fields of the array elements are taken to have been retained for this
0700  * function. This allows the following pattern...
0701  *
0702  *   size_t NumPairs;
0703  *   LLVMOrcCSymbolAliasMapPairs CallableAliases;
0704  *   -- Build CallableAliases array --
0705  *   LLVMOrcMaterializationUnitRef MU =
0706  *      LLVMOrcLazyReexports(LCTM, ISM, JD, CallableAliases, NumPairs);
0707  *
0708  * ... without requiring cleanup of the elements of the CallableAliases array afterwards.
0709  *
0710  * The client is still responsible for deleting the CallableAliases array itself.
0711  *
0712  * If a client wishes to reuse elements of the CallableAliases array after this call they
0713  * must explicitly retain each of the elements for themselves.
0714  */
0715 LLVMOrcMaterializationUnitRef LLVMOrcLazyReexports(
0716     LLVMOrcLazyCallThroughManagerRef LCTM, LLVMOrcIndirectStubsManagerRef ISM,
0717     LLVMOrcJITDylibRef SourceRef, LLVMOrcCSymbolAliasMapPairs CallableAliases,
0718     size_t NumPairs);
0719 // TODO: ImplSymbolMad SrcJDLoc
0720 
0721 /**
0722  * Disposes of the passed MaterializationResponsibility object.
0723  *
0724  * This should only be done after the symbols covered by the object have either
0725  * been resolved and emitted (via
0726  * LLVMOrcMaterializationResponsibilityNotifyResolved and
0727  * LLVMOrcMaterializationResponsibilityNotifyEmitted) or failed (via
0728  * LLVMOrcMaterializationResponsibilityFailMaterialization).
0729  */
0730 void LLVMOrcDisposeMaterializationResponsibility(
0731     LLVMOrcMaterializationResponsibilityRef MR);
0732 
0733 /**
0734  * Returns the target JITDylib that these symbols are being materialized into.
0735  */
0736 LLVMOrcJITDylibRef LLVMOrcMaterializationResponsibilityGetTargetDylib(
0737     LLVMOrcMaterializationResponsibilityRef MR);
0738 
0739 /**
0740  * Returns the ExecutionSession for this MaterializationResponsibility.
0741  */
0742 LLVMOrcExecutionSessionRef
0743 LLVMOrcMaterializationResponsibilityGetExecutionSession(
0744     LLVMOrcMaterializationResponsibilityRef MR);
0745 
0746 /**
0747  * Returns the symbol flags map for this responsibility instance.
0748  *
0749  * The length of the array is returned in NumPairs and the caller is responsible
0750  * for the returned memory and needs to call LLVMOrcDisposeCSymbolFlagsMap.
0751  *
0752  * To use the returned symbols beyond the livetime of the
0753  * MaterializationResponsibility requires the caller to retain the symbols
0754  * explicitly.
0755  */
0756 LLVMOrcCSymbolFlagsMapPairs LLVMOrcMaterializationResponsibilityGetSymbols(
0757     LLVMOrcMaterializationResponsibilityRef MR, size_t *NumPairs);
0758 
0759 /**
0760  * Disposes of the passed LLVMOrcCSymbolFlagsMap.
0761  *
0762  * Does not release the entries themselves.
0763  */
0764 void LLVMOrcDisposeCSymbolFlagsMap(LLVMOrcCSymbolFlagsMapPairs Pairs);
0765 
0766 /**
0767  * Returns the initialization pseudo-symbol, if any. This symbol will also
0768  * be present in the SymbolFlagsMap for this MaterializationResponsibility
0769  * object.
0770  *
0771  * The returned symbol is not retained over any mutating operation of the
0772  * MaterializationResponsbility or beyond the lifetime thereof.
0773  */
0774 LLVMOrcSymbolStringPoolEntryRef
0775 LLVMOrcMaterializationResponsibilityGetInitializerSymbol(
0776     LLVMOrcMaterializationResponsibilityRef MR);
0777 
0778 /**
0779  * Returns the names of any symbols covered by this
0780  * MaterializationResponsibility object that have queries pending. This
0781  * information can be used to return responsibility for unrequested symbols
0782  * back to the JITDylib via the delegate method.
0783  */
0784 LLVMOrcSymbolStringPoolEntryRef *
0785 LLVMOrcMaterializationResponsibilityGetRequestedSymbols(
0786     LLVMOrcMaterializationResponsibilityRef MR, size_t *NumSymbols);
0787 
0788 /**
0789  * Disposes of the passed LLVMOrcSymbolStringPoolEntryRef* .
0790  *
0791  * Does not release the symbols themselves.
0792  */
0793 void LLVMOrcDisposeSymbols(LLVMOrcSymbolStringPoolEntryRef *Symbols);
0794 
0795 /**
0796  * Notifies the target JITDylib that the given symbols have been resolved.
0797  * This will update the given symbols' addresses in the JITDylib, and notify
0798  * any pending queries on the given symbols of their resolution. The given
0799  * symbols must be ones covered by this MaterializationResponsibility
0800  * instance. Individual calls to this method may resolve a subset of the
0801  * symbols, but all symbols must have been resolved prior to calling emit.
0802  *
0803  * This method will return an error if any symbols being resolved have been
0804  * moved to the error state due to the failure of a dependency. If this
0805  * method returns an error then clients should log it and call
0806  * LLVMOrcMaterializationResponsibilityFailMaterialization. If no dependencies
0807  * have been registered for the symbols covered by this
0808  * MaterializationResponsibility then this method is guaranteed to return
0809  * LLVMErrorSuccess.
0810  */
0811 LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyResolved(
0812     LLVMOrcMaterializationResponsibilityRef MR, LLVMOrcCSymbolMapPairs Symbols,
0813     size_t NumPairs);
0814 
0815 /**
0816  * Notifies the target JITDylib (and any pending queries on that JITDylib)
0817  * that all symbols covered by this MaterializationResponsibility instance
0818  * have been emitted.
0819  *
0820  * This function takes ownership of the symbols in the Dependencies struct.
0821  * This allows the following pattern...
0822  *
0823  *   LLVMOrcSymbolStringPoolEntryRef Names[] = {...};
0824  *   LLVMOrcCDependenceMapPair Dependence = {JD, {Names, sizeof(Names)}}
0825  *   LLVMOrcMaterializationResponsibilityAddDependencies(JD, Name, &Dependence,
0826  * 1);
0827  *
0828  * ... without requiring cleanup of the elements of the Names array afterwards.
0829  *
0830  * The client is still responsible for deleting the Dependencies.Names arrays,
0831  * and the Dependencies array itself.
0832  *
0833  * This method will return an error if any symbols being resolved have been
0834  * moved to the error state due to the failure of a dependency. If this
0835  * method returns an error then clients should log it and call
0836  * LLVMOrcMaterializationResponsibilityFailMaterialization.
0837  * If no dependencies have been registered for the symbols covered by this
0838  * MaterializationResponsibility then this method is guaranteed to return
0839  * LLVMErrorSuccess.
0840  */
0841 LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyEmitted(
0842     LLVMOrcMaterializationResponsibilityRef MR,
0843     LLVMOrcCSymbolDependenceGroup *SymbolDepGroups, size_t NumSymbolDepGroups);
0844 
0845 /**
0846  * Attempt to claim responsibility for new definitions. This method can be
0847  * used to claim responsibility for symbols that are added to a
0848  * materialization unit during the compilation process (e.g. literal pool
0849  * symbols). Symbol linkage rules are the same as for symbols that are
0850  * defined up front: duplicate strong definitions will result in errors.
0851  * Duplicate weak definitions will be discarded (in which case they will
0852  * not be added to this responsibility instance).
0853  *
0854  * This method can be used by materialization units that want to add
0855  * additional symbols at materialization time (e.g. stubs, compile
0856  * callbacks, metadata)
0857  */
0858 LLVMErrorRef LLVMOrcMaterializationResponsibilityDefineMaterializing(
0859     LLVMOrcMaterializationResponsibilityRef MR,
0860     LLVMOrcCSymbolFlagsMapPairs Pairs, size_t NumPairs);
0861 
0862 /**
0863  * Notify all not-yet-emitted covered by this MaterializationResponsibility
0864  * instance that an error has occurred.
0865  * This will remove all symbols covered by this MaterializationResponsibility
0866  * from the target JITDylib, and send an error to any queries waiting on
0867  * these symbols.
0868  */
0869 void LLVMOrcMaterializationResponsibilityFailMaterialization(
0870     LLVMOrcMaterializationResponsibilityRef MR);
0871 
0872 /**
0873  * Transfers responsibility to the given MaterializationUnit for all
0874  * symbols defined by that MaterializationUnit. This allows
0875  * materializers to break up work based on run-time information (e.g.
0876  * by introspecting which symbols have actually been looked up and
0877  * materializing only those).
0878  */
0879 LLVMErrorRef LLVMOrcMaterializationResponsibilityReplace(
0880     LLVMOrcMaterializationResponsibilityRef MR,
0881     LLVMOrcMaterializationUnitRef MU);
0882 
0883 /**
0884  * Delegates responsibility for the given symbols to the returned
0885  * materialization responsibility. Useful for breaking up work between
0886  * threads, or different kinds of materialization processes.
0887  *
0888  * The caller retains responsibility of the the passed
0889  * MaterializationResponsibility.
0890  */
0891 LLVMErrorRef LLVMOrcMaterializationResponsibilityDelegate(
0892     LLVMOrcMaterializationResponsibilityRef MR,
0893     LLVMOrcSymbolStringPoolEntryRef *Symbols, size_t NumSymbols,
0894     LLVMOrcMaterializationResponsibilityRef *Result);
0895 
0896 /**
0897  * Create a "bare" JITDylib.
0898  *
0899  * The client is responsible for ensuring that the JITDylib's name is unique,
0900  * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
0901  *
0902  * This call does not install any library code or symbols into the newly
0903  * created JITDylib. The client is responsible for all configuration.
0904  */
0905 LLVMOrcJITDylibRef
0906 LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES,
0907                                           const char *Name);
0908 
0909 /**
0910  * Create a JITDylib.
0911  *
0912  * The client is responsible for ensuring that the JITDylib's name is unique,
0913  * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
0914  *
0915  * If a Platform is attached to the ExecutionSession then
0916  * Platform::setupJITDylib will be called to install standard platform symbols
0917  * (e.g. standard library interposes). If no Platform is installed then this
0918  * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will
0919  * always return success.
0920  */
0921 LLVMErrorRef
0922 LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES,
0923                                       LLVMOrcJITDylibRef *Result,
0924                                       const char *Name);
0925 
0926 /**
0927  * Returns the JITDylib with the given name, or NULL if no such JITDylib
0928  * exists.
0929  */
0930 LLVMOrcJITDylibRef
0931 LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES,
0932                                          const char *Name);
0933 
0934 /**
0935  * Return a reference to a newly created resource tracker associated with JD.
0936  * The tracker is returned with an initial ref-count of 1, and must be released
0937  * with LLVMOrcReleaseResourceTracker when no longer needed.
0938  */
0939 LLVMOrcResourceTrackerRef
0940 LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD);
0941 
0942 /**
0943  * Return a reference to the default resource tracker for the given JITDylib.
0944  * This operation will increase the retain count of the tracker: Clients should
0945  * call LLVMOrcReleaseResourceTracker when the result is no longer needed.
0946  */
0947 LLVMOrcResourceTrackerRef
0948 LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD);
0949 
0950 /**
0951  * Add the given MaterializationUnit to the given JITDylib.
0952  *
0953  * If this operation succeeds then JITDylib JD will take ownership of MU.
0954  * If the operation fails then ownership remains with the caller who should
0955  * call LLVMOrcDisposeMaterializationUnit to destroy it.
0956  */
0957 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD,
0958                                    LLVMOrcMaterializationUnitRef MU);
0959 
0960 /**
0961  * Calls remove on all trackers associated with this JITDylib, see
0962  * JITDylib::clear().
0963  */
0964 LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD);
0965 
0966 /**
0967  * Add a DefinitionGenerator to the given JITDylib.
0968  *
0969  * The JITDylib will take ownership of the given generator: The client is no
0970  * longer responsible for managing its memory.
0971  */
0972 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
0973                                  LLVMOrcDefinitionGeneratorRef DG);
0974 
0975 /**
0976  * Create a custom generator.
0977  *
0978  * The F argument will be used to implement the DefinitionGenerator's
0979  * tryToGenerate method (see
0980  * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction).
0981  *
0982  * Ctx is a context object that will be passed to F. This argument is
0983  * permitted to be null.
0984  *
0985  * Dispose is the disposal function for Ctx. This argument is permitted to be
0986  * null (in which case the client is responsible for the lifetime of Ctx).
0987  */
0988 LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator(
0989     LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx,
0990     LLVMOrcDisposeCAPIDefinitionGeneratorFunction Dispose);
0991 
0992 /**
0993  * Continue a lookup that was suspended in a generator (see
0994  * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction).
0995  */
0996 void LLVMOrcLookupStateContinueLookup(LLVMOrcLookupStateRef S,
0997                                       LLVMErrorRef Err);
0998 
0999 /**
1000  * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
1001  * the JITDylib. On success the resulting generator is owned by the client.
1002  * Ownership is typically transferred by adding the instance to a JITDylib
1003  * using LLVMOrcJITDylibAddGenerator,
1004  *
1005  * The GlobalPrefix argument specifies the character that appears on the front
1006  * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
1007  * If non-null, this character will be stripped from the start of all symbol
1008  * strings before passing the remaining substring to dlsym.
1009  *
1010  * The optional Filter and Ctx arguments can be used to supply a symbol name
1011  * filter: Only symbols for which the filter returns true will be visible to
1012  * JIT'd code. If the Filter argument is null then all process symbols will
1013  * be visible to JIT'd code. Note that the symbol name passed to the Filter
1014  * function is the full mangled symbol: The client is responsible for stripping
1015  * the global prefix if present.
1016  */
1017 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
1018     LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx,
1019     LLVMOrcSymbolPredicate Filter, void *FilterCtx);
1020 
1021 /**
1022  * Get a LLVMOrcCreateDynamicLibararySearchGeneratorForPath that will reflect
1023  * library symbols into the JITDylib. On success the resulting generator is
1024  * owned by the client. Ownership is typically transferred by adding the
1025  * instance to a JITDylib using LLVMOrcJITDylibAddGenerator,
1026  *
1027  * The GlobalPrefix argument specifies the character that appears on the front
1028  * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
1029  * If non-null, this character will be stripped from the start of all symbol
1030  * strings before passing the remaining substring to dlsym.
1031  *
1032  * The optional Filter and Ctx arguments can be used to supply a symbol name
1033  * filter: Only symbols for which the filter returns true will be visible to
1034  * JIT'd code. If the Filter argument is null then all library symbols will
1035  * be visible to JIT'd code. Note that the symbol name passed to the Filter
1036  * function is the full mangled symbol: The client is responsible for stripping
1037  * the global prefix if present.
1038  * 
1039  * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
1040  * 
1041  */
1042 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForPath(
1043     LLVMOrcDefinitionGeneratorRef *Result, const char *FileName,
1044     char GlobalPrefix, LLVMOrcSymbolPredicate Filter, void *FilterCtx);
1045 
1046 /**
1047  * Get a LLVMOrcCreateStaticLibrarySearchGeneratorForPath that will reflect
1048  * static library symbols into the JITDylib. On success the resulting
1049  * generator is owned by the client. Ownership is typically transferred by
1050  * adding the instance to a JITDylib using LLVMOrcJITDylibAddGenerator,
1051  *
1052  * Call with the optional TargetTriple argument will succeed if the file at
1053  * the given path is a static library or a MachO universal binary containing a
1054  * static library that is compatible with the given triple. Otherwise it will
1055  * return an error.
1056  *
1057  * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
1058  * 
1059  */
1060 LLVMErrorRef LLVMOrcCreateStaticLibrarySearchGeneratorForPath(
1061     LLVMOrcDefinitionGeneratorRef *Result, LLVMOrcObjectLayerRef ObjLayer,
1062     const char *FileName, const char *TargetTriple);
1063 
1064 /**
1065  * Create a ThreadSafeContext containing a new LLVMContext.
1066  *
1067  * Ownership of the underlying ThreadSafeContext data is shared: Clients
1068  * can and should dispose of their ThreadSafeContext as soon as they no longer
1069  * need to refer to it directly. Other references (e.g. from ThreadSafeModules)
1070  * will keep the data alive as long as it is needed.
1071  */
1072 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
1073 
1074 /**
1075  * Get a reference to the wrapped LLVMContext.
1076  */
1077 LLVMContextRef
1078 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);
1079 
1080 /**
1081  * Dispose of a ThreadSafeContext.
1082  */
1083 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
1084 
1085 /**
1086  * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
1087  * ownership of the M argument which should not be disposed of or referenced
1088  * after this function returns.
1089  *
1090  * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
1091  * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer
1092  * responsible for it. If it is not transferred to the JIT then the client
1093  * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
1094  */
1095 LLVMOrcThreadSafeModuleRef
1096 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
1097                                  LLVMOrcThreadSafeContextRef TSCtx);
1098 
1099 /**
1100  * Dispose of a ThreadSafeModule. This should only be called if ownership has
1101  * not been passed to LLJIT (e.g. because some error prevented the client from
1102  * adding this to the JIT).
1103  */
1104 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
1105 
1106 /**
1107  * Apply the given function to the module contained in this ThreadSafeModule.
1108  */
1109 LLVMErrorRef
1110 LLVMOrcThreadSafeModuleWithModuleDo(LLVMOrcThreadSafeModuleRef TSM,
1111                                     LLVMOrcGenericIRModuleOperationFunction F,
1112                                     void *Ctx);
1113 
1114 /**
1115  * Create a JITTargetMachineBuilder by detecting the host.
1116  *
1117  * On success the client owns the resulting JITTargetMachineBuilder. It must be
1118  * passed to a consuming operation (e.g.
1119  * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
1120  * LLVMOrcDisposeJITTargetMachineBuilder.
1121  */
1122 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
1123     LLVMOrcJITTargetMachineBuilderRef *Result);
1124 
1125 /**
1126  * Create a JITTargetMachineBuilder from the given TargetMachine template.
1127  *
1128  * This operation takes ownership of the given TargetMachine and destroys it
1129  * before returing. The resulting JITTargetMachineBuilder is owned by the client
1130  * and must be passed to a consuming operation (e.g.
1131  * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
1132  * LLVMOrcDisposeJITTargetMachineBuilder.
1133  */
1134 LLVMOrcJITTargetMachineBuilderRef
1135 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
1136 
1137 /**
1138  * Dispose of a JITTargetMachineBuilder.
1139  */
1140 void LLVMOrcDisposeJITTargetMachineBuilder(
1141     LLVMOrcJITTargetMachineBuilderRef JTMB);
1142 
1143 /**
1144  * Returns the target triple for the given JITTargetMachineBuilder as a string.
1145  *
1146  * The caller owns the resulting string as must dispose of it by calling
1147  * LLVMDisposeMessage
1148  */
1149 char *LLVMOrcJITTargetMachineBuilderGetTargetTriple(
1150     LLVMOrcJITTargetMachineBuilderRef JTMB);
1151 
1152 /**
1153  * Sets the target triple for the given JITTargetMachineBuilder to the given
1154  * string.
1155  */
1156 void LLVMOrcJITTargetMachineBuilderSetTargetTriple(
1157     LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple);
1158 
1159 /**
1160  * Add an object to an ObjectLayer to the given JITDylib.
1161  *
1162  * Adds a buffer representing an object file to the given JITDylib using the
1163  * given ObjectLayer instance. This operation transfers ownership of the buffer
1164  * to the ObjectLayer instance. The buffer should not be disposed of or
1165  * referenced once this function returns.
1166  *
1167  * Resources associated with the given object will be tracked by the given
1168  * JITDylib's default ResourceTracker.
1169  */
1170 LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer,
1171                                              LLVMOrcJITDylibRef JD,
1172                                              LLVMMemoryBufferRef ObjBuffer);
1173 
1174 /**
1175  * Add an object to an ObjectLayer using the given ResourceTracker.
1176  *
1177  * Adds a buffer representing an object file to the given ResourceTracker's
1178  * JITDylib using the given ObjectLayer instance. This operation transfers
1179  * ownership of the buffer to the ObjectLayer instance. The buffer should not
1180  * be disposed of or referenced once this function returns.
1181  *
1182  * Resources associated with the given object will be tracked by
1183  * ResourceTracker RT.
1184  */
1185 LLVMErrorRef
1186 LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer,
1187                                       LLVMOrcResourceTrackerRef RT,
1188                                       LLVMMemoryBufferRef ObjBuffer);
1189 
1190 /**
1191  * Emit an object buffer to an ObjectLayer.
1192  *
1193  * Ownership of the responsibility object and object buffer pass to this
1194  * function. The client is not responsible for cleanup.
1195  */
1196 void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer,
1197                             LLVMOrcMaterializationResponsibilityRef R,
1198                             LLVMMemoryBufferRef ObjBuffer);
1199 
1200 /**
1201  * Dispose of an ObjectLayer.
1202  */
1203 void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer);
1204 
1205 void LLVMOrcIRTransformLayerEmit(LLVMOrcIRTransformLayerRef IRTransformLayer,
1206                                  LLVMOrcMaterializationResponsibilityRef MR,
1207                                  LLVMOrcThreadSafeModuleRef TSM);
1208 
1209 /**
1210  * Set the transform function of the provided transform layer, passing through a
1211  * pointer to user provided context.
1212  */
1213 void LLVMOrcIRTransformLayerSetTransform(
1214     LLVMOrcIRTransformLayerRef IRTransformLayer,
1215     LLVMOrcIRTransformLayerTransformFunction TransformFunction, void *Ctx);
1216 
1217 /**
1218  * Set the transform function on an LLVMOrcObjectTransformLayer.
1219  */
1220 void LLVMOrcObjectTransformLayerSetTransform(
1221     LLVMOrcObjectTransformLayerRef ObjTransformLayer,
1222     LLVMOrcObjectTransformLayerTransformFunction TransformFunction, void *Ctx);
1223 
1224 /**
1225  * Create a LocalIndirectStubsManager from the given target triple.
1226  *
1227  * The resulting IndirectStubsManager is owned by the client
1228  * and must be disposed of by calling LLVMOrcDisposeDisposeIndirectStubsManager.
1229  */
1230 LLVMOrcIndirectStubsManagerRef
1231 LLVMOrcCreateLocalIndirectStubsManager(const char *TargetTriple);
1232 
1233 /**
1234  * Dispose of an IndirectStubsManager.
1235  */
1236 void LLVMOrcDisposeIndirectStubsManager(LLVMOrcIndirectStubsManagerRef ISM);
1237 
1238 LLVMErrorRef LLVMOrcCreateLocalLazyCallThroughManager(
1239     const char *TargetTriple, LLVMOrcExecutionSessionRef ES,
1240     LLVMOrcJITTargetAddress ErrorHandlerAddr,
1241     LLVMOrcLazyCallThroughManagerRef *LCTM);
1242 
1243 /**
1244  * Dispose of an LazyCallThroughManager.
1245  */
1246 void LLVMOrcDisposeLazyCallThroughManager(
1247     LLVMOrcLazyCallThroughManagerRef LCTM);
1248 
1249 /**
1250  * Create a DumpObjects instance.
1251  *
1252  * DumpDir specifies the path to write dumped objects to. DumpDir may be empty
1253  * in which case files will be dumped to the working directory.
1254  *
1255  * IdentifierOverride specifies a file name stem to use when dumping objects.
1256  * If empty then each MemoryBuffer's identifier will be used (with a .o suffix
1257  * added if not already present). If an identifier override is supplied it will
1258  * be used instead, along with an incrementing counter (since all buffers will
1259  * use the same identifier, the resulting files will be named <ident>.o,
1260  * <ident>.2.o, <ident>.3.o, and so on). IdentifierOverride should not contain
1261  * an extension, as a .o suffix will be added by DumpObjects.
1262  */
1263 LLVMOrcDumpObjectsRef LLVMOrcCreateDumpObjects(const char *DumpDir,
1264                                                const char *IdentifierOverride);
1265 
1266 /**
1267  * Dispose of a DumpObjects instance.
1268  */
1269 void LLVMOrcDisposeDumpObjects(LLVMOrcDumpObjectsRef DumpObjects);
1270 
1271 /**
1272  * Dump the contents of the given MemoryBuffer.
1273  */
1274 LLVMErrorRef LLVMOrcDumpObjects_CallOperator(LLVMOrcDumpObjectsRef DumpObjects,
1275                                              LLVMMemoryBufferRef *ObjBuffer);
1276 
1277 /**
1278  * @}
1279  */
1280 
1281 LLVM_C_EXTERN_C_END
1282 
1283 #endif /* LLVM_C_ORC_H */