llvm/include/llvm-c/OrcEE.h

   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
  33 LLVM_C_EXTERN_C_BEGIN
  34
  35 typedef void *(*LLVMMemoryManagerCreateContextCallback)(void *CtxCtx);
  36 typedef 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  */
  49 LLVMOrcObjectLayerRef
  50 LLVMOrcCreateRTDyldObjectLinkingLayerWithSectionMemoryManager(
  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  */
  77 LLVMOrcObjectLayerRef
  78 LLVMOrcCreateRTDyldObjectLinkingLayerWithMCJITMemoryManagerLikeCallbacks(
  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  */
  93 void LLVMOrcRTDyldObjectLinkingLayerRegisterJITEventListener(
  94     LLVMOrcObjectLayerRef RTDyldObjLinkingLayer,
  95     LLVMJITEventListenerRef Listener);
  96
  97 /**
  98  * @}
  99  */
 100
 101 LLVM_C_EXTERN_C_END
 102
 103 #endif /* LLVM_C_ORCEE_H */