1/*===-- llvm-c/OrcEE.h - OrcV2 C bindings ExecutionEngine utils -*- 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 ExecutionEngine based utils, e.g. *|
11|* RTDyldObjectLinkingLayer (based on RuntimeDyld) in Orc. *|
12|* *|
13|* Many exotic languages can interoperate with C code but have a harder time *|
14|* with C++ due to name mangling. So in addition to C, this interface enables *|
15|* tools written in such languages. *|
16|* *|
17|* Note: This interface is experimental. It is *NOT* stable, and may be *|
18|* changed without warning. Only C API usage documentation is *|
19|* provided. See the C++ documentation for all higher level ORC API *|
20|* details. *|
21|* *|
22\*===----------------------------------------------------------------------===*/
23
24#ifndef LLVM_C_ORCEE_H
25#define LLVM_C_ORCEE_H
26
27#include "llvm-c/Error.h"
28#include "llvm-c/ExecutionEngine.h"
29#include "llvm-c/Orc.h"
30#include "llvm-c/TargetMachine.h"
31#include "llvm-c/Types.h"
32
33LLVM_C_EXTERN_C_BEGIN
34
35typedef void *(*LLVMMemoryManagerCreateContextCallback)(void *CtxCtx);
36typedef void (*LLVMMemoryManagerNotifyTerminatingCallback)(void *CtxCtx);
37
38/**
39 * @defgroup LLVMCExecutionEngineORCEE ExecutionEngine-based ORC Utils
40 * @ingroup LLVMCExecutionEngine
41 *
42 * @{
43 */
44
45/**
46 * Create a RTDyldObjectLinkingLayer instance using the standard
47 * SectionMemoryManager for memory management.
48 */
49LLVMOrcObjectLayerRef
50LLVMOrcCreateRTDyldObjectLinkingLayerWithSectionMemoryManager(
51 LLVMOrcExecutionSessionRef ES);
52
53/**
54 * Create a RTDyldObjectLinkingLayer instance using MCJIT-memory-manager-like
55 * callbacks.
56 *
57 * This is intended to simplify transitions for existing MCJIT clients. The
58 * callbacks used are similar (but not identical) to the callbacks for
59 * LLVMCreateSimpleMCJITMemoryManager: Unlike MCJIT, RTDyldObjectLinkingLayer
60 * will create a new memory manager for each object linked by calling the given
61 * CreateContext callback. This allows for code removal by destroying each
62 * allocator individually. Every allocator will be destroyed (if it has not been
63 * already) at RTDyldObjectLinkingLayer destruction time, and the
64 * NotifyTerminating callback will be called to indicate that no further
65 * allocation contexts will be created.
66 *
67 * To implement MCJIT-like behavior clients can implement CreateContext,
68 * NotifyTerminating, and Destroy as:
69 *
70 * void *CreateContext(void *CtxCtx) { return CtxCtx; }
71 * void NotifyTerminating(void *CtxCtx) { MyOriginalDestroy(CtxCtx); }
72 * void Destroy(void *Ctx) { }
73 *
74 * This scheme simply reuses the CreateContextCtx pointer as the one-and-only
75 * allocation context.
76 */
77LLVMOrcObjectLayerRef
78LLVMOrcCreateRTDyldObjectLinkingLayerWithMCJITMemoryManagerLikeCallbacks(
79 LLVMOrcExecutionSessionRef ES, void *CreateContextCtx,
80 LLVMMemoryManagerCreateContextCallback CreateContext,
81 LLVMMemoryManagerNotifyTerminatingCallback NotifyTerminating,
82 LLVMMemoryManagerAllocateCodeSectionCallback AllocateCodeSection,
83 LLVMMemoryManagerAllocateDataSectionCallback AllocateDataSection,
84 LLVMMemoryManagerFinalizeMemoryCallback FinalizeMemory,
85 LLVMMemoryManagerDestroyCallback Destroy);
86
87/**
88 * Add the given listener to the given RTDyldObjectLinkingLayer.
89 *
90 * Note: Layer must be an RTDyldObjectLinkingLayer instance or
91 * behavior is undefined.
92 */
93void LLVMOrcRTDyldObjectLinkingLayerRegisterJITEventListener(
94 LLVMOrcObjectLayerRef RTDyldObjLinkingLayer,
95 LLVMJITEventListenerRef Listener);
96
97/**
98 * @}
99 */
100
101LLVM_C_EXTERN_C_END
102
103#endif /* LLVM_C_ORCEE_H */
104