Thread Safety in JNI Function Calls
What is JNI development?
I used to do this kind of work, and after a former colleague raised some questions, I set aside time to dig into JNI development issues and one specific detail — thread safety of calls. JNI-layer calls are not that different from other languages calling into C/C++ — for example CGO between Go and C/C++ shares many of the same concerns.
JNI is Java’s native interface. With C/C++ (or other languages), compiled code inside the JVM can interact with native code outside it.
Java emphasizes portability. Native code looks like it breaks that promise, but it is often unavoidable — Java cannot implement every low-level capability.
What tools do you need for JNI?
On my machine I run OpenJDK 11 and GCC 11 on Linux. For editing I use VS Code with the Java, CMake, and C++ extensions.
Toolchain:
- OpenJDK 11
- GCC 11
- CMake 3.21
- Latest VS Code
Screenshot:

Why can’t OpenJDK find
javah? See JEP 313:javahwas removed.javaccan do the same job now:shelljavac -cp . -h abc MyCls.javaAssuming
MyCls.javain the current directory has native methods, this creates anabcdirectory with the C++ JNI header. You then write the matching C++ source.
Terminology
You can look up thread safety anywhere, and you may already know it, but here is a quick restatement:
A function is thread-safe if, when called concurrently from multiple threads, every caller still gets a correct result.
Main factors
Thread-safety problems appear when a call must mutate shared state.
That covers four cases:
- Static Java native call mutating shared C++ data
- Static Java native call mutating shared Java data
- Instance Java native call mutating shared C++ data
- Instance Java native call mutating shared Java data
Any shared data can create thread-safety issues.
Static vs instance native calls: if the native method is
static, it is a class-level call; otherwise it is an instance call.Shared C++ data means globals (or other globally reachable state). Shared Java data here means fields on a Java class or object that C++ reads or writes through JNI.
Walkthrough
Below is a small demo of JNI thread-safety issues.
Java side
The Java side is simple: declare a few native methods and call them from main:
class MyCls {
public static void main(String[] args) {
if (loadLibrary()) {
sayHello();
ConSt st = new ConSt();
threadSafe(st); // thread-safe as long as the passed-in st is unique per caller
System.out.println(mySafeInt);
System.out.println(st.mInt);
System.out.printf("unsafe int:%d\n", threadUnsafe());
MyCls obj = new MyCls();
obj.threadUnsafe2();
System.out.printf("unsafe int:%d\n", obj.myUnsafeInt);
}
}
// Load the C shared library
private static boolean loadLibrary() {
try {
System.loadLibrary("abc");
} catch(SecurityException e) {
e.printStackTrace();
return false;
} catch(UnsatisfiedLinkError e) {
e.printStackTrace();
return false;
}
return true;
}
private static long mySafeInt = 0;
private long myUnsafeInt = 0;
// Native interfaces
private static native void threadSafe(ConSt st);
private static native int threadUnsafe(); // uses shared C++ state with no locking
private native void threadUnsafe2(); // uses shared Java state with no locking
}
The heart of the demo is these three natives. threadSafe() could be split into two functions; in the C++ below I kept them together for brevity.
threadSafe() remains correct under any number of concurrent calls. threadUnsafe() and threadUnsafe2() are not thread-safe — under many threads you get scrambled results.
C/C++ side
std::mutex mu_thread_safe;
/*
* Class: MyCls
* Method: threadSafe
* Signature: (LConSt;)V
*/
JNIEXPORT void JNICALL Java_MyCls_threadSafe
(JNIEnv *env, jclass clz, jobject cons_st) {
// -- 1 -- Use a C++ mutex so the mutation is thread-safe
jfieldID _fieldId = env->GetStaticFieldID(clz, "mySafeInt", "J"); // static field on the class
mu_thread_safe.lock();
env->SetStaticLongField(clz, _fieldId, 12345); // mutex makes this safe
mu_thread_safe.unlock();
// -- 2 -- Pass state via a formal parameter; unique objects keep it thread-safe
jclass _cs_clz = env->FindClass("ConSt");
assert(_cs_clz != nullptr);
jfieldID _cs_fieldId = env->GetFieldID(_cs_clz, "mInt", "J");
env->SetLongField(cons_st, _cs_fieldId, 12345);
}
/*
* Class: MyCls
* Method: threadUnsafe
* Signature: ()V
*/
JNIEXPORT jint JNICALL Java_MyCls_threadUnsafe
(JNIEnv *, jclass) {
// -- 3 -- Shared C++ state mutated without locking — not thread-safe
static int _unsafe_int = 0;
_unsafe_int++; // no mutex
return _unsafe_int;
}
/*
* Class: MyCls
* Method: threadUnsafe2
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_MyCls_threadUnsafe2
(JNIEnv *env, jobject obj) {
// -- 4 -- Shared Java field mutated from C++ without locking — also not thread-safe
jclass _clz = env->FindClass("MyCls");
assert(_clz != nullptr);
jfieldID fieldId = env->GetFieldID(_clz, "myUnsafeInt", "J");
assert(fieldId != nullptr);
jlong myUnsafeInt = env->GetLongField(obj, fieldId) + 1;
env->SetLongField(obj, fieldId, myUnsafeInt);
}
In the first function, marker 1 uses a C++ mutex — that works, but under heavy concurrency it serializes everything and hurts throughput. Marker 2 is usually preferable: the caller passes a custom object, C++ mutates that object, and as long as each caller’s object is unique, concurrent results stay correct.
Markers 3 and 4 are counterexamples. Marker 3 mutates shared C++ state without locking; marker 4 is similar but the shared state lives in a Java field.
What is the fourth
signargument toGetFieldID()? It is the JNI type signature for that field. See the figure below (a screenshot from elsewhere); the official docs have the full table.
Summary
Thread safety means using shared resources carefully. Prefer not sharing at all — let callers pass the values to mutate. That usually works best.
Links: demo download
