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