Support Out-Of-Process JIT (#717)

* Implement Out-Of-Process JIT for CppInterOp

* Backport LLVM clang-repl's out-of-process JIT patches for clang 20

* Update `StreamCaptureInfo` to work with out-of-process JIT
    In out-of-process JIT, stream capture does not work out of the box.
    Therefore, at the time of creation of the JIT process, we customise it to redirect `stdout` and `stderr` to specific temporary files.
    The parent process creates these files and has a reference to them.
    The parent process can now dynamically read the contents of these temporary files, replicating the stream redirection.
    Note that `stdin` needs special care and does not work as expected right now.
    Ideally, the child process should just redirect to the parent process's streams, but this could not be implemented.

* Update Documentation
    Add build instructions for out-of-process JIT.

* Update tests to use Parameterised Test fixtures
    This enables reusing the existing tests without duplication for in-process and out-of-process JIT.
    Introduces multiple test configurations (InProcess & OutOfProcess right now), that can be used to customise the creation of the interpreter in the test suite.

* Add valgrind suppression file for out-of-process JIT
    These suppressions are from LLVM. Needs to be fixed upstream.

---------

Co-authored-by: kr-2003 <[email protected]>
Co-authored-by: Vipul Cariappa <[email protected]>

Author: 3 people

.github/actions/Build_LLVM/action.yml

@@ -43,6 +43,10 @@ runs:
           ninja LLVMOrcDebugging -j ${{ env.ncpus }}
           ninja clingInterpreter -j ${{ env.ncpus }}
         else
+          if [[ "${{ matrix.oop-jit }}" == "On" ]]; then
+            git apply -v ../patches/llvm/clang20-1-out-of-process.patch
+            echo "Apply clang20-1-out-of-process.patch:"
+          fi
           cd build
           cmake -DLLVM_ENABLE_PROJECTS="${{ matrix.llvm_enable_projects}}" \
                 -DLLVM_TARGETS_TO_BUILD="${{ matrix.llvm_targets_to_build }}"  \
@@ -57,7 +61,15 @@ runs:
                 -DLLVM_INCLUDE_EXAMPLES=OFF                     \
                 -DLLVM_INCLUDE_TESTS=OFF                        \
                 ../llvm
-          ninja clang clangInterpreter clangStaticAnalyzerCore -j ${{ env.ncpus }}
+          ninja clang clangInterpreter clangStaticAnalyzerCore
+          if [[ "${{ matrix.oop-jit }}" == "On" ]]; then
+            if [[ "${{ matrix.os }}" == macos* ]]; then
+              SUFFIX="_osx"
+            elif [[ "${{ matrix.os }}" == ubuntu* ]]; then
+              SUFFIX="-x86_64"
+            fi
+            ninja llvm-jitlink-executor orc_rt${SUFFIX} -j ${{ env.ncpus }}       
+          fi
           cd ./tools/
           rm -rf $(find . -maxdepth 1 ! -name "clang" ! -name ".")
           cd ..

.github/actions/Build_and_Test_CppInterOp/action.yml

@@ -48,6 +48,7 @@ runs:
                 -DCODE_COVERAGE=${{ env.CODE_COVERAGE }}     \
                 -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR       \
                 -DLLVM_ENABLE_WERROR=On                      \
+                -DLLVM_BUILT_WITH_OOP_JIT=${{ matrix.oop-jit }} \
                 ../
         fi
         docs_on=$(echo "${{ matrix.documentation }}" | tr '[:lower:]' '[:upper:]')
@@ -58,7 +59,18 @@ runs:
           cmake --build . --target check-cppinterop --parallel ${{ env.ncpus }}
           os="${{ matrix.os }}"
           if [[ "${os}" != "macos"* ]]; then
-            valgrind --show-error-list=yes --track-origins=yes --error-exitcode=1 unittests/CppInterOp/CppInterOpTests/unittests/bin/${{ env.BUILD_TYPE }}/CppInterOpTests
+            CLANG_VERSION="${{ matrix.clang-runtime }}"
+            if [[ "$CLANG_VERSION" == "20" && "${{ matrix.cling }}" == "Off" ]]; then
+              SUPPRESSION_FILE="../etc/clang${CLANG_VERSION}-valgrind.supp"
+              valgrind --show-error-list=yes --track-origins=yes --error-exitcode=1 \
+                --show-leak-kinds=definite,possible \
+                --suppressions="${SUPPRESSION_FILE}" \
+                unittests/CppInterOp/CppInterOpTests/unittests/bin/${{ env.BUILD_TYPE }}/CppInterOpTests
+            else
+              valgrind --show-error-list=yes --track-origins=yes --error-exitcode=1 \
+                --show-leak-kinds=definite,possible \
+                unittests/CppInterOp/CppInterOpTests/unittests/bin/${{ env.BUILD_TYPE }}/CppInterOpTests
+            fi
           fi
         fi
         echo "CB_PYTHON_DIR=$CB_PYTHON_DIR" >> $GITHUB_ENV

.github/workflows/main.yml

@@ -63,9 +63,10 @@ jobs:
             clang-runtime: '20'
             cling: Off
             cppyy: Off
-            llvm_enable_projects: "clang"
+            llvm_enable_projects: "clang;compiler-rt"
             llvm_targets_to_build: "host;NVPTX"
             coverage: true
+            oop-jit: On
           - name: ubu24-x86-gcc12-clang-repl-20
             os: ubuntu-24.04
             compiler: gcc-12
@@ -74,6 +75,15 @@ jobs:
             cppyy: Off
             llvm_enable_projects: "clang"
             llvm_targets_to_build: "host;NVPTX"
+          - name: ubu24-x86-gcc12-clang-repl-20-out-of-process
+            os: ubuntu-24.04
+            compiler: gcc-12
+            clang-runtime: '20'
+            cling: Off
+            cppyy: Off
+            llvm_enable_projects: "clang;compiler-rt"
+            llvm_targets_to_build: "host;NVPTX"
+            oop-jit: On
           - name: ubu24-x86-gcc12-clang-repl-19-cppyy
             os: ubuntu-24.04
             compiler: gcc-12
@@ -100,6 +110,15 @@ jobs:
             llvm_enable_projects: "clang"
             llvm_targets_to_build: "host;NVPTX"
           # MacOS Arm Jobs
+          - name: osx15-arm-clang-clang-repl-20-out-of-process
+            os: macos-15
+            compiler: clang
+            clang-runtime: '20'
+            cling: Off
+            cppyy: Off
+            llvm_enable_projects: "clang;compiler-rt"
+            llvm_targets_to_build: "host"
+            oop-jit: On
           - name: osx15-arm-clang-clang-repl-20
             os: macos-15
             compiler: clang
@@ -220,7 +239,7 @@ jobs:
         path: |
           llvm-project
           ${{ matrix.cling=='On' && 'cling' || '' }}
-        key: ${{ env.CLING_HASH }}-${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-clang-${{ matrix.clang-runtime }}.x-patch-${{ hashFiles(format('patches/llvm/clang{0}-*.patch', matrix.clang-runtime)) || 'none' }}
+        key: ${{ env.CLING_HASH }}-${{ runner.os }}-${{ matrix.os }}-${{ matrix.compiler }}-clang-${{ matrix.clang-runtime }}.x-patch-${{ hashFiles(format('patches/llvm/clang{0}-*.patch', matrix.clang-runtime)) || 'none' }}${{ matrix.oop-jit == 'On' && '-oop' || '' }}
 
     - name: Setup default Build Type
       uses: ./.github/actions/Miscellaneous/Select_Default_Build_Type

CMakeLists.txt

@@ -298,6 +298,18 @@ include_directories(SYSTEM ${LLVM_INCLUDE_DIRS})
 separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
 add_definitions(${LLVM_DEFINITIONS_LIST})
 
+string(REGEX REPLACE "/lib/cmake/llvm$" "" LLVM_BINARY_LIB_DIR "${LLVM_DIR}")
+add_definitions(-DLLVM_BINARY_LIB_DIR="${LLVM_BINARY_LIB_DIR}")
+
+if(LLVM_BUILT_WITH_OOP_JIT)
+  if((CMAKE_SYSTEM_NAME STREQUAL "Darwin" AND CMAKE_SYSTEM_PROCESSOR MATCHES "arm64") OR
+     (CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64"))
+    add_definitions(-DLLVM_BUILT_WITH_OOP_JIT)
+  else()
+    message(FATAL_ERROR "LLVM_BUILT_WITH_OOP_JIT is only supported on MacOS arm64 or Linux x86_64. Build aborted.")
+  endif()
+endif()
+
 # If the llvm sources are present add them with higher priority.
 if (LLVM_BUILD_MAIN_SRC_DIR)
   # LLVM_INCLUDE_DIRS contains the include paths to both LLVM's source and

README.md

@@ -111,6 +111,13 @@ git clone --depth=1 --branch release/20.x https://github.com/llvm/llvm-project.g
 cd llvm-project
 ```
 
+If you want to have out-of-process JIT execution enabled in CppInterOp, then apply this patch on Linux-x86_64 and MacOS arm64 environment.
+> Note that this patch will not work for Windows because out-of-process JIT execution is currently implemented for Linux-x86_64 and MacOS arm64 only.
+
+```bash
+git apply -v ../CppInterOp/patches/llvm/clang20-1-out-of-process.patch
+```
+
 ##### Build Clang-REPL
 
 Clang-REPL is an interpreter that CppInterOp works alongside. Build Clang (and
@@ -140,6 +147,45 @@ export LLVM_DIR=$PWD
 cd ../
 ```
 
+##### Build Clang-REPL with Out-of-Process JIT Execution
+
+To have ``Out-of-Process JIT Execution`` enabled, run following commands to build clang and clang-repl to support this feature:
+> Only for Linux x86_64 and MacOS arm64
+
+```bash
+mkdir build 
+cd build 
+cmake -DLLVM_ENABLE_PROJECTS="clang;compiler-rt"                   \
+              -DLLVM_TARGETS_TO_BUILD="host;NVPTX"                \
+              -DCMAKE_BUILD_TYPE=Release                          \
+              -DLLVM_ENABLE_ASSERTIONS=ON                         \
+              -DCLANG_ENABLE_STATIC_ANALYZER=OFF                  \
+              -DCLANG_ENABLE_ARCMT=OFF                            \
+              -DCLANG_ENABLE_FORMAT=OFF                           \
+              -DCLANG_ENABLE_BOOTSTRAP=OFF                        \
+              ../llvm
+```
+
+###### For Linux x86_64
+
+```bash
+cmake --build . --target clang clang-repl llvm-jitlink-executor orc_rt-x86_64 --parallel $(nproc --all)
+```
+
+###### For MacOS arm64
+
+```bash
+cmake --build . --target clang clang-repl llvm-jitlink-executor orc_rt_osx --parallel $(sysctl -n hw.ncpu)
+```
+
+Note the 'llvm-project' directory location by executing
+
+```bash
+cd ../
+export LLVM_DIR=$PWD
+cd ../
+```
+
 #### Environment variables
 
 You will need to define the following environment variables for the build of CppInterOp and cppyy (as they clear for a new session, it is recommended that you also add these to your .bashrc in linux, .bash_profile if on MacOS). On Linux and MacOS you define as follows
@@ -167,6 +213,10 @@ cmake -DBUILD_SHARED_LIBS=ON -DCPPINTEROP_USE_CLING=ON -DCPPINTEROP_USE_REPL=Off
 cmake --build . --target install --parallel $(nproc --all)
 ```
 
+and
+
+> Do make sure to pass ``DLLVM_BUILT_WITH_OOP_JIT=ON``, if you want to have out-of-process JIT execution feature enabled.
+
 #### Testing CppInterOp
 
 To test the built CppInterOp execute the following command in the CppInterOP build folder on Linux and MacOS

docs/DevelopersDocumentation.rst

@@ -41,6 +41,15 @@ Clone the 20.x release of the LLVM project repository.
    git clone --depth=1 --branch release/20.x https://github.com/llvm/llvm-project.git
    cd llvm-project
 
+If you want to have out-of-process JIT execution enabled in CppInterOp, then apply this patch on Linux-x86_64 and MacOS arm64 environment.
+.. note::
+
+   This patch will not work for Windows because out-of-process JIT execution is currently implemented for Linux and MacOS only.
+
+.. code:: bash
+
+   git apply -v ../CppInterOp/patches/llvm/clang20-1-out-of-process.patch
+
 ******************
  Build Clang-REPL
 ******************
@@ -99,6 +108,34 @@ On Windows you execute the following
    $env:LLVM_DIR= $PWD.Path
    cd ..\
 
+***************************************************
+Build Clang-REPL with Out-of-Process JIT Execution
+***************************************************
+
+To have `Out-of-Process JIT Execution` enabled, run following commands to build clang and clang-repl to support this feature:
+
+.. note::
+
+   Only for Linux x86_64 and MacOS arm64
+
+.. code:: bash
+   mkdir build 
+   cd build 
+   cmake -DLLVM_ENABLE_PROJECTS="clang;compiler-rt"                   \
+                  -DLLVM_TARGETS_TO_BUILD="host;NVPTX"                \
+                  -DCMAKE_BUILD_TYPE=Release                          \
+                  -DLLVM_ENABLE_ASSERTIONS=ON                         \
+                  -DCLANG_ENABLE_STATIC_ANALYZER=OFF                  \
+                  -DCLANG_ENABLE_ARCMT=OFF                            \
+                  -DCLANG_ENABLE_FORMAT=OFF                           \
+                  -DCLANG_ENABLE_BOOTSTRAP=OFF                        \
+                  ../llvm
+   
+   # For Linux x86_64
+   cmake --build . --target clang clang-repl llvm-jitlink-executor orc_rt-x86_64 --parallel $(nproc --all)
+   # For MacOS arm64
+   cmake --build . --target clang clang-repl llvm-jitlink-executor orc_rt_osx --parallel $(sysctl -n hw.ncpu)
+
 **************************************
  Build Cling and related dependencies
 **************************************
@@ -261,6 +298,10 @@ commands on Linux and MacOS
    cmake -DBUILD_SHARED_LIBS=ON -DLLVM_DIR=$LLVM_DIR/build/lib/cmake/llvm -DClang_DIR=$LLVM_DIR/build/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR ..
    cmake --build . --target install --parallel $(nproc --all)
 
+.. note::
+
+   Do make sure to pass ``DLLVM_BUILT_WITH_OOP_JIT=ON``, if you want to have out-of-process JIT execution feature enabled.
+
 and
 
 .. code:: powershell

docs/InstallationAndUsage.rst

@@ -41,6 +41,15 @@ Clone the 20.x release of the LLVM project repository.
    git clone --depth=1 --branch release/20.x https://github.com/llvm/llvm-project.git
    cd llvm-project
 
+If you want to have out-of-process JIT execution enabled in CppInterOp, then apply this patch on Linux-x86_64 and MacOS arm64 environment.
+.. note::
+
+   This patch will not work for Windows because out-of-process JIT execution is currently implemented for Linux and MacOS only.
+
+.. code:: bash
+
+   git apply -v ../CppInterOp/patches/llvm/clang20-1-out-of-process.patch
+
 ******************
  Build Clang-REPL
 ******************
@@ -99,6 +108,34 @@ On Windows you execute the following
    $env:LLVM_DIR= $PWD.Path
    cd ..\
 
+***************************************************
+Build Clang-REPL with Out-of-Process JIT Execution
+***************************************************
+
+To have `Out-of-Process JIT Execution` enabled, run following commands to build clang and clang-repl to support this feature:
+
+.. note::
+
+   Only for Linux x86_64 and MacOS arm64
+
+.. code:: bash
+   mkdir build 
+   cd build 
+   cmake -DLLVM_ENABLE_PROJECTS="clang;compiler-rt"                   \
+                  -DLLVM_TARGETS_TO_BUILD="host;NVPTX"                \
+                  -DCMAKE_BUILD_TYPE=Release                          \
+                  -DLLVM_ENABLE_ASSERTIONS=ON                         \
+                  -DCLANG_ENABLE_STATIC_ANALYZER=OFF                  \
+                  -DCLANG_ENABLE_ARCMT=OFF                            \
+                  -DCLANG_ENABLE_FORMAT=OFF                           \
+                  -DCLANG_ENABLE_BOOTSTRAP=OFF                        \
+                  ../llvm
+   
+   # For Linux x86_64
+   cmake --build . --target clang clang-repl llvm-jitlink-executor orc_rt-x86_64 --parallel $(nproc --all)
+   # For MacOS arm64
+   cmake --build . --target clang clang-repl llvm-jitlink-executor orc_rt_osx --parallel $(sysctl -n hw.ncpu)
+
 **************************************
  Build Cling and related dependencies
 **************************************
@@ -263,6 +300,10 @@ commands on Linux and MacOS
    cmake -DBUILD_SHARED_LIBS=ON -DLLVM_DIR=$LLVM_DIR/build/lib/cmake/llvm -DClang_DIR=$LLVM_DIR/build/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR ..
    cmake --build . --target install --parallel $(nproc --all)
 
+.. note::
+
+   Do make sure to pass ``DLLVM_BUILT_WITH_OOP_JIT=ON``, if you want to have out-of-process JIT execution feature enabled.
+
 and
 
 .. code:: powershell

etc/clang20-valgrind.supp

@@ -0,0 +1,18 @@
+{
+   Clang 20 Out of Process
+   Memcheck:Param
+   write(buf)
+   fun:__libc_write
+   fun:write
+   fun:_ZN4llvm3orc26FDSimpleRemoteEPCTransport11sendMessageENS0_21SimpleRemoteEPCOpcodeEmNS0_12ExecutorAddrENS_8ArrayRefIcEE
+   fun:_ZN4llvm3orc15SimpleRemoteEPC11sendMessageENS0_21SimpleRemoteEPCOpcodeEmNS0_12ExecutorAddrENS_8ArrayRefIcEE
+   fun:_ZN4llvm3orc15SimpleRemoteEPC16callWrapperAsyncENS0_12ExecutorAddrENS0_22ExecutorProcessControl18IncomingWFRHandlerENS_8ArrayRefIcEE
+   fun:_ZN4llvm3orc30EPCGenericJITLinkMemoryManager13InFlightAlloc8finalizeENS_15unique_functionIFvNS_8ExpectedINS_7jitlink20JITLinkMemoryManager14FinalizedAllocEEEEEE
+   fun:_ZN4llvm7jitlink13JITLinkerBase10linkPhase3ESt10unique_ptrIS1_St14default_deleteIS1_EENS_8ExpectedINS_8DenseMapINS_3orc15SymbolStringPtrENS8_17ExecutorSymbolDefENS_12DenseMapInfoIS9_vEENS_6detail12DenseMapPairIS9_SA_EEEEEE
+   fun:_ZZN4llvm7jitlink24createLookupContinuationIZNS0_13JITLinkerBase10linkPhase2ESt10unique_ptrIS2_St14default_deleteIS2_EENS_8ExpectedIS3_INS0_20JITLinkMemoryManager13InFlightAllocES4_IS9_EEEEEUlNS7_INS_8DenseMapINS_3orc15SymbolStringPtrENSE_17ExecutorSymbolDefENS_12DenseMapInfoISF_vEENS_6detail12DenseMapPairISF_SG_EEEEEEE_EES3_INS0_30JITLinkAsyncLookupContinuationES4_ISP_EET_EN4Impl3runESN_
+   fun:_ZZN4llvm3orc21LinkGraphLinkingLayer10JITLinkCtx6lookupERKNS_8DenseMapINS0_15SymbolStringPtrENS_7jitlink17SymbolLookupFlagsENS_12DenseMapInfoIS4_vEENS_6detail12DenseMapPairIS4_S6_EEEESt10unique_ptrINS5_30JITLinkAsyncLookupContinuationESt14default_deleteISG_EEENUlNS_8ExpectedINS3_IS4_NS0_17ExecutorSymbolDefES8_NSA_IS4_SL_EEEEEEE0_clESO_
+   fun:_ZN4llvm6detail18UniqueFunctionBaseIvJNS_8ExpectedINS_8DenseMapINS_3orc15SymbolStringPtrENS4_17ExecutorSymbolDefENS_12DenseMapInfoIS5_vEENS0_12DenseMapPairIS5_S6_EEEEEEEE8CallImplIZNS4_21LinkGraphLinkingLayer10JITLinkCtx6lookupERKNS3_IS5_NS_7jitlink17SymbolLookupFlagsES8_NS9_IS5_SI_EEEESt10unique_ptrINSH_30JITLinkAsyncLookupContinuationESt14default_deleteISO_EEEUlSC_E0_EEvPvRSC_
+   fun:_ZZN4llvm3orc23AsynchronousSymbolQuery14handleCompleteERNS0_16ExecutionSessionEEN20RunQueryCompleteTask3runEv
+   fun:_ZNSt6thread11_State_implINS_8_InvokerISt5tupleIJZN4llvm3orc31DynamicThreadPoolTaskDispatcher8dispatchESt10unique_ptrINS4_4TaskESt14default_deleteIS7_EEEUlvE_EEEEE6_M_runEv
+   obj:/usr/lib/x86_64-linux-gnu/libstdc++.so.6.0.30
+}

include/CppInterOp/CppInterOp.h

@@ -19,6 +19,7 @@
 #include <cstdint>
 #include <set>
 #include <string>
+#include <sys/types.h>
 #include <vector>
 
 // The cross-platform CPPINTEROP_API macro definition
@@ -935,6 +936,12 @@ CPPINTEROP_API void CodeComplete(std::vector<std::string>& Results,
 ///\returns 0 on success, non-zero on failure.
 CPPINTEROP_API int Undo(unsigned N = 1);
 
+#ifndef _WIN32
+/// Returns the process ID of the executor process.
+/// \returns the PID of the executor process.
+CPPINTEROP_API pid_t GetExecutorPID();
+#endif
+
 } // end namespace Cpp
 
 #endif // CPPINTEROP_CPPINTEROP_H