Foreign Function and Memory API - jextract

From Java, it is possible to exchange with the native world since JDK 1.1, JDK22 however, brings a newer approach that is both supported and safer to cross that bridge. Lets examine the key concepts of the FFM API and why it improves significantly the situation. Let's take a look at jextract as well, a tool to automate the mapping generation.

Transcript

1. Bridge Java to the native world FFM API and jextract Brice Dutheil
2. Bio Brice DUTHEIL est un ingénieur logiciel chez Datadog. Il a construit son expérience avec du backend type EJB/WAR/EAR, du Spring Boot, puis des pods kubernetes – d’abord en tant que développeur puis ingénieur de production – dans le secteur du transport et de la téléphonie avant de rejoindre Datadog. Il a également été un des gros contributeurs à Mockito. Aujourd'hui il travaille sur le développement de plugin pour les produits JetBrains. https://blog.arkey.fr https://twitter.com/BriceDutheil
3. Native access history Jogl (Java OpenGL) Gluegen generate bindings (java & C code) Opensourced in 2010 FFM (Foreign Function & Memory API) to bind to native libraries JDK 1.0 1996 Native interface ? JDK 1.1 1997 JNI (Java Native Interface) JDK 1.5 2004 JNA (Java Native Access) 2006 JDK 8 2014 JDK 22 2023-03 JNR (Java Native Runtime) 2010 JDK 7 2011 Method handles JExtract utility (Oracle) to Java generate bindings (source and/or bytecode) SWIG (Simplified Wrapper and Interface Generator) Covers more that C or Java JavaCPP generate bindings (java & C code) JEP: 472: Prepare to Restrict the Use of JNI
4. 2024-03-19 22 https://www.oracle.com/a/ocom/img/obic-java-cup.svg https://upload.wikimedia.org/wikipedia/commons/1/18/OpenJDK_logo.svg The people The Java spec version
5. JEP-454 : Foreign Function & Memory API Introduce an API by which Java programs can interoperate with code and data outside of the Java runtime. By efficiently invoking foreign functions (i.e., code outside the JVM), and by safely accessing foreign memory (i.e., memory not managed by the JVM), the API enables Java programs to call native libraries and process native data without the brittleness and danger of JNI. “
6. JEP-454 : Foreign Function & Memory API Introduce an API by which Java programs can interoperate with code and data outside of the Java runtime. By efficiently invoking foreign functions (i.e., code outside the JVM), and by safely accessing foreign memory (i.e., memory not managed by the JVM), the API enables Java programs to call native libraries and process native data without the brittleness and danger of JNI. Also part of the Panama Project Vector API 7th incubator (JEP-460) An API to express vectorized computation on supported CPU. “
7. 9 years in the making JEP-191 Foreign Function Interface JEP-338 Vector API (Incubator) JEP-370 Foreign Memory Access API (Incubator) JEP-383 Foreign Memory Access API (2nd Incubator) JEP-389 Foreign Linker API (Incubator) JEP-393 Foreign Memory Access API (3rd Incubator) JEP-414 Vector API (2nd Incubator) JEP-412 Foreign Function & Memory API JEP-417 Vector API (3nd Incubator) JEP-419 Foreign Function & Memory API (Second Incubator) JEP-424 Foreign Function & Memory API (Preview) JEP-426 Vector API (Fourth Incubator) JEP-434 Foreign Function & Memory API (Second Preview) JEP-438 Vector API (Fifth Incubator) JEP-442 Foreign Function & Memory API (Third Preview) JEP-448 Vector API (Sixth Incubator) JEP 454 Foreign Function & Memory API JEP 460 Vector API (Seventh Incubator) JDK 22 2014 2023
8. Why native ? Native functions are needed for various reasons • OS: interacting with devices, file systems, network interfaces, … • Third party libraries ◦ Unique feature, unique implementation, performance ▪ e.g. Harfbuzz
9. Why native ? Native functions are needed for various reasons • OS: interacting with devices, file systems, network interfaces, … • Third party libraries ◦ Unique feature, unique implementation, performance ▪ e.g. Harfbuzz, Libsodium, blake3
10. Why native ? Native functions are needed for various reasons • OS: interacting with devices, file systems, network interfaces, … • Third party libraries ◦ Unique feature, unique implementation, performance ▪ e.g. Harfbuzz, Libsodium, blake3, vectorscan, fswatch, tcmalloc, libVLC, CEF, clang, etc.
11. Why native ? Native functions are needed for various reasons • OS: interacting with devices, file systems, network interfaces, … • Third party libraries ◦ Unique feature, unique implementation, performance ▪ e.g. Harfbuzz, Libsodium, blake3, vectorscan, fswatch, tcmalloc, libVLC, CEF, clang, etc. ▪ OpenGL http://opening.download/spring-2021.html
12. JNI package q.r.s; class NativeBinding { static { System.load("path/to/libNative.so"); } public static native boolean isatty( int fileDescriptor ); } #include "q_r_s_Native.h" #include <unistd.h> JNIEXPORT jboolean JNICALL Java_q_r_s_NativeBinding_isatty( JNIEnv *env, jclass cls, jint fileDescriptor ) { return isatty(fileDescriptor)? JNI_TRUE: JNI_FALSE; } $ javac -d classes -cp src \ -h jni q/r/s/Native.java $ gcc \ -I $JAVA_HOME/include \ -I $JAVA_HOME/include/linux \ -fpic \ -shared \ -o libNative.so \ Native.c 🥇 Available since Java 1.1 🏎 Efficient 🏗 Complex and painful build ☣ Can terminate the JVM 💡 Before JDK10 use javah. See JEP-313
13. JNI The base of everything To call native code, the JVM must perform some tricks • Initialize a valid C stack • Initialize CPU register for the OS and CPU calling convention, and switch them back on return • Use CPU memory barrier instructions (fencing) • Prevent some JIT optimisations like inlining • If critical sections are declared (Get*Critical) prevent the GC to run at the very least on the impacted région • Data exchange (objects, arrays) likely require copy (unless in critical section) ◦ And likely serialization
14. JNI JNA package q.r.s; class NativeBinding { static { System.load("path/to/libNative.so"); } public static native boolean isatty( int fileDescriptor ); } #include "q_r_s_Native.h" #include <unistd.h> JNIEXPORT jboolean JNICALL Java_q_r_s_NativeBinding_isatty( JNIEnv *env, jclass cls, jint fileDescriptor ) { return isatty(fileDescriptor)? JNI_TRUE: JNI_FALSE; } $ javac -d classes -cp src \ -h jni q/r/s/Native.java $ gcc \ -I $JAVA_HOME/include \ -I $JAVA_HOME/include/linux \ -fpic \ -shared \ -o Native.so \ Native.c public interface JNA_Library extends Library { JNA_Library INSTANCE = (JNA_Library) Native.loadLibrary( "c", JNA_Library.class ); boolean isatty(int fileDescriptor); } 💪 Concept 1996, released 2006 📦 Third party 🎚 Easy to use, no C build 🚜 Versatile, not fast
15. Featureful JNA • Supports native types (wstring, structure, union, etc.) • Lots of reflection used for ease-of-use • Handles serialization, memory segments • Based upon JNI (invisible) to invoke its own native library • JNA Native lib will perform dispatch via libffi libffi is an assembly handwritten library that sets up the C callsite (c stack, registers)
16. JNI JNA JNR-FFI package q.r.s; class NativeBinding { static { System.load("path/to/libNative.so"); } public static native boolean isatty( int fileDescriptor ); } #include "q_r_s_Native.h" #include <unistd.h> JNIEXPORT jboolean JNICALL Java_q_r_s_NativeBinding_isatty( JNIEnv *env, jclass cls, jint fileDescriptor ) { return isatty(fileDescriptor)? JNI_TRUE: JNI_FALSE; } $ javac -d classes -cp src \ -h jni q/r/s/Native.java $ gcc \ -I $JAVA_HOME/include \ -I $JAVA_HOME/include/linux \ -fpic \ -shared \ -o Native.so \ Native.c public interface JNA_Library extends Library { JNA_Library INSTANCE = (JNA_Library) Native.loadLibrary( "c", JNA_Library.class ); boolean isatty(int fileDescriptor); } public interface IsATTY_JNRFFI { boolean isatty(int fileDescriptor); } import jnr.ffi.LibraryLoader; IsATTY_JNRFFI c = LibraryLoader .create(IsATTY_JNRFFI.class) .load("c"); 📦 Third party 🎚 Easy to use 🏎 Almost as fast as JNI
17. JNR-FFI Simple and faster than JNA • Supports native types (wstring, structure, union, etc.) • Handles classloader • Generates bytecode instead of reflection, way more efficient • Based upon JNI (invisible) to invoke its own native library • Also rely on libffi • Inspiration for JEP-191, and Project Panama
18. Foreign Function and Memory var linker = Linker.nativeLinker(); var lookup = linker.defaultLookup();
19. Foreign Function and Memory var linker = Linker.nativeLinker(); var lookup = linker.defaultLookup(); var isatty = lookup.find("isatty").orElseThrow();
20. Foreign Function and Memory var linker = Linker.nativeLinker(); var lookup = linker.defaultLookup(); var isatty = lookup.find("isatty").orElseThrow(); var isatty_MH = linker.downcallHandle(isatty, FunctionDescriptor.of( ValueLayout.JAVA_INT, ValueLayout.JAVA_INT ));
21. Foreign Function and Memory var linker = Linker.nativeLinker(); var lookup = linker.defaultLookup(); var isatty = lookup.find("isatty").orElseThrow(); var isatty_MH = linker.downcallHandle(isatty, FunctionDescriptor.of( ValueLayout.JAVA_INT, ValueLayout.JAVA_INT )); int result = isatty_MH.invokeExact(fileDescriptor); ☕ First party, made by Oracle 🎚 Easy to use 🏎 Faster than JNI Thanks to inlining and less conversions
22. Understand FFM API usage
23. JVM Restrictions JDK Team starting to enforce integrity and safety by default e.g. JDK 21, dynamic agent loading raise a warning, in later JDK disabled by default JNI might be restricted too Native memory must be explicitly enabled via cli or manifest (JDK 22) --enable-native-access=ALL-UNNAMED | {modules} Enable-Native-Access: ALL-UNNAMED ℹ JEP 472: Prepare to Restrict The Use of JNI: https://openjdk.org/jeps/472
24. Bad code can crash the VM # # A fatal error has been detected by the Java Runtime Environment: # # SIGSEGV (0xb) at pc=0x0000000104a0e9d8, pid=52896, tid=9987 # # JRE version: OpenJDK Runtime Environment (22.0+26) (build 22-ea+26-2112) # Java VM: OpenJDK 64-Bit Server VM (22-ea+26-2112, mixed mode, sharing, tiered, compressed oops, compressed class ptrs, g1 gc, bsd-aarch64) # Problematic frame: # V [libjvm.dylib+0x9b69d8] Unsafe_GetByte(JNIEnv_*, _jobject*, _jobject*, long)+0x14c # # No core dump will be written. Core dumps have been disabled. To enable core dumping, try "ulimit -c unlimited" before starting Java again # # An error report file with more information is saved as: # /Users/brice.dutheil/opensource/panama-watch/hs_err_pid52896.log # # If you would like to submit a bug report, please visit: # https://bugreport.java.com/bugreport/crash.jsp #
25. Foreign Function and Memory Suppose the printf function
26. Foreign Function and Memory Suppose the printf function Standard libc function are documented in man pages man 3 printf
27. Foreign Function and Memory Suppose the printf function Standard libc function are documented in man pages man 3 printf
28. Foreign Function and Memory The printf is very similar to System.out.printf, 1. A format string 2. Variable arguments
29. Foreign Function and Memory The printf is very similar to System.out.printf System.out.printf("%-10.3f%n", pi); printf("%-10.3f\n", pi);
30. Simplified call without format arguments: printf("printed to stdout") Foreign Function and Memory var printf = LINKER.downcallHandle( SYMBOL_LOOKUP.find("printf").orElseThrow(), FunctionDescriptor.of( ValueLayout.JAVA_LONG, ValueLayout.ADDRESS ) );
31. The process And then …handling memory The JVM The Over Simplified “memory chart” ™ A native lib Java heap message
32. The process And then …handling memory The JVM A native lib Java heap message 1. Allocate new Off-heap segment of memory and copy content message The Over Simplified “memory chart” ™
33. The process And then …handling memory The JVM A native lib Java heap message 2. Pass the pointer of native segment to function function message The Over Simplified “memory chart” ™
34. The process And then …handling memory The JVM A native lib Java heap message Now there’s litter in the process memory ? function message The Over Simplified “memory chart” ™
35. Foreign Function and Memory 4 concepts to grasp • Arenas : allow memory lifecycle management, form allocation to disposal • Memory segments : a contiguous region of bytes • Memory layouts : data model in a memory segment • MethodHandle, VarHandle : polymorphic glue to access native function & memory
36. Foreign Function and Memory • FFM API is designed in a way to prevent misuse for memory in particular. • FFM comes with Arenas, they control the lifecycle of native memory segments. ◦ Multiple characteristics are available ▪ Global ⟹ Deallocation ❌ ▪ Automatic ⟹ Deallocation❓ (when GC is passing by) ▪ Confined ⟹ Deallocate at close 🚧 Singled 🧵 ▪ Shared ⟹ Deallocate at close 🚧, Shared by multiple 🧵🧵🧵🧵… ◦ Implementing custom memory management is possible, ▪ Interfaces: Arena ➝ SegmentAllocator
37. For the printf example, let’s create a confined arena Foreign Function and Memory try (var arena = Arena.ofConfined()) { }
38. For the printf example, then let’s allocate and copy Java string content Foreign Function and Memory try (var arena = Arena.ofConfined()) { var memorySegment = arena.allocateFrom(str); }
39. For the printf example, then make the call Foreign Function and Memory try (var arena = Arena.ofConfined()) { var memorySegment = arena.allocateFrom(str); return (long) printf.invoke(memorySegment); }
40. For the printf example, then make the call Foreign Function and Memory try (var arena = Arena.ofConfined()) { var memorySegment = arena.allocateFrom(str); return (long) printf.invoke(memorySegment); } Deallocation when closed
41. MemorySegment Represents a contiguous “segment” of bytes, on-heap or off-heap All segments have a start address in memory, this value is used as the pointer Accessible via MemorySegment::address All segments have a size Accessible via MemorySegment::byteSize A segment with a zero-length is an address
42. MemorySegment Represents a contiguous “segment” of memory The process The JVM A native lib Java heap 2E502E2E A0FB992E function Segments of memory The Over Simplified “memory chart” ™
43. Pointers everywhere Pointers are links to everything Even native functions are actually memory address Actually an address, returns a zero-length MemorySegment var printf = LINKER.downcallHandle( SYMBOL_LOOKUP.find("printf").orElseThrow(), FunctionDescriptor.of( ValueLayout.JAVA_LONG, ValueLayout.ADDRESS ) );
44. MemorySegment Represents a contiguous “segment” of memory The process The JVM A native lib Java heap 2E502E2E A0FB992E function Segments of memory 0-length The Over Simplified “memory chart” ™
45. Exchanging structured data Passing strings and raw types is almost easy as usual factories are there, e.g. allocateFrom(elementLayout, elementsArray) Fun begin with complex layout, use MemoryLayout factories
46. Exchanging structured data typedef struct { uint8_t buf_len; uint8_t flags; } basic_struct; MemoryLayout.structLayout( JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags"), ).withName("basic_struct"); uint8_t buf[8]; MemoryLayout.sequenceLayout( 64, JAVA_BYTE ).withName("buf") typedef struct { uint8_t buf[8]; uint8_t buf_len; uint8_t flags; } basic_struct; MemoryLayout.structLayout( bufLayout, JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags"), ).withName("basic_struct");
47. Exchanging structured data Passing strings and raw types is almost easy as usual factories are there, e.g. allocateFrom(elementLayout, elementsArray) Fun begins with complex layout, use MemoryLayout factories • structLayout(…), structure like • sequenceLayout(…), array like • unionLayout(…), allow different structs over the same storage • paddingLayout(…), padding require understanding of what means alignment
48. Exchanging structured data Structured access to elements basic_struct_LAYOUT = MemoryLayout.structLayout(bufLayout, JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags") ).withName("basic_struct");
49. Exchanging structured data Structured access to elements basic_struct_LAYOUT = MemoryLayout.structLayout(bufLayout, JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags") ).withName("basic_struct"); VarHandle flags = basic_struct_LAYOUT.varHandle( MemoryLayout.PathElement.groupElement("flags"));
50. Exchanging structured data Structured access to elements basic_struct_LAYOUT = MemoryLayout.structLayout(bufLayout, JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags") ).withName("basic_struct"); VarHandle flags = basic_struct_LAYOUT.varHandle( MemoryLayout.PathElement.groupElement("flags")); flags.get(memorySegment, 0L); flags.set(memorySegment, 0L, (byte) 0x2); storage Base offset in segment value
51. Exchanging structured data Structured access to elements basic_struct_LAYOUT = MemoryLayout.structLayout(bufLayout, JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags")).withName("basic_struct"); VarHandle flags = basic_struct_LAYOUT.varHandle( MemoryLayout.PathElement.groupElement("flags")); flags.get(memorySegment, 0L); flags.set(memorySegment, 0L, (byte) 0x2); Notice the enforced type
52. Exchanging structured data Structured access to elements basic_struct_LAYOUT = MemoryLayout.structLayout(bufLayout, JAVA_BYTE.withName("buf_len"), JAVA_BYTE.withName("flags")).withName("basic_struct"); VarHandle flags = basic_struct_LAYOUT.varHandle( MemoryLayout.PathElement.groupElement("flags")); flags.get(memorySegment, 0L); flags.set(memorySegment, 0L, (byte) 0x2); Exception in thread "main" java.lang.invoke.WrongMethodTypeException: cannot convert MethodHandle(VarHandle,MemorySegment,long,byte)void to (VarHandle,MemorySegment,int)void Notice the enforced type, WrongMethodTypeException if incorrect
53. Day to day tips
54. Loading libraries Standard or common libraries are already loaded by the JVM process • Nothing to do • Symbols are available via Linker.nativeLinker().defaultLookup() e.g. printf, isatty, etc. SYMBOL_LOOKUP = Linker.nativeLinker().defaultLookup() SYMBOL_LOOKUP.find("symbol") Tied to symbol lookup
55. Loading libraries JNI library loading mechanism via System::load or System::loadLibrary • ⚠ Lifecycle tied to the classloader • Library and symbols can only be “appearing” once SYMBOL_LOOKUP = SymbolLookup.loaderLookup() SYMBOL_LOOKUP.find("symbol")
56. Loading libraries FFM API has a flexible loading mechanism • Not tied to classloader, but to an Arena, that can be explicitly controlled SYMBOL_LOOKUP = SymbolLookup.libraryLookup("path/to/libblake3.so", LIBRARY_ARENA) SYMBOL_LOOKUP.find("symbol") Usually LIBRARY_ARENA = Arena.ofAuto();
57. Loading libraries FFM API has a flexible loading mechanism • Not tied to classloader, but to an Arena, that can be explicitly controlled • Composable lookup SYMBOL_LOOKUP = SymbolLookup.libraryLookup("path/to/libblake3.so", LIBRARY_ARENA) .or(SymbolLookup.loaderLookup()) .or(Linker.nativeLinker().defaultLookup()); SYMBOL_LOOKUP.find("symbol")
58. Handling error in C with errno errno is like a global error state in the C standard library, • it’s an integer variable set by the function that was called https://man7.org/linux/man-pages/man3/errno.3.html
59. Handling error in C with errno errno is like a global error state in the C standard library, • it’s an integer variable set by the function that was called https://man7.org/linux/man-pages/man3/errno.3.html ioctl = LINKER.downcallHandle( SYMBOL_LOOKUP.find("ioctl").orElseThrow(), ioctlFunctionDescriptor, ); result = (int) ioctl.invokeExact(…)
60. Handling error in C with errno errno is like a global error state in the C standard library, • it’s an integer variable set by the function that was called https://man7.org/linux/man-pages/man3/errno.3.html ioctl = LINKER.downcallHandle( SYMBOL_LOOKUP.find("ioctl").orElseThrow(), ioctlFunctionDescriptor, Linker.Option.captureCallState("errno") ); var csl = Linker.Option.captureStateLayout(); var errnoHandle = csl.varHandle( PathElement.groupElement("errno") ); result = (int) ioctl.invokeExact(…)
61. Handling error in C with errno errno is like a global error state in the C standard library, • it’s an integer variable set by the function that was called https://man7.org/linux/man-pages/man3/errno.3.html ioctl = LINKER.downcallHandle( SYMBOL_LOOKUP.find("ioctl").orElseThrow(), ioctlFunctionDescriptor, Linker.Option.captureCallState("errno") ); var csl = Linker.Option.captureStateLayout(); var errnoHandle = csl.varHandle( PathElement.groupElement("errno") ); var storage = arena.allocate(csl); result = (int) ioctl.invokeExact(storage, …) switch ((int) errnoHandle.get(storage, 0L)) { 25 -> … // ENOTTY }
62. MethodHandles As you noticed, this API relies a lot on invokedynamic features. • VarHandle • MethodHandle This means we benefit from all the features • binding arguments (similar to currying) • Interception • etc. and it’s errors • WrongMethodTypeException in particular
63. Bad code example using printf Foreign Function and Memory try (var arena = Arena.ofConfined()) { var memorySegment = arena.allocateFrom(str); return (long) printf.invoke(memorySegment.address()); } Wrong
64. Understanding WrongMethodTypeException If WrongMethodTypeException shows up, read the message Exception in thread "main" java.lang.invoke.WrongMethodTypeException: handle's method type (MemorySegment)long but found (long)long at java.base/java.lang.invoke.Invokers.newWrongMethodTypeException(Invokers.java:521) at java.base/java.lang.invoke.Invokers.checkExactType(Invokers.java:530) at io.whatever.App.c_printf(App.java:41)
65. Understanding WrongMethodTypeException handle's method type (MemorySegment)long Indicates what was described in the descriptor but found (long)long Indicates what was seen on call site FunctionDescriptor.of( ValueLayout.JAVA_LONG, ValueLayout.ADDRESS ) ℹ ValueLayout.ADDRESS carrier type is MemorySegment (long) printf .invokeExact(segment.address());
66. Variadic function in the MethodHandle section E.g. int printf(const char * restrict format, ...) • It’s not really supported in the JDK • JDK team opted for specialized downcall ◦ new downcall declaration for new sequence of argos • JDK advocate use of jextract for this feature to work. • Required to declare the downcallHandle with the index of the first variadic param LINKER.downcallHandle(…, Linker.Option.firstVariadicArg(2));
67. Interacting with non-C language Linker and SymbolLookup works with C conventions Foreign code needs to visible as a C function …(usually declared with extern) Swift @_cdecl("authenticate_user_touchid") public func authenticateUserApi() { … } Rust #[no_mangle] pub extern "C" fn abort() { … } Objective-C extern void cameraCapture(); Also look at cbindgen to generate C binding first https://jornvernee.github.io/java/panama/rust/panama-ffi/2021/09/03/rust-panama-helloworld.html
68. Graalvm native-image support Currently baking, e.g. in JDK 21 preview API • Missing features: variadic functions, shared arenas, upcalls, etc. • Requires some special configuration at build time https://www.graalvm.org/latest/reference-manual/native-image/native-code-interoperability/foreign-interface/ class FFMRegistrationFeature implements Feature { public void duringSetup(DuringSetupAccess access) { RuntimeForeignAccess.registerForDowncall( FunctionDescriptor.ofVoid() ); RuntimeForeignAccess.registerForDowncall( FunctionDescriptor.ofVoid(), Linker.Option.isTrivial() ); … } } --features=com.example.FFMRegistrationFeature -H:+UnlockExperimentalVMOptions -H:+ForeignAPISupport --enable-native-access=ALL-UNNAMED native-image.properties
69. About sun.misc.Unsafe Used for low level concurrency library, and others • Netty (used by quarkus), Akka, Hazelcast, Apache Spark, Java based implementation of some codecs JDK developers aim to remove it at some point …but alternative supported API are not yet performant enough JEP 471: Deprecate the Memory-Access Methods in sun.misc.Unsafe for Removal A collection of methods for performing low-level, unsafe operations.
70. Automating with jextract
71. Binding Automation: JavaCPP Supports rich C++ constructs Generation at build time Configuration medium : Java class Existing binding (javacpp-presets)
72. Binding Automation: jextract https://twitter.com/devoxx/status/1715655857797550378 External CLI tool Supports C/C++ constructs • Even complex declarations • No C code generated Maintained by JDK team ⚠ Stable but still as mentions early access
73. Binding Automation: jextract Navigate to https://jdk.java.net/jextract/ ℹ Possibly add the executable permission : chmod +x jextract-22/jextract Or remove macOs quarantine flags : sudo xattr -r -d com.apple.quarantine jextract-22/jextract/
74. Basic usage If you have a simple library $ jextract \ --target-package org.lib \ --header-class-name Lib \ lib.h org.lib.Lib
75. Generated code E.g. with BLAKE3/c/blake3.h (and --header-class-name blake3_h) Generated API usage var hasher = blake3_hasher.allocate(arena); blake3_h.blake3_hasher_init(hasher); var content = arena.allocateFrom("Hello Panama!"); blake3_h.blake3_hasher_update( hasher, content, content.byteSize() - 1 ); allocate returns MemorySegment with the blake3_hasher struct layout Functions and other symbols exposed as statics under blake3_h
76. Generated code E.g. with BLAKE3/c/blake3.h (and --header-class-name blake3_h) /** * {@snippet lang=c : * struct { * uint32_t key[8]; * blake3_chunk_state chunk; * uint8_t cv_stack_len; * uint8_t cv_stack[1760]; * } * } */ public class blake3_hasher { … /** * {@snippet lang=c : * void blake3_hasher_init(blake3_hasher *self) * } */ public static void blake3_hasher_init(MemorySegment self) { …
77. Configuring library loading Is library on system library path? If yes Specify shared lib name $ jextract … \ --library GL \ --library GLU \ … Lookup will look for standard locations /usr/lib /usr/lib64 /lib /lib64 ├── libGL.so └── libGLU.so /usr/local/lib /usr/local/lib64 generates SymbolLookup.libraryLookup(System.mapLibraryName("GL"), …); SymbolLookup.libraryLookup(System.mapLibraryName("GLU"), …);
78. Or, prefix path with a colon : Configuring library loading Is library on system library path ? If no, either don’t pass --library flag, and load the library yourself before using bindings. Specify library path $ jextract … \ --library :path/to/libblake3.so \ … SymbolLookup.libraryLookup("path/to/libblake3.so", …) Explicit load SymbolLookup.libraryLookup( "path/to/libblake3.so", … ); // Then use generated bindings generates Note the colon
79. Dealing with includes Add include dirs $ jextract \ --target-package org.lib \ --include-dir path1/to/include \ --include-dir path2/to/include \ lib.h E.g. Specific library include path : /usr/local/Cellar/ffmpeg@4/4.4.4/include Or system includes macOs: /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/ …or: /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include Linux: /usr/include/ lib.h #include "relative/path1/a.h" #include "relative/path2/b.h" …
80. Multiple headers Juste create a synthetic single header file Declare every included headers Pass synthetic header $ jextract …\ my-multiple.h my-multiple.h #include "path/to/libOneThing.h" #include "path/to/libOtherThing.h" …
81. Choose generated binding explicitly Dumping symbol include configuration Dump all symbols first $ jextract … \ --dump-includes my-dump.txt \ blake3.h
82. Choose generated binding explicitly How to be specific about which symbol ? Dump all symbols first $ jextract … \ --dump-includes my-dump.txt \ blake3.h my-dump.txt … #### Extracted from: …/blake3.h --include-struct blake3_chunk_state # header: …/c/blake3.h --include-struct blake3_hasher # header: …/blake3.h … --include-struct --include-function --include-constant --include-typedef --include-union --include-var
83. Choose generated binding explicitly How to be specific about which symbol ? Dump all symbols first $ jextract … \ --dump-includes my-dump.txt \ blake3.h my-dump.txt … #### Extracted from: …/blake3.h --include-struct blake3_chunk_state # header: …/c/blake3.h --include-struct blake3_hasher # header: …/blake3.h … Selected “symbols” $ jextract … \ --include-struct blake3_chunk_state \ --include-struct blake3_hasher \ blake3.h Select which symbol should have a binding
84. Use a argument file Like the java command, jextract supports arguments file my-config.txt $ jextract … \ @my-config.txt --output path/to/gen-sources/jextract-blake3/java --target-package blake3 --header-class-name blake3_h --include-struct blake3_chunk_state # header: …/c/blake3.h --include-struct blake3_hasher # header: …/blake3.h … blake3.h
85. Caution Native headers may not be platform independent • OS specific macros (preprocessed by the C preprocessor before the binding) • Imprecise C types, e.g. long (different length depending on the platform), Precise types: int64_t, long long (instead of long) JExtract may produce bindings that may behave incorrectly on other platforms. ➡ Double check, jextract’s generated code on other platform, if unsure about library ☣ ℹ OpenGL is even more tricky, check out PanamaGL : https://gitlab.com/jzy3d/panama-gl (needs contributors)
86. JEP 454: Foreign Function & Memory API Javadoc JDK 22 java.base/java.lang.foreign Oracle Devguide for JDK 21: Foreign Function and Memory API JExtract : https://github.com/openjdk/jextract • From C to Java Code using Panama by Johannes Bechberger • The Panama Dojo: Black Belt Programming with Java 21 & the FFM API by Per Minborg • JVMLS: Project Panama - Foreign Function & Memory API by Maurizio Cimadamore Some projects • Vulkan on macOs : GitHub - chengenzhao/java-vulkan-mac Foreign Function and Memory API - jextract