Say Hello to Panama
With JEP-454, the Foreign Function & Memory (FFM) API became a stable feature. Starting with JDK 22, developers can use this API with no extra configuration or "hassle." This article looks at how the FFM API makes working with native libraries simpler and improves performance.
With JEP-454, the Foreign Function & Memory (FFM) API became a stable feature. Starting with JDK 22, developers can use this API with no extra configuration or “hassle.” This article looks at how the FFM API makes working with native libraries simpler and improves performance.
Setup
The code is in Java, but I ran it with Scala-CLI because it keeps things simple. The benchmarks ran on an Intel(R) Xeon(R) @ 2.20GHz machine with 4 vCPUs (2 cores), 16GB RAM, on Debian GNU/Linux 12 (bookworm) with the OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS).
Example
To illustrate these advantages, I’ll use the pow function from the libm.so library. For a fair comparison, let’s first see how this function is called through the classic JNI API.
JNI
Calling a native function through the JNI API involves a number of manual steps.
To begin, we declare a Java method with the native keyword, which acts as a stand-in for the native implementation:
public static native double calculate(double base, double exponent);
The example uses a static method, but that isn’t strictly necessary. Still, whether the method is static or not affects which parameters are passed to the native function (more on this shortly).
Then we generate a C/C++ header file with the Java compiler. This file serves as the “bridge” between Java and C:
javac -h native/ src/main/java/methods/JNIPowerCalculator.java
This command tells the Java Compiler to look for native methods in JNIPowerCalculator.java and write a header file to the native/ directory. For our function, the resulting declaration is:
JNIEXPORT jdouble JNICALL Java_methods_JNIPowerCalculator_calculate
(JNIEnv *, jclass, jdouble, jdouble);
JNIEXPORT– a macro that makes the function visible to the JVM.jdouble– the return type as mapped by JNI (the counterpart of Java’s double).JNICALL– a macro that guarantees the right calling convention (which differs across operating systems, e.g. Windows vs. Linux).Java_methods_JNIPowerCalculator_calculateis the method name, which must obey a strict naming convention:
a) Java_
b) package_
c) class_
d) method name
JNIEnv *– a pointer to the JNI environment, used for interacting with the JVM (e.g. to create Java objects or throw exceptions).jclass– a reference to the class that contains the method. For a non-static method, this parameter would instead be ajobject(a reference to the particular instance).- Finally, there are two
jdoublearguments, which are the function’s arguments.
Next comes the actual C implementation, which here simply delegates to the standard math library:
JNIEXPORT jdouble JNICALL Java_methods_JNIPowerCalculator_calculate
(JNIEnv *env, jclass clazz, jdouble base, jdouble exponent) {
return pow(base, exponent);
}
Lastly, the C code has to be compiled into a shared library that the JVM is able to load:
gcc -shared -fPIC \
-I"$JAVA_HOME/include" \
-I"$JAVA_HOME/include/linux" \
native/PowerCalculator.c -o lib/libnative-power-calculator.so -lm
-shared– produces a shared library (.so) rather than an executable.-fPIC– producesPosition Independent Code, which shared libraries on Linux need so that they can be loaded at any memory address without clashes.-I– points the compiler to the required header files.-o– sets the output path and file name.-lm– links in the standard math library (m), so that the pow function can be used.
Clearly, even calling a trivial native function takes a lot of “boilerplate” code and external tools. There’s no way to call the native function directly – you have to write and compile a wrapper that satisfies JNI’s strict naming and parameter rules.
Let’s now see how the FFM API has changed things.
Project Panama
Thanks to the Foreign Function & Memory (FFM) API, the very same pow function can be called purely from Java, with no C “glue” code at all. It all begins with obtaining a MethodHandle. Sample code could look like this:
public class PanamaPowerCalculator {
private static final MethodHandle METHOD_HANDLE;
static {
(1) Linker linker = Linker.nativeLinker();
Map<String, MemoryLayout> layouts = (3) linker.canonicalLayouts();
(5) MemorySegment symbol = linker.defaultLookup().find("pow").get();
(2) ValueLayout cDouble = (ValueLayout) layouts.get("double");
(4) FunctionDescriptor fd = FunctionDescriptor.of(cDouble, cDouble, cDouble);
(6) METHOD_HANDLE = linker.downcallHandle(symbol, fd);
}
...
}
Linker– gives access to foreign functions.ValueLayout– describes the size and alignment of basic data types, e.g. Integer, Long, ….canonicalLayouts– supplies the standard layouts of C data types for the underlying operating system and processor. This matters because they can differ between operating systems, e.g.: on Windows a long is typically 32 bits, whereas on Linux it’s 64 bits.FunctionDescriptor– describes the foreign function’s signature. The first argument is the layout of the return type, and the next two are the layouts of the arguments.MemorySegment– gives access to contiguous regions of memory – here, to thepowfunction.MethodHandle– a reference to a foreign function that can be executed directly.
The example above performs a downcall (invoking a native function from Java). Notably, the FFM API supports the opposite direction too: upcalls.
With an upcallStub, a Java method handle can be handed to native code as a function pointer, letting C code “call back” into your Java application. This article, however, deals only with the downcall case.
After the MethodHandle has been initialized for a downcall, it can be executed with either the invoke or the invokeExact method.
The invoke method is forgiving. When the arguments you pass don’t exactly match the FunctionDescriptor, the JVM tries to convert the types automatically before making the native call.
public static double calculateInvokeWithConversion(int base, int exponent) {
try {
return (double) METHOD_HANDLE.invoke(base, exponent);
} catch (Throwable t) {
throw new RuntimeException(t);
}
}
The invokeExact method, on the other hand, demands that the types match the FunctionDescriptor precisely. Passing an argument of the wrong type results in an immediate WrongMethodTypeException.
public static double calculateInvokeExact(double base, double exponent) {
try {
return (double) METHOD_HANDLE.invokeExact(base, exponent);
} catch (Throwable t) {
throw new RuntimeException(t);
}
}
The FFM approach is considerably cleaner and easier to maintain than JNI. It does away with C headers, external compilers and “glue” code, so all the logic stays inside the Java ecosystem.
Can we go even further, though? The next section shows how jextract can automate the whole process.
Jextract
Hand-writing the MethodHandle and FunctionDescriptor logic is fine for a single function such as pow, but for bigger libraries it gets tedious and error-prone. That’s where jextract steps in.
The jextract tool automatically generates Java bindings from the headers of native libraries. Notably, although it started out inside the OpenJDK, it’s now maintained as a standalone tool so that it can evolve independently of the main JDK release cycle.
You’ll need the jextract binary to use it. This command generates a Java wrapper for the pow function:
jextract --output src/main/java \
-t math \
/usr/include/math.h \
--header-class-name NativeMath \
--include-function pow
--output– the target directory for the generated source files.-t– the name of the target Java package./usr/include/math.h– the header file to parse.--header-class-name– the name of the Java class that will contain the native methods.--include-function– narrows down what gets generated. Without it,jextractwould try to generate bindings for every function inmath.h.
Usually, the command produces two main files:
- NativeMath.java – exposes the high-level Java methods that you call directly, serving as the main interface to the native library.
- NativeMath$shared.java – holds the behind-the-scenes “plumbing”, such as memory layouts, which tells the JVM how to deal with native data types.
With JNI, hand-written Panama and jextract-generated Panama covered, let’s compare how they perform and check whether the “boilerplate” really affects speed.
Comparison
To measure how efficient these approaches are, I ran a JMH benchmark comparing five implementations:
- JNI API: The classic native bridge.
- Panama
invokeExact. - Panama
invoke(With Conversion):intarguments passed to adoublesignature. - Panama
invoke(Matching Types):doublearguments passed directly - jextract: Relying on the auto-generated bindings.
Results of the benchmark:
Benchmark Mode Cnt Score Error Units
NativeMethodCallBenchmark.benchmark_JNI_Power_Calculator avgt 15 34.659 ? 0.198 ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Exact_Power_Calculator avgt 15 29.541 ? 0.222 ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_With_Conversion_Power_Calculator avgt 15 34.310 ? 0.312 ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Without_Conversion_Power_Calculator avgt 15 29.554 ? 0.138 ns/op
NativeMethodCallBenchmark.benchmark_Panama_J_Extract_Power_Calculator avgt 15 29.413 ? 0.067 ns/op
According to the results, invokeExact, invoke (with matching types) and jextract come out on top, practically level at ~29.5 ns. The remaining options are about 5ns (17%) slower.
That 29.5 ns, however, also covers the time spent on the pow calculation itself in libm.so. To find the real cost of the Java-to-native transition, I ran the benchmark with the perfasm profiler:
scala-cli . --jmh --power -- -f 1 -prof "perfasm:events=cpu-clock;intel=true"
The profiler’s overhead made the numbers slightly different, but the overall pattern stayed the same:
Benchmark Mode Cnt Score Error Units
NativeMethodCallBenchmark.benchmark_JNI_Power_Calculator avgt 5 35.050 ? 3.193 ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Exact_Power_Calculator avgt 5 30.336 ? 7.101 ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_With_Conversion_Power_Calculator avgt 5 36.807 ? 12.709 ns/op
NativeMethodCallBenchmark.benchmark_Panama_Invoke_Without_Conversion_Power_Calculator avgt 5 29.660 ? 0.335 ns/op
NativeMethodCallBenchmark.benchmark_Panama_J_Extract_Power_Calculator avgt 5 30.168 ? 6.217 ns/op
The profiler output showed that the math operation itself in libm.so takes about 17 ns. Subtracting this “work time” from the totals gives:
- Overhead of Panama: ~12.5 ns
- Overhead of JNI/Conversion: ~17.5 ns
Seen this way, the fastest Panama solutions beat the slower ones by about 30% in pure call overhead.
Naturally, this applies only to such a simple example. If our native library did other kinds of work, the gain would be somewhat larger or smaller, depending on how “work” compares to “call overhead”. Still, let’s try to understand why some solutions are faster than the others.
Performance analysis
To simplify debugging with jhsdb, I added a Main class to the project. The code the JIT compiles in a regular application isn’t always the same as JMH’s heavily optimized code, but it gives a good view of how the JVM deals with these calls.
The assembly generated for the three fastest solutions (invokeExact, invoke – without conversion, and jextract) is very much alike:
0x00007fa5dfef0166: movabs $0x7fa5f7a682b0,%rsi
...
0x00007fa5dfef0178: movabs $0x7157a5328,%rdx
0x00007fa5dfef0182: nop
0x00007fa5dfef0183: call 0x00007fa5dfede980
- The
rsiregister contains the memory address of thepowfunction. - The
rdxregister contains theNativeEntryPointaddress. - NativeEntryPoint keeps a reference to nep_invoker_blob, a dedicated stub that performs the transition into the native function with very few extra instructions.
With JNI, the JVM produces a native_wrapper. Like the nep_invoker_blob, it bridges the JVM and the foreign function, but it is far less optimized. On top of that, our own C wrapper brings an extra layer of overhead that the JIT is unable to optimize away.
With invoke and type conversion, the route to the native function is much longer. It does end up calling the nep_invoker_blob, but the JIT compiler can’t apply the same aggressive optimizations, since it has to generate logic that converts the data types before they cross the native boundary.
Conclusion
The Foreign Function & Memory (FFM) API makes interacting with native libraries considerably simpler. As our benchmarks show, this simplicity also brings better performance. Because the JIT compiler can optimize the call path directly, the FFM API cuts call overhead by about 30% (as shown above) compared to classic JNI.
Whether you rely on jextract for automation or on MethodHandle for manual control, you end up with a faster, safer and easier-to-maintain way of using native code in modern Java.
I hope this article proves useful to you.