This is an automated email from the ASF dual-hosted git repository.
zhztheplayer pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gluten.git
The following commit(s) were added to refs/heads/main by this push:
new 3dae1409f9 [CORE] Preserve Java throwables at the JNI boundary (#13560)
3dae1409f9 is described below
commit 3dae1409f9c8656dbb79d26f31ad5b4b8e0f3dbc
Author: Felipe Pessoto <[email protected]>
AuthorDate: Fri Nov 13 08:46:32 2026 -0800
[CORE] Preserve Java throwables at the JNI boundary (#13560)
---
.github/workflows/velox_backend_x86.yml | 16 +-
cpp/core/CMakeLists.txt | 11 +
cpp/core/jni/JavaException.cc | 198 +++++++++++++
cpp/core/jni/JavaException.h | 62 +++++
cpp/core/jni/JniCommon.h | 28 +-
cpp/core/jni/JniError.h | 30 +-
cpp/core/tests/CMakeLists.txt | 3 +
cpp/core/tests/JavaExceptionAllocationTest.cc | 160 +++++++++++
cpp/core/tests/JavaExceptionJniTest.cc | 240 ++++++++++++++++
cpp/core/tests/JavaExceptionTest.cc | 196 +++++++++++++
cpp/core/tests/utils/TestJniEnvironment.h | 179 ++++++++++++
docs/developers/NewToGluten.md | 49 ++++
gluten-arrow/pom.xml | 43 +++
.../apache/gluten/jni/JavaExceptionJniTest.java | 310 +++++++++++++++++++++
14 files changed, 1489 insertions(+), 36 deletions(-)
diff --git a/.github/workflows/velox_backend_x86.yml
b/.github/workflows/velox_backend_x86.yml
index c7a9ecc288..d73eeb3078 100644
--- a/.github/workflows/velox_backend_x86.yml
+++ b/.github/workflows/velox_backend_x86.yml
@@ -133,6 +133,7 @@ jobs:
# Output flags:
# cpp – C++ sources, Velox build scripts, or dev tooling changed
# java – any cross-version Java/Scala/Maven source changed
+ # jni_test – core JNI Java tests, their classes, or build wiring changed
# shims34/35/40/41 – version-specific shim layer changed
# tools_it – tools/gluten-it changed
#
@@ -159,6 +160,7 @@ jobs:
cpp: ${{ steps.filter.outputs.cpp }}
java: ${{ steps.filter.outputs.java }}
udf: ${{ steps.filter.outputs.udf }}
+ jni_test: ${{ steps.filter.outputs.jni_test }}
shims34: ${{ steps.filter.outputs.shims34 }}
shims35: ${{ steps.filter.outputs.shims35 }}
shims40: ${{ steps.filter.outputs.shims40 }}
@@ -188,7 +190,7 @@ jobs:
recent=$(git log --oneline --after="24 hours ago" HEAD | wc -l)
if [ "$recent" -eq 0 ]; then
echo "No commits in the last 24 hours -- skipping nightly run."
- for flag in cpp java udf shims34 shims35 shims40 shims41
shims42 tools_it; do
+ for flag in cpp java udf jni_test shims34 shims35 shims40
shims41 shims42 tools_it; do
echo "$flag=false" >> $GITHUB_OUTPUT
done
echo "full_run=false" >> $GITHUB_OUTPUT
@@ -196,7 +198,7 @@ jobs:
fi
fi
# Run everything, including the extended matrices PR runs skip.
- for flag in cpp java udf shims34 shims35 shims40 shims41 shims42
tools_it; do
+ for flag in cpp java udf jni_test shims34 shims35 shims40 shims41
shims42 tools_it; do
echo "$flag=true" >> $GITHUB_OUTPUT
done
echo "full_run=true" >> $GITHUB_OUTPUT
@@ -224,6 +226,7 @@ jobs:
echo "cpp=$(match '^(cpp/|ep/build-velox/|dev/)')"
>> $GITHUB_OUTPUT
echo "java=$(match
'^(\.github/(workflows|actions)/|pom\.xml|backends-velox/|gluten-(uniffle|celeborn|ras|core|substrait|arrow|delta|iceberg|hudi|paimon)/|gluten-ut/(common/|test/|src-iceberg-upstream/|pom\.xml)|package/|build/mvn)')"
>> $GITHUB_OUTPUT
echo "udf=$(match
'^(backends-velox/src/test/scala/org/apache/gluten/expression/VeloxUdfSuite\.scala|\.github/workflows/velox_backend_x86\.yml)$')"
>> $GITHUB_OUTPUT
+ echo "jni_test=$(match
'^(\.github/workflows/velox_backend_x86\.yml|pom\.xml|gluten-(arrow|core)/pom\.xml|build/mvn|gluten-arrow/src/test/java/org/apache/gluten/jni/.*|gluten-arrow/src/main/java/org/apache/gluten/exception/JniExceptionDescriber\.java|gluten-core/src/main/java/org/apache/gluten/exception/GlutenException\.java)$')"
>> $GITHUB_OUTPUT
echo "shims34=$(match
'^(shims/(spark34|common)/|gluten-ut/spark34/)')" >>
$GITHUB_OUTPUT
echo "shims35=$(match
'^(shims/(spark35|common)/|gluten-ut/spark35/)')" >>
$GITHUB_OUTPUT
echo "shims40=$(match
'^(shims/(spark40|common)/|gluten-ut/spark40/)')" >>
$GITHUB_OUTPUT
@@ -1160,7 +1163,10 @@ jobs:
cpp-test-udf-test:
needs: detect-changes
- if: needs.detect-changes.outputs.cpp == 'true' ||
needs.detect-changes.outputs.udf == 'true'
+ if: >-
+ needs.detect-changes.outputs.cpp == 'true' ||
+ needs.detect-changes.outputs.udf == 'true' ||
+ needs.detect-changes.outputs.jni_test == 'true'
runs-on: ubuntu-24.04
container: apache/gluten:centos-9-jdk8
steps:
@@ -1207,6 +1213,7 @@ jobs:
run: |
df -a
bash dev/ci-velox-buildshared-centos-9.sh
+ cmake --build cpp/build --target java_exception_jni_test --parallel 2
ccache -s
# Runs in this job because clang-tidy needs the compilation database and
header tree
# the build just produced; only 'cpp/build/' is uploaded, so shipping
@@ -1250,7 +1257,7 @@ jobs:
--conf $(realpath
backends-velox/generated-native-benchmark/conf_12_0_*.ini) \
--plan $(realpath
backends-velox/generated-native-benchmark/plan_12_0_*.json) \
--data $(realpath
backends-velox/generated-native-benchmark/data_12_0_*_0.parquet),$(realpath
backends-velox/generated-native-benchmark/data_12_0_*_1.parquet)
- - name: Run UDF test
+ - name: Run JNI and UDF tests
run: |
export SPARK_SCALA_VERSION=2.12
yum install -y java-17-openjdk-devel
@@ -1259,6 +1266,7 @@ jobs:
java -version
# Depends on --build_example=ON.
$MVN_CMD install -Pspark-3.5 -Pbackends-velox -Pjava-17 -pl
backends-velox -am -DskipTests
+ $MVN_CMD test -pl gluten-arrow -Pspark-3.5 -Pbackends-velox
-Pjava-17 -Pjni-test
for bypass_registration in false true; do
for suite in VeloxUdfSuiteLocal VeloxUdfSuiteCluster; do
echo "Running $suite with bypass
registration=$bypass_registration"
diff --git a/cpp/core/CMakeLists.txt b/cpp/core/CMakeLists.txt
index b16ce48c96..6033bc3848 100644
--- a/cpp/core/CMakeLists.txt
+++ b/cpp/core/CMakeLists.txt
@@ -146,6 +146,7 @@ set(SPARK_COLUMNAR_PLUGIN_SRCS
utils/tac/TypeAwareCompressCodec.cc
utils/StringUtil.cc
utils/ObjectStore.cc
+ jni/JavaException.cc
jni/JniError.cc
jni/JniCommon.cc
jni/TaskContextJniWrapper.cc)
@@ -261,6 +262,16 @@ if(NOT ENABLE_GLUTEN_VCPKG)
endif()
target_link_libraries(gluten_core_impl PRIVATE glog::glog)
+# Java CI builds this explicitly and transfers it separately from production
+# libraries.
+add_library(java_exception_jni_test SHARED EXCLUDE_FROM_ALL
+ tests/JavaExceptionJniTest.cc)
+target_link_libraries(java_exception_jni_test
+ PRIVATE gluten_core_impl glog::glog Threads::Threads)
+set_target_properties(
+ java_exception_jni_test PROPERTIES LIBRARY_OUTPUT_DIRECTORY
+ ${root_directory}/test-libs)
+
install(TARGETS gluten DESTINATION ${CMAKE_INSTALL_LIBDIR})
if(CMAKE_SYSTEM_NAME MATCHES "Linux")
diff --git a/cpp/core/jni/JavaException.cc b/cpp/core/jni/JavaException.cc
new file mode 100644
index 0000000000..22070a1e3e
--- /dev/null
+++ b/cpp/core/jni/JavaException.cc
@@ -0,0 +1,198 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "JavaException.h"
+
+#include <glog/logging.h>
+
+#include <stdexcept>
+#include <string>
+
+namespace gluten {
+
+JniEntryGuard::JniEntryGuard() noexcept {
+ ++depth_;
+}
+
+JniEntryGuard::~JniEntryGuard() noexcept {
+ --depth_;
+}
+
+bool JniEntryGuard::isActive() noexcept {
+ return depth_ != 0;
+}
+
+namespace {
+
+// The describer class and result need two locals; reserve one spare slot.
+constexpr jint kDescriptionLocalCapacity = 3;
+
+class LocalFrame {
+ public:
+ explicit LocalFrame(JNIEnv* env) : env_(env),
pushed_(env->PushLocalFrame(kDescriptionLocalCapacity) == JNI_OK) {}
+
+ ~LocalFrame() {
+ if (pushed_) {
+ env_->PopLocalFrame(nullptr);
+ }
+ }
+
+ bool pushed() const {
+ return pushed_;
+ }
+
+ private:
+ JNIEnv* env_;
+ bool pushed_;
+};
+
+// Lossy native wrappers and destructor logging may have only what(), not the
carrier.
+std::string describe(JNIEnv* env, jthrowable throwable) {
+ const std::string prefix = "Error during calling Java code from native code:
";
+ const auto unavailable = [&](const char* reason) {
+ // Describing an exception must not replace the throwable we are
transporting.
+ env->ExceptionClear();
+ return prefix + "Java stack trace unavailable (" + reason + ")";
+ };
+ LocalFrame frame(env);
+ if (!frame.pushed()) {
+ return unavailable("PushLocalFrame failed");
+ }
+ auto describer =
env->FindClass("org/apache/gluten/exception/JniExceptionDescriber");
+ if (describer == nullptr) {
+ return unavailable("JniExceptionDescriber lookup failed");
+ }
+ auto method = env->GetStaticMethodID(describer, "describe",
"(Ljava/lang/Throwable;)Ljava/lang/String;");
+ if (method == nullptr) {
+ return unavailable("describe method lookup failed");
+ }
+ auto description =
static_cast<jstring>(env->CallStaticObjectMethod(describer, method, throwable));
+ if (env->ExceptionCheck() || description == nullptr) {
+ return unavailable("describe method failed");
+ }
+ const auto release = [&](const char* chars) {
env->ReleaseStringUTFChars(description, chars); };
+ std::unique_ptr<const char, decltype(release)>
chars(env->GetStringUTFChars(description, nullptr), release);
+ if (!chars) {
+ return unavailable("GetStringUTFChars failed");
+ }
+ return prefix + chars.get();
+}
+
+} // namespace
+
+struct JavaException::State {
+ State(JNIEnv* env, jthrowable throwable) {
+ if (throwable == nullptr) {
+ throw std::invalid_argument("JavaException requires a non-null
throwable");
+ }
+ if (env->GetJavaVM(&vm) != JNI_OK) {
+ throw std::runtime_error("Unable to get JavaVM for Java exception");
+ }
+ ref = static_cast<jthrowable>(env->NewGlobalRef(throwable));
+ if (ref == nullptr) {
+ throw std::runtime_error("Unable to create global reference for Java
exception");
+ }
+ }
+
+ ~State() {
+ JNIEnv* env = nullptr;
+ auto status = vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_8);
+ const bool detached = status == JNI_EDETACHED;
+ if (detached) {
+ status = vm->AttachCurrentThreadAsDaemon(reinterpret_cast<void**>(&env),
nullptr);
+ }
+ if (status != JNI_OK) {
+ LOG(ERROR) << "Unable to attach thread to release Java exception global
reference: " << status;
+ return;
+ }
+ env->DeleteGlobalRef(ref);
+ // Only detach if this destructor attached the thread; never detach a
caller's JNI/HDFS thread.
+ if (detached && vm->DetachCurrentThread() != JNI_OK) {
+ LOG(ERROR) << "Unable to detach thread after releasing Java exception
global reference";
+ }
+ }
+
+ JavaVM* vm{nullptr};
+ jthrowable ref{nullptr};
+ std::string message;
+};
+
+JavaException::JavaException(JNIEnv* env, jthrowable throwable) :
state_(std::make_shared<State>(env, throwable)) {
+ try {
+ state_->message = describe(env, throwable);
+ } catch (const std::exception&) {
+ // Keep the captured throwable even if diagnostics fail. what() must not
allocate a fallback.
+ env->ExceptionClear();
+ }
+}
+
+const char* JavaException::what() const noexcept {
+ return state_->message.empty()
+ ? "Error during calling Java code from native code: Java stack trace
unavailable (native diagnostic failure)"
+ : state_->message.c_str();
+}
+
+void JavaException::throwToJava(JNIEnv* env) const noexcept {
+ if (env->Throw(state_->ref) != JNI_OK) {
+ LOG(ERROR) << "Unable to restore original Java exception";
+ }
+}
+
+bool JavaException::throwNestedToJava(JNIEnv* env, const std::exception&
error) noexcept {
+ const auto* nested = dynamic_cast<const std::nested_exception*>(&error);
+ if (nested == nullptr || nested->nested_ptr() == nullptr) {
+ return false;
+ }
+ try {
+ std::rethrow_exception(nested->nested_ptr());
+ } catch (const JavaException& original) {
+ original.throwToJava(env);
+ return true;
+ } catch (const std::exception& cause) {
+ return throwNestedToJava(env, cause);
+ } catch (...) {
+ // Not a Java exception. Leave the enclosing native error to the existing
JNI fallback.
+ return false;
+ }
+}
+
+void JavaException::check(JNIEnv* env) {
+ if (!env->ExceptionCheck()) {
+ return;
+ }
+ auto throwable = env->ExceptionOccurred();
+ env->ExceptionClear();
+ const auto release = [env](jthrowable ref) { env->DeleteLocalRef(ref); };
+ std::unique_ptr<_jthrowable, decltype(release)> local(throwable, release);
+ // Guard construction only: successful carrier propagation must leave JNI
clear.
+ auto error = [env, throwable]() {
+ try {
+ return JavaException(env, throwable);
+ } catch (...) {
+ if (!JniEntryGuard::isActive()) {
+ // An attached pool worker has no Java return boundary to consume
pending state.
+ env->ExceptionClear();
+ } else if (!env->ExceptionCheck() && env->Throw(throwable) != JNI_OK) {
+ LOG(ERROR) << "Unable to restore original Java exception";
+ }
+ throw;
+ }
+ }();
+ throw error;
+}
+
+} // namespace gluten
diff --git a/cpp/core/jni/JavaException.h b/cpp/core/jni/JavaException.h
new file mode 100644
index 0000000000..e1048172b4
--- /dev/null
+++ b/cpp/core/jni/JavaException.h
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <jni.h>
+
+#include <exception>
+#include <memory>
+
+namespace gluten {
+
+// Tracks guarded Java-to-native entries on the current thread, not throwable
ownership.
+class JniEntryGuard final {
+ public:
+ JniEntryGuard() noexcept;
+ ~JniEntryGuard() noexcept;
+
+ JniEntryGuard(const JniEntryGuard&) = delete;
+ JniEntryGuard& operator=(const JniEntryGuard&) = delete;
+
+ static bool isActive() noexcept;
+
+ private:
+ // Core objects can appear in multiple DSOs; inline storage is coalesced
across them.
+ inline static thread_local unsigned depth_ = 0;
+};
+
+// Owns a global reference, so copies and exception_ptrs may outlive the JNI
call or thread.
+class JavaException final : public std::exception {
+ public:
+ // The caller owns throwable's reference and must clear any pending JNI
exception first.
+ JavaException(JNIEnv* env, jthrowable throwable);
+
+ const char* what() const noexcept override;
+
+ void throwToJava(JNIEnv* env) const noexcept;
+
+ static bool throwNestedToJava(JNIEnv* env, const std::exception& error)
noexcept;
+
+ static void check(JNIEnv* env);
+
+ private:
+ struct State;
+ std::shared_ptr<State> state_;
+};
+
+} // namespace gluten
diff --git a/cpp/core/jni/JniCommon.h b/cpp/core/jni/JniCommon.h
index f1113a7f82..b72fd3eee9 100644
--- a/cpp/core/jni/JniCommon.h
+++ b/cpp/core/jni/JniCommon.h
@@ -24,6 +24,7 @@
#include <functional>
+#include "JavaException.h"
#include "compute/ProtobufUtils.h"
#include "compute/Runtime.h"
#include "memory/AllocationListener.h"
@@ -53,32 +54,7 @@ static inline std::string jStringToCString(JNIEnv* env,
jstring string) {
}
static inline void checkException(JNIEnv* env) {
- if (env->ExceptionCheck()) {
- jthrowable t = env->ExceptionOccurred();
- env->ExceptionClear();
-
- jclass describerClass =
env->FindClass("org/apache/gluten/exception/JniExceptionDescriber");
- jmethodID describeMethod =
- env->GetStaticMethodID(describerClass, "describe",
"(Ljava/lang/Throwable;)Ljava/lang/String;");
-
- std::stringstream message;
- message << "Error during calling Java code from native code: ";
-
- const auto description =
static_cast<jstring>(env->CallStaticObjectMethod(describerClass,
describeMethod, t));
-
- if (env->ExceptionCheck()) {
- message << "Uncaught Java exception during calling the Java exception
describer method!";
- env->ExceptionClear();
- } else {
- try {
- message << jStringToCString(env, description);
- } catch (const std::exception& e) {
- message << e.what();
- }
- }
-
- throw gluten::GlutenException(message.str());
- }
+ gluten::JavaException::check(env);
}
static inline jclass createGlobalClassReference(JNIEnv* env, const char*
className) {
diff --git a/cpp/core/jni/JniError.h b/cpp/core/jni/JniError.h
index 1c57dc3b34..2e09e82f54 100644
--- a/cpp/core/jni/JniError.h
+++ b/cpp/core/jni/JniError.h
@@ -23,16 +23,34 @@
#include "utils/Exception.h"
#ifndef JNI_METHOD_START
-#define JNI_METHOD_START try {
+#define JNI_METHOD_START \
+ const gluten::JniEntryGuard jniEntryGuard; \
+ try {
// macro ended
#endif
#ifndef JNI_METHOD_END
-#define JNI_METHOD_END(fallback_expr)
\
- }
\
- catch (std::exception & e) {
\
- env->ThrowNew(gluten::getJniErrorState()->glutenExceptionClass(),
e.what()); \
- return fallback_expr;
\
+#define JNI_METHOD_END(fallback_expr)
\
+ }
\
+ catch (const gluten::JavaException& e) {
\
+ if (!env->ExceptionCheck()) {
\
+ e.throwToJava(env);
\
+ }
\
+ if (!env->ExceptionCheck() &&
\
+ env->ThrowNew(gluten::getJniErrorState()->glutenExceptionClass(),
e.what()) != JNI_OK) { \
+ LOG(ERROR) << "Unable to throw GlutenException at JNI boundary";
\
+ }
\
+ return fallback_expr;
\
+ }
\
+ catch (const std::exception& e) {
\
+ if (!env->ExceptionCheck()) {
\
+ gluten::JavaException::throwNestedToJava(env, e);
\
+ }
\
+ if (!env->ExceptionCheck() &&
\
+ env->ThrowNew(gluten::getJniErrorState()->glutenExceptionClass(),
e.what()) != JNI_OK) { \
+ LOG(ERROR) << "Unable to throw GlutenException at JNI boundary";
\
+ }
\
+ return fallback_expr;
\
}
// macro ended
#endif
diff --git a/cpp/core/tests/CMakeLists.txt b/cpp/core/tests/CMakeLists.txt
index 26000453f6..26ae2bc47d 100644
--- a/cpp/core/tests/CMakeLists.txt
+++ b/cpp/core/tests/CMakeLists.txt
@@ -19,3 +19,6 @@ add_test_case(memory_allocator_test SOURCES
MemoryAllocatorTest.cc)
add_test_case(ffor_codec_test SOURCES FForCodecTest.cc)
add_test_case(print_config_test SOURCES PrintConfigTest.cc)
add_test_case(payload_test SOURCES PayloadTest.cc)
+add_test_case(java_exception_test SOURCES JavaExceptionTest.cc)
+add_test_case(java_exception_allocation_test SOURCES
+ JavaExceptionAllocationTest.cc)
diff --git a/cpp/core/tests/JavaExceptionAllocationTest.cc
b/cpp/core/tests/JavaExceptionAllocationTest.cc
new file mode 100644
index 0000000000..ca150cc1d6
--- /dev/null
+++ b/cpp/core/tests/JavaExceptionAllocationTest.cc
@@ -0,0 +1,160 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <new>
+#include <utility>
+
+#include "jni/JavaException.h"
+#include "tests/utils/TestJniEnvironment.h"
+
+namespace {
+thread_local bool failNextAllocation = false;
+
+struct RestoreJniFunctions {
+ JNIEnv* env;
+ const JNINativeInterface_* original;
+
+ ~RestoreJniFunctions() {
+ env->functions = original;
+ }
+};
+} // namespace
+
+// This executable isolates the replacement allocator from other core tests.
+void* operator new(std::size_t size) {
+ if (std::exchange(failNextAllocation, false)) {
+ throw std::bad_alloc();
+ }
+ if (auto* memory = std::malloc(size == 0 ? 1 : size)) {
+ return memory;
+ }
+ throw std::bad_alloc();
+}
+
+void operator delete(void* memory) noexcept {
+ std::free(memory);
+}
+
+void operator delete(void* memory, std::size_t) noexcept {
+ std::free(memory);
+}
+
+TEST(JavaExceptionAllocationTest, stateAllocationFailureRetainsOriginal) {
+ gluten::TestJniEnvironment jni;
+ const gluten::JniEntryGuard entry;
+ jni.pending = &jni.original;
+ failNextAllocation = true;
+ try {
+ gluten::JavaException::check(jni.env());
+ failNextAllocation = false;
+ FAIL() << "Expected std::bad_alloc";
+ } catch (const std::bad_alloc&) {
+ EXPECT_FALSE(std::exchange(failNextAllocation, false));
+ } catch (...) {
+ failNextAllocation = false;
+ throw;
+ }
+ EXPECT_EQ(jni.pending, &jni.original);
+ EXPECT_EQ(jni.createdGlobalRefs, 0);
+ EXPECT_EQ(jni.deletedGlobalRefs, 0);
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_EQ(jni.pushedFrames, 0);
+ EXPECT_EQ(jni.poppedFrames, 0);
+ EXPECT_EQ(jni.releasedStrings, 0);
+}
+
+TEST(JavaExceptionAllocationTest,
workerStateAllocationFailureLeavesNoPendingException) {
+ gluten::TestJniEnvironment jni;
+ const gluten::JniEntryGuard callerEntry;
+ jni.workerAttached = true;
+ std::thread worker([&] {
+ EXPECT_FALSE(gluten::JniEntryGuard::isActive());
+ jni.pending = &jni.original;
+ failNextAllocation = true;
+ try {
+ gluten::JavaException::check(jni.workerEnv());
+ failNextAllocation = false;
+ FAIL() << "Expected std::bad_alloc";
+ } catch (const std::bad_alloc&) {
+ EXPECT_FALSE(std::exchange(failNextAllocation, false));
+ }
+ EXPECT_EQ(jni.pending, nullptr);
+ EXPECT_NO_THROW(gluten::JavaException::check(jni.workerEnv()));
+ });
+ worker.join();
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_EQ(jni.createdGlobalRefs, 0);
+ EXPECT_EQ(jni.deletedGlobalRefs, 0);
+ EXPECT_EQ(jni.attaches, 0);
+ EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionAllocationTest, entryTrackingDoesNotAllocate) {
+ bool nestedActive = false;
+ bool outerActive = false;
+ failNextAllocation = true;
+ {
+ const gluten::JniEntryGuard outer;
+ try {
+ const gluten::JniEntryGuard inner;
+ nestedActive = gluten::JniEntryGuard::isActive();
+ throw 7;
+ } catch (int) {
+ outerActive = gluten::JniEntryGuard::isActive();
+ }
+ }
+ const bool noAllocation = std::exchange(failNextAllocation, false);
+ EXPECT_TRUE(noAllocation);
+ EXPECT_TRUE(nestedActive);
+ EXPECT_TRUE(outerActive);
+ EXPECT_FALSE(gluten::JniEntryGuard::isActive());
+}
+
+TEST(JavaExceptionAllocationTest, diagnosticAllocationFailureRetainsOriginal) {
+ gluten::TestJniEnvironment jni;
+ auto functions = *jni.env()->functions;
+ functions.GetStringUTFChars = [](JNIEnv*, jstring, jboolean*) -> const char*
{
+ // The throwable is already captured; fail the native diagnostic string,
not NewGlobalRef.
+ failNextAllocation = true;
+ return "original Java exception";
+ };
+ const RestoreJniFunctions restore{jni.env(), jni.env()->functions};
+ jni.env()->functions = &functions;
+ jni.pending = &jni.original;
+ try {
+ gluten::JavaException::check(jni.env());
+ failNextAllocation = false;
+ FAIL() << "Expected JavaException";
+ } catch (const gluten::JavaException& error) {
+ EXPECT_FALSE(std::exchange(failNextAllocation, false));
+ EXPECT_STREQ(
+ error.what(),
+ "Error during calling Java code from native code: Java stack trace
unavailable (native diagnostic failure)");
+ EXPECT_EQ(jni.deletedGlobalRefs, 0);
+ auto copy = error;
+ copy.throwToJava(jni.env());
+ }
+ EXPECT_EQ(jni.pending, &jni.original);
+ EXPECT_EQ(jni.createdGlobalRefs, 1);
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_EQ(jni.releasedStrings, 1);
+ EXPECT_EQ(jni.pushedFrames, jni.poppedFrames);
+}
diff --git a/cpp/core/tests/JavaExceptionJniTest.cc
b/cpp/core/tests/JavaExceptionJniTest.cc
new file mode 100644
index 0000000000..353e3a73b7
--- /dev/null
+++ b/cpp/core/tests/JavaExceptionJniTest.cc
@@ -0,0 +1,240 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <exception>
+#include <stdexcept>
+#include <thread>
+
+#include "jni/JniCommon.h"
+#include "jni/JniError.h"
+
+namespace {
+class ScopedThrowFailure : public JNINativeInterface_ {
+ public:
+ ScopedThrowFailure(JNIEnv* env, jthrowable failure) noexcept
+ : JNINativeInterface_(*env->functions), env_(env),
original_(env->functions), failure_(failure) {
+ Throw = [](JNIEnv* env, jthrowable) {
+ const auto* functions = static_cast<const
ScopedThrowFailure*>(env->functions);
+ if (functions->failure_ != nullptr && functions->original_->Throw(env,
functions->failure_) != JNI_OK) {
+ LOG(ERROR) << "Unable to install injected Java restoration failure";
+ }
+ return JNI_ERR;
+ };
+ env_->functions = this;
+ }
+
+ ~ScopedThrowFailure() {
+ env_->functions = original_;
+ }
+
+ ScopedThrowFailure(const ScopedThrowFailure&) = delete;
+ ScopedThrowFailure& operator=(const ScopedThrowFailure&) = delete;
+
+ private:
+ JNIEnv* env_;
+ const JNINativeInterface_* original_;
+ jthrowable failure_;
+};
+
+class ScopedCaptureFailure : public JNINativeInterface_ {
+ public:
+ ScopedCaptureFailure(JNIEnv* env, jthrowable failure) noexcept
+ : JNINativeInterface_(*env->functions), env_(env),
original_(env->functions), failure_(failure) {
+ NewGlobalRef = [](JNIEnv* env, jobject) -> jobject {
+ const auto* functions = static_cast<const
ScopedCaptureFailure*>(env->functions);
+ if (functions->original_->Throw(env, functions->failure_) != JNI_OK) {
+ throw std::runtime_error("Unable to install injected Java capture
failure");
+ }
+ return nullptr;
+ };
+ env_->functions = this;
+ }
+
+ ~ScopedCaptureFailure() {
+ env_->functions = original_;
+ }
+
+ ScopedCaptureFailure(const ScopedCaptureFailure&) = delete;
+ ScopedCaptureFailure& operator=(const ScopedCaptureFailure&) = delete;
+
+ private:
+ JNIEnv* env_;
+ const JNINativeInterface_* original_;
+ jthrowable failure_;
+};
+
+void invokeCallback(JNIEnv* env, jobject callback) {
+ auto callbackClass = env->GetObjectClass(callback);
+ checkException(env);
+ auto run = env->GetMethodID(callbackClass, "run", "()V");
+ env->DeleteLocalRef(callbackClass);
+ checkException(env);
+ env->CallVoidMethod(callback, run);
+ checkException(env);
+}
+
+jint roundTrip(JNIEnv* env, jobject callback, jboolean nested, jthrowable
pending) {
+ JNI_METHOD_START
+ gluten::getJniErrorState()->ensureInitialized(env);
+ checkException(env);
+ try {
+ invokeCallback(env, callback);
+ } catch (...) {
+ if (pending != nullptr && env->Throw(pending) != JNI_OK) {
+ throw std::runtime_error("Unable to install newer pending Java
exception");
+ }
+ if (nested) {
+ std::throw_with_nested(std::runtime_error("native wrapper"));
+ }
+ throw;
+ }
+ return 42;
+ JNI_METHOD_END(-1)
+}
+} // namespace
+
+extern "C" JNIEXPORT jint JNICALL
+Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTrip(JNIEnv* env, jclass,
jobject callback, jboolean nested) {
+ return roundTrip(env, callback, nested, nullptr);
+}
+
+extern "C" JNIEXPORT jint JNICALL
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripWithPendingException(
+ JNIEnv* env,
+ jclass,
+ jobject callback,
+ jboolean nested,
+ jthrowable pending) {
+ return roundTrip(env, callback, nested, pending);
+}
+
+extern "C" JNIEXPORT void JNICALL
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripWithFailedCapture(
+ JNIEnv* env,
+ jclass,
+ jobject callback,
+ jthrowable failure) {
+ JNI_METHOD_START
+ gluten::getJniErrorState()->ensureInitialized(env);
+ checkException(env);
+ const ScopedCaptureFailure functions(env, failure);
+ invokeCallback(env, callback);
+ JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT void JNICALL
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripOnWorker(
+ JNIEnv* env,
+ jclass,
+ jobject callback,
+ jobject nextCallback,
+ jthrowable captureFailure) {
+ JNI_METHOD_START
+ gluten::getJniErrorState()->ensureInitialized(env);
+ checkException(env);
+ JavaVM* vm = nullptr;
+ if (env->GetJavaVM(&vm) != JNI_OK) {
+ throw std::runtime_error("Unable to get test JavaVM");
+ }
+ const auto release = [env](jobject ref) { env->DeleteGlobalRef(ref); };
+ const auto retain = [&](jobject object) {
+ std::unique_ptr<_jobject, decltype(release)>
ref(env->NewGlobalRef(object), release);
+ checkException(env);
+ return ref;
+ };
+ auto globalCallback = retain(callback);
+ auto globalNextCallback = retain(nextCallback);
+ auto globalFailure = retain(captureFailure);
+ std::exception_ptr error;
+ std::thread worker([&] {
+ JNIEnv* workerEnv = nullptr;
+ if (vm->AttachCurrentThreadAsDaemon(reinterpret_cast<void**>(&workerEnv),
nullptr) != JNI_OK) {
+ error = std::make_exception_ptr(std::runtime_error("Unable to attach
test worker"));
+ return;
+ }
+ try {
+ if (gluten::JniEntryGuard::isActive()) {
+ throw std::runtime_error("Worker inherited another thread's JNI
entry");
+ }
+ try {
+ if (globalFailure) {
+ const ScopedCaptureFailure functions(workerEnv,
static_cast<jthrowable>(globalFailure.get()));
+ invokeCallback(workerEnv, globalCallback.get());
+ } else {
+ invokeCallback(workerEnv, globalCallback.get());
+ }
+ } catch (const gluten::JavaException& captured) {
+ auto copy = captured;
+ error = std::make_exception_ptr(copy);
+ } catch (...) {
+ error = std::current_exception();
+ }
+ if (workerEnv->ExceptionCheck()) {
+ workerEnv->ExceptionClear();
+ throw std::runtime_error("Capture failure left a pending exception on
a reused worker");
+ }
+ JNIEnv* reusedEnv = nullptr;
+ if (vm->GetEnv(reinterpret_cast<void**>(&reusedEnv), JNI_VERSION_1_8) !=
JNI_OK || reusedEnv != workerEnv) {
+ throw std::runtime_error("Worker was detached between callbacks");
+ }
+ invokeCallback(workerEnv, globalNextCallback.get());
+ if (gluten::JniEntryGuard::isActive()) {
+ throw std::runtime_error("Worker retained a completed JNI entry");
+ }
+ } catch (...) {
+ error = std::current_exception();
+ }
+ // This test owns the thread; detach only after both callbacks, not
between jobs.
+ workerEnv->ExceptionClear();
+ if (vm->DetachCurrentThread() != JNI_OK) {
+ error = std::make_exception_ptr(std::runtime_error("Unable to detach
finished test worker"));
+ }
+ });
+ worker.join();
+ if (error) {
+ std::rethrow_exception(error);
+ }
+ JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT jint JNICALL
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripWithFailedRestore(
+ JNIEnv* env,
+ jclass clazz,
+ jobject callback,
+ jboolean nested,
+ jthrowable failure) {
+ // Keep fault injection active through the production boundary's catch
handlers.
+ const ScopedThrowFailure functions(env, failure);
+ return Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTrip(env, clazz,
callback, nested);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_org_apache_gluten_jni_JavaExceptionJniTest_throwNativeException(JNIEnv*
env, jclass) {
+ JNI_METHOD_START
+ gluten::getJniErrorState()->ensureInitialized(env);
+ checkException(env);
+ throw std::runtime_error("native-only failure");
+ JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT void JNICALL
Java_org_apache_gluten_jni_JavaExceptionJniTest_close(JNIEnv* env, jclass) {
+ JNI_METHOD_START
+ gluten::getJniErrorState()->close();
+ JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
Java_org_apache_gluten_jni_JavaExceptionJniTest_entryActive(JNIEnv*, jclass) {
+ // Inspect the caller's scope without adding another guarded entry.
+ return gluten::JniEntryGuard::isActive();
+}
diff --git a/cpp/core/tests/JavaExceptionTest.cc
b/cpp/core/tests/JavaExceptionTest.cc
new file mode 100644
index 0000000000..c01708dfb4
--- /dev/null
+++ b/cpp/core/tests/JavaExceptionTest.cc
@@ -0,0 +1,196 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <gtest/gtest.h>
+
+#include <stdexcept>
+#include <string>
+
+#include "jni/JavaException.h"
+#include "tests/utils/TestJniEnvironment.h"
+
+using namespace gluten;
+
+TEST(JavaExceptionTest, noPendingException) {
+ TestJniEnvironment jni;
+ EXPECT_NO_THROW(JavaException::check(jni.env()));
+ EXPECT_EQ(jni.createdGlobalRefs, 0);
+}
+
+TEST(JavaExceptionTest, copiesKeepOriginalAliveUntilLastRelease) {
+ TestJniEnvironment jni;
+ std::exception_ptr saved;
+ jni.pending = &jni.original;
+ try {
+ JavaException::check(jni.env());
+ FAIL() << "Expected JavaException";
+ } catch (const JavaException& error) {
+ EXPECT_EQ(jni.pending, nullptr);
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_STREQ(error.what(), "Error during calling Java code from native
code: original Java exception");
+ auto copy = error;
+ saved = std::make_exception_ptr(copy);
+ }
+ EXPECT_EQ(jni.createdGlobalRefs, 1);
+ EXPECT_EQ(jni.deletedGlobalRefs, 0);
+ try {
+ std::rethrow_exception(saved);
+ } catch (const JavaException& error) {
+ error.throwToJava(jni.env());
+ }
+ EXPECT_EQ(jni.pending, &jni.original);
+ saved = nullptr;
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+ EXPECT_TRUE(jni.globalRefs.empty());
+ EXPECT_EQ(jni.pushedFrames, jni.poppedFrames);
+ EXPECT_EQ(jni.releasedStrings, 1);
+ EXPECT_EQ(jni.attaches, 0);
+ EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionTest, cleanupOnDetachedThread) {
+ TestJniEnvironment jni;
+ auto saved = std::make_exception_ptr(JavaException(jni.env(),
&jni.original));
+ std::thread worker([error = std::move(saved)]() mutable { error = nullptr;
});
+ worker.join();
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+ EXPECT_TRUE(jni.globalRefs.empty());
+ EXPECT_EQ(jni.deletingEnv, jni.workerEnv());
+ EXPECT_EQ(jni.attaches, 1);
+ EXPECT_EQ(jni.detaches, 1);
+}
+
+TEST(JavaExceptionTest, cleanupDoesNotDetachPreviouslyAttachedThread) {
+ TestJniEnvironment jni;
+ jni.workerAttached = true;
+ auto saved = std::make_exception_ptr(JavaException(jni.env(),
&jni.original));
+ std::thread worker([error = std::move(saved)]() mutable { error = nullptr;
});
+ worker.join();
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+ EXPECT_EQ(jni.deletingEnv, jni.workerEnv());
+ EXPECT_EQ(jni.attaches, 0);
+ EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionTest, descriptionFailureDoesNotReplaceOriginal) {
+ TestJniEnvironment jni;
+ jni.failDescription = true;
+ jni.pending = &jni.original;
+ try {
+ JavaException::check(jni.env());
+ FAIL() << "Expected JavaException";
+ } catch (const JavaException& error) {
+ EXPECT_EQ(jni.pending, nullptr);
+ EXPECT_NE(std::string(error.what()).find("JniExceptionDescriber lookup
failed"), std::string::npos);
+ error.throwToJava(jni.env());
+ }
+ EXPECT_EQ(jni.pending, &jni.original);
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_EQ(jni.pushedFrames, jni.poppedFrames);
+}
+
+TEST(JavaExceptionTest, localFrameFailureDoesNotReplaceOriginal) {
+ TestJniEnvironment jni;
+ jni.failLocalFrame = true;
+ {
+ JavaException error(jni.env(), &jni.original);
+ EXPECT_EQ(jni.pending, nullptr);
+ error.throwToJava(jni.env());
+ }
+ EXPECT_EQ(jni.pending, &jni.original);
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+ EXPECT_EQ(jni.poppedFrames, 0);
+}
+
+TEST(JavaExceptionTest, globalRefFailureRetainsPendingAllocationError) {
+ TestJniEnvironment jni;
+ const JniEntryGuard entry;
+ jni.failGlobalRef = true;
+ jni.pending = &jni.original;
+ EXPECT_THROW(JavaException::check(jni.env()), std::runtime_error);
+ EXPECT_EQ(jni.pending, &jni.secondary);
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_EQ(jni.createdGlobalRefs, 0);
+ EXPECT_EQ(jni.deletedGlobalRefs, 0);
+}
+
+TEST(JavaExceptionTest, workerGlobalRefFailureLeavesNoPendingException) {
+ TestJniEnvironment jni;
+ const JniEntryGuard callerEntry;
+ jni.workerAttached = true;
+ std::thread worker([&] {
+ EXPECT_FALSE(JniEntryGuard::isActive());
+ jni.failGlobalRef = true;
+ jni.pending = &jni.original;
+ EXPECT_THROW(JavaException::check(jni.workerEnv()), std::runtime_error);
+ EXPECT_EQ(jni.pending, nullptr);
+ jni.failGlobalRef = false;
+ EXPECT_NO_THROW(JavaException::check(jni.workerEnv()));
+ });
+ worker.join();
+ EXPECT_EQ(jni.deletedLocalRefs, 1);
+ EXPECT_EQ(jni.createdGlobalRefs, 0);
+ EXPECT_EQ(jni.deletedGlobalRefs, 0);
+ EXPECT_EQ(jni.attaches, 0);
+ EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionTest, standardNestedWrappersRestoreOriginal) {
+ TestJniEnvironment jni;
+ try {
+ throw JavaException(jni.env(), &jni.original);
+ } catch (...) {
+ try {
+ std::throw_with_nested(std::runtime_error("inner native wrapper"));
+ } catch (...) {
+ try {
+ std::throw_with_nested(std::runtime_error("outer native wrapper"));
+ } catch (const std::exception& error) {
+ EXPECT_TRUE(JavaException::throwNestedToJava(jni.env(), error));
+ }
+ }
+ }
+ EXPECT_EQ(jni.pending, &jni.original);
+ EXPECT_EQ(jni.createdGlobalRefs, 1);
+ EXPECT_EQ(jni.deletedGlobalRefs, 1);
+}
+
+TEST(JavaExceptionTest, nativeOnlyWrappersRetainExistingFallback) {
+ TestJniEnvironment jni;
+ EXPECT_FALSE(JavaException::throwNestedToJava(jni.env(),
std::runtime_error("native error")));
+ try {
+ throw std::runtime_error("native cause");
+ } catch (...) {
+ try {
+ std::throw_with_nested(std::runtime_error("native wrapper"));
+ } catch (const std::exception& error) {
+ EXPECT_FALSE(JavaException::throwNestedToJava(jni.env(), error));
+ }
+ }
+ try {
+ throw 42;
+ } catch (...) {
+ try {
+ std::throw_with_nested(std::runtime_error("nonstandard native cause"));
+ } catch (const std::exception& error) {
+ EXPECT_FALSE(JavaException::throwNestedToJava(jni.env(), error));
+ }
+ }
+ EXPECT_EQ(jni.pending, nullptr);
+ EXPECT_EQ(jni.createdGlobalRefs, 0);
+}
diff --git a/cpp/core/tests/utils/TestJniEnvironment.h
b/cpp/core/tests/utils/TestJniEnvironment.h
new file mode 100644
index 0000000000..f339fe750a
--- /dev/null
+++ b/cpp/core/tests/utils/TestJniEnvironment.h
@@ -0,0 +1,179 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <jni.h>
+
+#include <thread>
+#include <unordered_map>
+
+namespace gluten {
+
+// JNI function tables let tests account for references without relying on JVM
garbage collection.
+class TestJniEnvironment {
+ private:
+ struct Env : JNIEnv_ {
+ explicit Env(TestJniEnvironment* owner) : owner(owner) {
+ functions = &owner->functions_;
+ }
+ TestJniEnvironment* owner;
+ };
+
+ struct Vm : JavaVM_ {
+ explicit Vm(TestJniEnvironment* owner) : owner(owner) {
+ functions = &owner->invocation_;
+ }
+ TestJniEnvironment* owner;
+ };
+
+ static TestJniEnvironment& from(JNIEnv* env) {
+ return *static_cast<Env*>(env)->owner;
+ }
+
+ static TestJniEnvironment& from(JavaVM* vm) {
+ return *static_cast<Vm*>(vm)->owner;
+ }
+
+ public:
+ TestJniEnvironment() {
+ functions_.GetJavaVM = [](JNIEnv* env, JavaVM** vm) {
+ *vm = &from(env).vm_;
+ return JNI_OK;
+ };
+ functions_.ExceptionCheck = [](JNIEnv* env) -> jboolean { return
from(env).pending != nullptr; };
+ functions_.ExceptionOccurred = [](JNIEnv* env) { return from(env).pending;
};
+ functions_.ExceptionClear = [](JNIEnv* env) { from(env).pending = nullptr;
};
+ functions_.NewGlobalRef = [](JNIEnv* env, jobject object) -> jobject {
+ auto& self = from(env);
+ if (self.failGlobalRef) {
+ self.pending = &self.secondary;
+ return nullptr;
+ }
+ auto ref = new _jthrowable();
+ self.globalRefs.emplace(ref, static_cast<jthrowable>(object));
+ ++self.createdGlobalRefs;
+ return ref;
+ };
+ functions_.DeleteGlobalRef = [](JNIEnv* env, jobject object) {
+ auto& self = from(env);
+ self.globalRefs.erase(object);
+ delete static_cast<jthrowable>(object);
+ ++self.deletedGlobalRefs;
+ self.deletingEnv = env;
+ };
+ functions_.DeleteLocalRef = [](JNIEnv* env, jobject) {
++from(env).deletedLocalRefs; };
+ functions_.Throw = [](JNIEnv* env, jthrowable throwable) {
+ auto& self = from(env);
+ auto global = self.globalRefs.find(throwable);
+ self.pending = global == self.globalRefs.end() ? throwable :
global->second;
+ return JNI_OK;
+ };
+ functions_.PushLocalFrame = [](JNIEnv* env, jint) {
+ auto& self = from(env);
+ if (self.failLocalFrame) {
+ self.pending = &self.secondary;
+ return JNI_ERR;
+ }
+ ++self.pushedFrames;
+ return JNI_OK;
+ };
+ functions_.PopLocalFrame = [](JNIEnv* env, jobject result) {
+ ++from(env).poppedFrames;
+ return result;
+ };
+ functions_.FindClass = [](JNIEnv* env, const char*) -> jclass {
+ auto& self = from(env);
+ if (self.failDescription) {
+ self.pending = &self.secondary;
+ return nullptr;
+ }
+ return &self.describer_;
+ };
+ functions_.GetStaticMethodID = [](JNIEnv* env, jclass, const char*, const
char*) {
+ return reinterpret_cast<jmethodID>(&from(env).describer_);
+ };
+ functions_.CallStaticObjectMethodV = [](JNIEnv* env, jclass, jmethodID,
va_list) -> jobject {
+ return &from(env).description_;
+ };
+ functions_.GetStringUTFChars = [](JNIEnv*, jstring, jboolean*) { return
"original Java exception"; };
+ functions_.ReleaseStringUTFChars = [](JNIEnv* env, jstring, const char*) {
++from(env).releasedStrings; };
+ invocation_.GetEnv = [](JavaVM* vm, void** env, jint) {
+ auto& self = from(vm);
+ if (std::this_thread::get_id() == self.ownerThread_) {
+ *env = &self.env_;
+ return JNI_OK;
+ }
+ if (!self.workerAttached) {
+ return JNI_EDETACHED;
+ }
+ *env = &self.workerEnv_;
+ return JNI_OK;
+ };
+ invocation_.AttachCurrentThreadAsDaemon = [](JavaVM* vm, void** env,
void*) {
+ auto& self = from(vm);
+ ++self.attaches;
+ self.workerAttached = true;
+ *env = &self.workerEnv_;
+ return JNI_OK;
+ };
+ invocation_.DetachCurrentThread = [](JavaVM* vm) {
+ auto& self = from(vm);
+ ++self.detaches;
+ self.workerAttached = false;
+ return JNI_OK;
+ };
+ }
+
+ JNIEnv* env() {
+ return &env_;
+ }
+
+ JNIEnv* workerEnv() {
+ return &workerEnv_;
+ }
+
+ _jthrowable original;
+ _jthrowable secondary;
+ jthrowable pending{nullptr};
+ std::unordered_map<jobject, jthrowable> globalRefs;
+ int createdGlobalRefs{0};
+ int deletedGlobalRefs{0};
+ int deletedLocalRefs{0};
+ int pushedFrames{0};
+ int poppedFrames{0};
+ int releasedStrings{0};
+ int attaches{0};
+ int detaches{0};
+ bool workerAttached{false};
+ bool failGlobalRef{false};
+ bool failDescription{false};
+ bool failLocalFrame{false};
+ JNIEnv* deletingEnv{nullptr};
+
+ private:
+ JNINativeInterface_ functions_{};
+ JNIInvokeInterface_ invocation_{};
+ Env env_{this};
+ Env workerEnv_{this};
+ Vm vm_{this};
+ _jclass describer_;
+ _jstring description_;
+ const std::thread::id ownerThread_{std::this_thread::get_id()};
+};
+
+} // namespace gluten
diff --git a/docs/developers/NewToGluten.md b/docs/developers/NewToGluten.md
index f2591918eb..4e8affca0d 100644
--- a/docs/developers/NewToGluten.md
+++ b/docs/developers/NewToGluten.md
@@ -94,6 +94,55 @@ To format Java/Scala code using the
[Spotless](https://github.com/diffplug/spotl
./dev/format-scala-code.sh
```
+### Java exceptions crossing native code
+
+JNI callbacks must call `checkException(env)` after invoking Java. It throws
+`gluten::JavaException`, which owns a shared global reference to the original
Java
+throwable. `JNI_METHOD_END` restores that same object with JNI `Throw`,
retaining
+its class, cause, suppressed exceptions, stack trace, and structured Spark
error
+metadata. Native diagnostic formatting is best-effort after capturing the
throwable.
+If native carrier construction fails within a guarded JNI entry on the current
+thread, `checkException` restores the original throwable before local-reference
+cleanup unless a newer Java exception is pending. Without such an entry, it
clears
+pending JNI state before propagating the native failure so an attached worker
can
+be reused. Successfully captured carriers remain transferable across threads.
+Successful carrier propagation keeps JNI clear until the return boundary
restores
+the throwable.
+Do not replace this carrier with an exception constructed from `what()`.
+
+Same-object preservation applies at the JNI return boundary. Public iterator
+`hasNext()`/`next()` may apply existing Java wrappers, usually
`GlutenException`;
+existing schema-error translation also retains the original as a cause. Inspect
+the cause chain rather than assuming a top-level exception class or
`SparkThrowable`.
+These wrappers catch `Exception`, not every `Throwable`.
+
+Copies and `std::exception_ptr` instances keep the throwable alive until the
last
+owner releases it. Cleanup uses the current thread's JNI environment and
detaches
+only threads it attached itself. Failures while describing the captured
throwable
+do not replace it; if creating its global reference fails within a guarded JNI
+entry, the pending Java allocation error is preserved.
+
+`JNI_METHOD_END` also restores carriers inside standard `std::nested_exception`
+wrappers. Other native errors keep their existing `GlutenException` fallback.
+If carrier restoration leaves no pending Java exception, the boundary attempts
+that same fallback using the caught exception's diagnostic. A newer pending
Java
+exception is left untouched; failure to throw the fallback is logged.
+Backend-specific callback and output-boundary propagation is separate from this
+core contract; it does not by itself protect the full Velox driver path.
+Preserving the throwable does not merge Java and C++ frames into a hybrid stack
+trace (see [#9642](https://github.com/apache/gluten/issues/9642)).
+
+`gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java`
runs
+these cases through JUnit and Maven Surefire without starting Spark or a
backend.
+After configuring the native core, build its test-only bridge with
+`cmake --build cpp/build --target java_exception_jni_test`, then run
+`./build/mvn test -pl gluten-arrow -Pbackends-velox -Pspark-3.5 -Pjava-17
-Pjni-test`.
+The explicit `jni-test` profile requires the bridge in `cpp/build/test-libs`;
+a missing library fails the tests rather than skipping them. The existing
+`cpp-test-udf-test` CI job builds the bridge locally and enables this profile
in
+its Java 17 Maven step. No separate test artifact is needed, and the bridge is
+neither installed nor bundled in production jars.
+
### C++ code development
This guide is for remote debugging by connecting to the remote Linux server
using `SSH`.
diff --git a/gluten-arrow/pom.xml b/gluten-arrow/pom.xml
index 5b5f761c2f..54f8391041 100644
--- a/gluten-arrow/pom.xml
+++ b/gluten-arrow/pom.xml
@@ -278,4 +278,47 @@
<testOutputDirectory>target/scala-${scala.binary.version}/test-classes</testOutputDirectory>
</build>
+ <profiles>
+ <profile>
+ <id>exclude-jni-test</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <excludes combine.children="append">
+ <!-- The jni-test profile requires the separately built native
test bridge. -->
+ <exclude>**/JavaExceptionJniTest.java</exclude>
+ </excludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ <profile>
+ <id>jni-test</id>
+ <properties>
+
<gluten.jni.test.lib.dir>${project.basedir}/../cpp/build/test-libs</gluten.jni.test.lib.dir>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <failIfNoTests>true</failIfNoTests>
+ <forkedProcessTimeoutInSeconds>60</forkedProcessTimeoutInSeconds>
+ <systemPropertyVariables>
+
<gluten.jni.test.lib.dir>${gluten.jni.test.lib.dir}</gluten.jni.test.lib.dir>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
</project>
diff --git
a/gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java
b/gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java
new file mode 100644
index 0000000000..154487c462
--- /dev/null
+++ b/gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java
@@ -0,0 +1,310 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.gluten.jni;
+
+import org.apache.gluten.exception.GlutenException;
+
+import org.junit.AfterClass;
+import org.junit.Assert;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.File;
+import java.util.Collections;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+
+/** Tests the core JNI exception contract without starting Spark or a backend.
*/
+public final class JavaExceptionJniTest {
+ private static boolean libraryLoaded;
+
+ public interface Callback {
+ void run() throws Throwable;
+ }
+
+ private static final class StructuredException extends RuntimeException {
+ private final String errorClass;
+ private final Map<String, String> parameters;
+
+ private StructuredException(String errorClass, Map<String, String>
parameters) {
+ this.errorClass = errorClass;
+ this.parameters = parameters;
+ }
+ }
+
+ private static native int roundTrip(Callback callback, boolean nested);
+
+ private static native void roundTripWithFailedCapture(Callback callback,
Throwable failure);
+
+ private static native void roundTripOnWorker(
+ Callback callback, Callback nextCallback, Throwable captureFailure);
+
+ private static native int roundTripWithPendingException(
+ Callback callback, boolean nested, Throwable pending);
+
+ private static native int roundTripWithFailedRestore(
+ Callback callback, boolean nested, Throwable failure);
+
+ private static native void throwNativeException();
+
+ private static native void close();
+
+ private static native boolean entryActive();
+
+ @BeforeClass
+ public static void loadLibrary() {
+ String directory = System.getProperty("gluten.jni.test.lib.dir");
+ Assert.assertNotNull(
+ "Enable the jni-test Maven profile to configure the native bridge",
directory);
+ System.load(
+ new File(directory,
System.mapLibraryName("java_exception_jni_test")).getAbsolutePath());
+ libraryLoaded = true;
+ }
+
+ @AfterClass
+ public static void releaseReferences() {
+ if (libraryLoaded) {
+ close();
+ }
+ }
+
+ @Test
+ public void direct() {
+ preservesThrowable(false);
+ }
+
+ @Test
+ public void nested() {
+ preservesThrowable(true);
+ }
+
+ @Test
+ public void directRetainsAlreadyPendingException() {
+ retainsAlreadyPendingException(false);
+ }
+
+ @Test
+ public void nestedRetainsAlreadyPendingException() {
+ retainsAlreadyPendingException(true);
+ }
+
+ private static void retainsAlreadyPendingException(boolean nested) {
+ ArithmeticException original = new ArithmeticException("original callback
failure");
+ IllegalStateException newer = new IllegalStateException("newer pending
exception");
+ try {
+ roundTripWithPendingException(
+ () -> {
+ throw original;
+ },
+ nested,
+ newer);
+ Assert.fail("Expected the newer pending Java exception");
+ } catch (RuntimeException actual) {
+ Assert.assertSame(newer, actual);
+ }
+ preservesThrowable(nested);
+ }
+
+ @Test
+ public void failedDirectRestorationFallsBack() {
+ failedRestorationFallsBack(false);
+ }
+
+ @Test
+ public void failedNestedRestorationFallsBack() {
+ failedRestorationFallsBack(true);
+ }
+
+ private static void failedRestorationFallsBack(boolean nested) {
+ ArithmeticException original = new ArithmeticException("original callback
failure");
+ try {
+ roundTripWithFailedRestore(
+ () -> {
+ throw original;
+ },
+ nested,
+ null);
+ Assert.fail("Failed restoration must not return without a Java
exception");
+ } catch (GlutenException actual) {
+ Assert.assertSame(GlutenException.class, actual.getClass());
+ Assert.assertNull(actual.getCause());
+ if (nested) {
+ Assert.assertEquals("native wrapper", actual.getMessage());
+ } else {
+ Assert.assertTrue(actual.getMessage().contains("original callback
failure"));
+ }
+ }
+ preservesThrowable(nested);
+ }
+
+ @Test
+ public void failedDirectRestorationRetainsPendingError() {
+ failedRestorationRetainsPendingError(false);
+ }
+
+ @Test
+ public void failedNestedRestorationRetainsPendingError() {
+ failedRestorationRetainsPendingError(true);
+ }
+
+ private static void failedRestorationRetainsPendingError(boolean nested) {
+ OutOfMemoryError newer = new OutOfMemoryError("injected restoration
failure");
+ try {
+ roundTripWithFailedRestore(
+ () -> {
+ throw new ArithmeticException("original callback failure");
+ },
+ nested,
+ newer);
+ Assert.fail("Expected the newer pending Java exception");
+ } catch (OutOfMemoryError actual) {
+ Assert.assertSame(newer, actual);
+ }
+ preservesThrowable(nested);
+ }
+
+ private static void preservesThrowable(boolean nested) {
+ preservesThrowable(callback -> roundTrip(callback, nested));
+ }
+
+ private static void preservesThrowable(Consumer<Callback> invoke) {
+ StructuredException original =
+ new StructuredException("TEST_ERROR",
Collections.singletonMap("value", "original"));
+ Throwable cause = new IllegalStateException("original cause");
+ Throwable suppressed = new IllegalArgumentException("original suppressed
exception");
+ original.initCause(cause);
+ original.addSuppressed(suppressed);
+ StackTraceElement[] stack = original.getStackTrace();
+ try {
+ invoke.accept(
+ () -> {
+ throw original;
+ });
+ Assert.fail("Expected the original exception");
+ } catch (StructuredException actual) {
+ Assert.assertSame(original, actual);
+ Assert.assertSame(original.getClass(), actual.getClass());
+ Assert.assertSame(cause, actual.getCause());
+ Assert.assertEquals(1, actual.getSuppressed().length);
+ Assert.assertSame(suppressed, actual.getSuppressed()[0]);
+ Assert.assertArrayEquals(stack, actual.getStackTrace());
+ Assert.assertEquals("TEST_ERROR", actual.errorClass);
+ Assert.assertEquals(Collections.singletonMap("value", "original"),
actual.parameters);
+ }
+ }
+
+ @Test
+ public void failedCaptureRetainsPendingErrorAtJavaEntry() {
+ OutOfMemoryError newer = new OutOfMemoryError("injected global reference
failure");
+ try {
+ roundTripWithFailedCapture(
+ () -> {
+ throw new ArithmeticException("original callback failure");
+ },
+ newer);
+ Assert.fail("Expected the newer pending error at the Java return
boundary");
+ } catch (OutOfMemoryError actual) {
+ Assert.assertSame(newer, actual);
+ }
+ }
+
+ @Test
+ public void failedCaptureDoesNotPoisonReusedWorker() {
+ AtomicReference<Thread> worker = new AtomicReference<>();
+ int[] calls = {0};
+ try {
+ roundTripOnWorker(
+ () -> {
+ worker.set(Thread.currentThread());
+ throw new ArithmeticException("original worker failure");
+ },
+ () -> {
+ Assert.assertSame(worker.get(), Thread.currentThread());
+ calls[0]++;
+ },
+ new OutOfMemoryError("injected global reference failure"));
+ Assert.fail("Expected the native capture failure");
+ } catch (GlutenException actual) {
+ Assert.assertEquals(
+ "Unable to create global reference for Java exception",
actual.getMessage());
+ }
+ Assert.assertEquals(1, calls[0]);
+ Assert.assertNotSame(Thread.currentThread(), worker.get());
+ }
+
+ @Test
+ public void capturedWorkerThrowableSurvivesReuse() {
+ AtomicReference<Thread> worker = new AtomicReference<>();
+ int[] calls = {0};
+ preservesThrowable(
+ callback ->
+ roundTripOnWorker(
+ () -> {
+ worker.set(Thread.currentThread());
+ callback.run();
+ },
+ () -> {
+ Assert.assertSame(worker.get(), Thread.currentThread());
+ calls[0]++;
+ },
+ null));
+ Assert.assertEquals(1, calls[0]);
+ Assert.assertNotSame(Thread.currentThread(), worker.get());
+ }
+
+ @Test
+ public void nestedJavaReentryRestoresScope() {
+ Assert.assertFalse(entryActive());
+ roundTrip(
+ () -> {
+ Assert.assertTrue(entryActive());
+ normalReturn();
+ Assert.assertTrue(entryActive());
+ nativeOnly();
+ Assert.assertTrue(entryActive());
+ failedCaptureRetainsPendingErrorAtJavaEntry();
+ Assert.assertTrue(entryActive());
+ },
+ false);
+ Assert.assertFalse(entryActive());
+ preservesThrowable(false);
+ Assert.assertFalse(entryActive());
+ }
+
+ @Test
+ public void nativeOnly() {
+ try {
+ throwNativeException();
+ Assert.fail("Expected GlutenException");
+ } catch (GlutenException actual) {
+ Assert.assertSame(GlutenException.class, actual.getClass());
+ Assert.assertNull(actual.getCause());
+ Assert.assertEquals("native-only failure", actual.getMessage());
+ }
+ }
+
+ @Test
+ public void normalReturn() {
+ for (boolean nested : new boolean[] {false, true}) {
+ int[] calls = {0};
+ int result = roundTrip(() -> calls[0]++, nested);
+ Assert.assertEquals(42, result);
+ Assert.assertEquals(1, calls[0]);
+ }
+ }
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]