include/llvm-c/OrcEE.h

0001 /*===-- llvm-c/OrcEE.h - OrcV2 C bindings ExecutionEngine utils -*- 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 ExecutionEngine based utils, e.g.  *|
0011 |* RTDyldObjectLinkingLayer (based on RuntimeDyld) in Orc.                    *|
0012 |*                                                                            *|
0013 |* Many exotic languages can interoperate with C code but have a harder time  *|
0014 |* with C++ due to name mangling. So in addition to C, this interface enables *|
0015 |* tools written in such languages.                                           *|
0016 |*                                                                            *|
0017 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
0018 |*       changed without warning. Only C API usage documentation is           *|
0019 |*       provided. See the C++ documentation for all higher level ORC API     *|
0020 |*       details.                                                             *|
0021 |*                                                                            *|
0022 \*===----------------------------------------------------------------------===*/
0023
0024 #ifndef LLVM_C_ORCEE_H
0025 #define LLVM_C_ORCEE_H
0026
0027 #include "llvm-c/Error.h"
0028 #include "llvm-c/ExecutionEngine.h"
0029 #include "llvm-c/Orc.h"
0030 #include "llvm-c/TargetMachine.h"
0031 #include "llvm-c/Types.h"
0032
0033 LLVM_C_EXTERN_C_BEGIN
0034
0035 typedef void *(*LLVMMemoryManagerCreateContextCallback)(void *CtxCtx);
0036 typedef void (*LLVMMemoryManagerNotifyTerminatingCallback)(void *CtxCtx);
0037
0038 /**
0039  * @defgroup LLVMCExecutionEngineORCEE ExecutionEngine-based ORC Utils
0040  * @ingroup LLVMCExecutionEngine
0041  *
0042  * @{
0043  */
0044
0045 /**
0046  * Create a RTDyldObjectLinkingLayer instance using the standard
0047  * SectionMemoryManager for memory management.
0048  */
0049 LLVMOrcObjectLayerRef
0050 LLVMOrcCreateRTDyldObjectLinkingLayerWithSectionMemoryManager(
0051     LLVMOrcExecutionSessionRef ES);
0052
0053 /**
0054  * Create a RTDyldObjectLinkingLayer instance using MCJIT-memory-manager-like
0055  * callbacks.
0056  *
0057  * This is intended to simplify transitions for existing MCJIT clients. The
0058  * callbacks used are similar (but not identical) to the callbacks for
0059  * LLVMCreateSimpleMCJITMemoryManager: Unlike MCJIT, RTDyldObjectLinkingLayer
0060  * will create a new memory manager for each object linked by calling the given
0061  * CreateContext callback. This allows for code removal by destroying each
0062  * allocator individually. Every allocator will be destroyed (if it has not been
0063  * already) at RTDyldObjectLinkingLayer destruction time, and the
0064  * NotifyTerminating callback will be called to indicate that no further
0065  * allocation contexts will be created.
0066  *
0067  * To implement MCJIT-like behavior clients can implement CreateContext,
0068  * NotifyTerminating, and Destroy as:
0069  *
0070  *   void *CreateContext(void *CtxCtx) { return CtxCtx; }
0071  *   void NotifyTerminating(void *CtxCtx) { MyOriginalDestroy(CtxCtx); }
0072  *   void Destroy(void *Ctx) { }
0073  *
0074  * This scheme simply reuses the CreateContextCtx pointer as the one-and-only
0075  * allocation context.
0076  */
0077 LLVMOrcObjectLayerRef
0078 LLVMOrcCreateRTDyldObjectLinkingLayerWithMCJITMemoryManagerLikeCallbacks(
0079     LLVMOrcExecutionSessionRef ES, void *CreateContextCtx,
0080     LLVMMemoryManagerCreateContextCallback CreateContext,
0081     LLVMMemoryManagerNotifyTerminatingCallback NotifyTerminating,
0082     LLVMMemoryManagerAllocateCodeSectionCallback AllocateCodeSection,
0083     LLVMMemoryManagerAllocateDataSectionCallback AllocateDataSection,
0084     LLVMMemoryManagerFinalizeMemoryCallback FinalizeMemory,
0085     LLVMMemoryManagerDestroyCallback Destroy);
0086
0087 /**
0088  * Add the given listener to the given RTDyldObjectLinkingLayer.
0089  *
0090  * Note: Layer must be an RTDyldObjectLinkingLayer instance or
0091  * behavior is undefined.
0092  */
0093 void LLVMOrcRTDyldObjectLinkingLayerRegisterJITEventListener(
0094     LLVMOrcObjectLayerRef RTDyldObjLinkingLayer,
0095     LLVMJITEventListenerRef Listener);
0096
0097 /**
0098  * @}
0099  */
0100
0101 LLVM_C_EXTERN_C_END
0102
0103 #endif /* LLVM_C_ORCEE_H */