Thread Safety in JNI Function Calls

November 29, 2021

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:

vscode

Why can’t OpenJDK find javah? See JEP 313: javah was removed. javac can do the same job now:

shell
javac -cp . -h abc MyCls.java

Assuming MyCls.java in the current directory has native methods, this creates an abc directory 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:

java
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

c++
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 sign argument to GetFieldID()? It is the JNI type signature for that field. See the figure below (a screenshot from elsewhere); the official docs have the full table.

sign

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