JDK 22: added example of FFM API to call native code

Author: wesleyegberto

.gitignore

@@ -16,4 +16,5 @@ hs_err_pid*
 .DS_Store
 *.data
 jdt.ls-java-project/
-*.dmg
+*.dmg
+*.so

java-22/ForeignFunctionAndMemoryApiAllocationTest.java

@@ -4,13 +4,14 @@
 import java.util.*;
 
 /**
- * To run: `java --enable-preview --source 22 ForeignFunctionAndMemoryApiAllocationTest.java`
+ * To run: `java --source 22 ForeignFunctionAndMemoryApiAllocationTest.java`
  */
 public class ForeignFunctionAndMemoryApiAllocationTest {
 	public static void main(String[] args) {
 		memorySegmentAllocationExample();
 		memorySegmentStructManualAllocation();
 		memorySegmentStructAutoAllocation();
+		memorySegmentUsingSegmentAllocator();
 	}
 
 	static void memorySegmentAllocationExample() {
@@ -82,4 +83,15 @@ static void memorySegmentStructAutoAllocation() {
 			yHandle.set(segment, 0L, i, value);
 		}
 	}
+
+	static void memorySegmentUsingSegmentAllocator() {
+		try (Arena arena = Arena.ofConfined()) {
+			MemorySegment segment = arena.allocate(1024 * 1024); // 1 MB
+			SegmentAllocator allocator = SegmentAllocator.slicingAllocator(segment);
+			for (int i = 0; i < 10; i++) {
+				MemorySegment msi = allocator.allocateFrom(ValueLayout.JAVA_INT, i);
+			}
+			System.out.println("Memory allocated to use with allocator: " + segment);
+		}
+	}
 }

java-22/ForeignFunctionAndMemoryApiFunctionExemple.java

@@ -1,18 +1,176 @@
 import java.lang.foreign.*;
+import java.lang.foreign.MemoryLayout.PathElement;
 import java.lang.invoke.*;
 import java.util.*;
 
 /**
- * To run: `java --enable-preview --source 22 ForeignFunctionAndMemoryApiFunctionExemple.java`
+ * To run: `java --enable-native-access=ALL-UNNAMED --source 22 -Djava.library.path=$(pwd)/ ForeignFunctionAndMemoryApiFunctionExemple.java`
  */
 public class ForeignFunctionAndMemoryApiFunctionExemple {
 	public static void main(String[] args) {
 		functionLookupExample();
+		downcallForeignFunction();
+		upcallJavaCodeToForeignFunction();
+		downcallJavaCodeToForeignFunctionPassingObject();
 	}
 
 	static void functionLookupExample() {
 		Linker linker = Linker.nativeLinker();
 		SymbolLookup stdlib = linker.defaultLookup();
-		Optional<MemorySegment> radixsortMem = stdlib.find("radixsort");
+
+		// find the function in stdlib
+		MemorySegment strlenPtr = stdlib.find("strlen").get();
+
+		// function signature: returns a long and receives a char* (address pointer)
+		FunctionDescriptor signature = FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+		// method handle to be used in Java code to invoke the foreign function
+		MethodHandle strlen = linker.downcallHandle(strlenPtr, signature);
+	}
+
+	/**
+	 * This method will invoke a standard C library function:
+	 * size_t strlen(const char *s)
+	 */
+	static void downcallForeignFunction() {
+		System.out.println("=== Downcall - passing array pointer (string) and receiving a long ===");
+		Linker linker = Linker.nativeLinker();
+		SymbolLookup stdlib = linker.defaultLookup();
+		MemorySegment strlenPtr = stdlib.find("strlen").get();
+		FunctionDescriptor signature = FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+		MethodHandle strlen = linker.downcallHandle(strlenPtr, signature);
+
+		try (Arena arena = Arena.ofConfined()) {
+			// allocates the memory (char*)
+			MemorySegment str = arena.allocateFrom("Hello FFM API!");
+			// invokes the native function passing the memory with the string
+			long len = (long) strlen.invoke(str);
+
+			System.out.println("strlen returned: " + len);
+		} catch (Throwable ex) {
+			System.err.println("Error: " + ex.getMessage());
+		}
+	}
+
+	/**
+	 * This method will invoke a standard C library function:
+	 * void qsort(void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *))
+	 */
+	static void upcallJavaCodeToForeignFunction() {
+		System.out.println("=== Downcall and Upcall - passing array pointer and function pointer ===");
+		Linker linker = Linker.nativeLinker();
+		SymbolLookup stdlib = linker.defaultLookup();
+
+		MethodHandle qsort = linker.downcallHandle(
+			stdlib.find("qsort").get(),
+			// signature: (array pointer, long, long, function pointer)
+			FunctionDescriptor.ofVoid(ValueLayout.ADDRESS, ValueLayout.JAVA_LONG, ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
+		);
+
+		// method handle to invoke the Java method
+		MethodHandle comparatorHandle = null;
+		try {
+			comparatorHandle = MethodHandles.lookup().findStatic(
+				MemorySegmentIntComparator.class,
+				"compare", // method name
+				MethodType.methodType(int.class, MemorySegment.class, MemorySegment.class) // signature (return and parameters)
+			);
+		} catch(NoSuchMethodException | IllegalAccessException ex) {}
+
+		// Java method pointer
+		MemorySegment comparatorPtr = linker.upcallStub(
+			comparatorHandle,
+			FunctionDescriptor.of( // signature
+				ValueLayout.JAVA_INT,
+				ValueLayout.ADDRESS.withTargetLayout(ValueLayout.JAVA_INT),
+				ValueLayout.ADDRESS.withTargetLayout(ValueLayout.JAVA_INT)
+			),
+			Arena.ofAuto() // arena to be used to allocate the foreign function arguments to pass to Java code
+		);
+
+		try (Arena arena = Arena.ofConfined()) {
+			int[] array = new int[] { 4, 0, 8, 7, 1, 6, 5, 9, 3, 2 };
+			System.out.println("Array to be sorted: " + Arrays.toString(array));
+
+			MemorySegment arrayPtr = arena.allocateFrom(ValueLayout.JAVA_INT, array);
+
+			// the array will be sorted in-place
+			qsort.invoke(arrayPtr, array.length, ValueLayout.JAVA_INT.byteSize(), comparatorPtr);
+
+			// gets the sorted array from the memory
+			int[] sortedArray = arrayPtr.toArray(ValueLayout.JAVA_INT);
+
+			System.out.println("Sorted array: " + Arrays.toString(sortedArray));
+		} catch (Throwable ex) {
+			System.err.println("Error: " + ex.getMessage());
+		}
+	}
+
+	/**
+	 * This method will invoke the C function `validate_person` defined in the `person_validator.c`.
+	 * The C code must be compiled first: `gcc -c person_validator.c`
+	 * Function's signature: char* validate_person(struct Person* person)
+	 * Struct: `struct Person { char* name; short age; }`
+	 */
+	static void downcallJavaCodeToForeignFunctionPassingObject() {
+		System.out.println("=== Downcall - passing struct pointer and receiving an array pointer (string) ===");
+		System.load(System.getProperty("java.library.path") + "libpersonvalidator.so");
+
+		SymbolLookup symbolLookup = SymbolLookup.loaderLookup();
+
+		MemoryLayout personStructMemoryLayout = MemoryLayout.structLayout(
+			ValueLayout.ADDRESS.withName("name"),
+			ValueLayout.JAVA_SHORT.withName("age")
+		);
+
+		MethodHandle personValidator = Linker.nativeLinker().downcallHandle(
+			symbolLookup.find("validate_person").get(),
+			// signature: struct pointer -> string pointer
+			FunctionDescriptor.of(ValueLayout.ADDRESS, ValueLayout.ADDRESS)
+		);
+
+		VarHandle nameHandle = personStructMemoryLayout.varHandle(PathElement.groupElement("name"));
+		VarHandle ageHandle = personStructMemoryLayout.varHandle(PathElement.groupElement("age"));
+
+		var people = List.of(
+			new Person(1, null, (short) 0),
+			new Person(2, "", (short) 0),
+			new Person(3, "Marley", (short) 0),
+			new Person(4, "Marley", (short) 10),
+			new Person(5, "Marley", (short) 19)
+		);
+
+		people.forEach(person -> {
+			try (Arena arena = Arena.ofConfined()) {
+				MemorySegment personPtr = arena.allocate(personStructMemoryLayout);
+				if (person.name() == null) {
+					nameHandle.set(personPtr, 0L, MemorySegment.NULL);
+				} else {
+					nameHandle.set(personPtr, 0L, arena.allocateFrom(person.name()));
+				}
+				ageHandle.set(personPtr, 0L, person.age());
+
+				// returns a zero-length memory segment (address pointer)
+				MemorySegment resultPtr = (MemorySegment) personValidator.invoke(personPtr);
+				// reinterpret the pointer to tell the size (max value to read until `\0`)
+				MemorySegment messagePtr = resultPtr.reinterpret(Integer.MAX_VALUE);
+				String message = messagePtr.getString(0);
+
+				System.out.println("ID " + person.id() + " validation result: " + message);
+			} catch (Throwable ex) {
+				System.err.println("Error: " + ex.getMessage());
+			}
+		});
+	}
+}
+
+class MemorySegmentIntComparator {
+	// function to be called by the foreign function
+	static int compare(MemorySegment x, MemorySegment y) {
+		System.err.println("\tJava method called with " + x + " and " + y);
+		// get the int in the memory
+		return Integer.compare(x.get(ValueLayout.JAVA_INT, 0), y.get(ValueLayout.JAVA_INT, 0));
 	}
 }
+
+record Person(int id, String name, short age) {}
+

java-22/README.md

@@ -83,28 +83,44 @@ To run each example use: `java --enable-preview --source 22 <FileName.java>`
           * we can use in a try-with-resources:
             * ```java
               try (Arena confinedArena = Arena.ofConfined()) {
-                MemorySegment input = confinedArena.allocate(100);
-                MemorySegment output = confinedArena.allocate(100);
+                  MemorySegment input = confinedArena.allocate(100);
+                  MemorySegment output = confinedArena.allocate(100);
               } // will be deallocated from here
               ```
         * [shared arena](https://cr.openjdk.org/~mcimadamore/jdk/FFM_23_PR/javadoc/java.base/java/lang/foreign/Arena.html#ofShared()):
           * is a confined arena for multi-threading
           * any thread can access and close the memory segment
+    * allocators:
+      * is an abstraction to define operations to allocate and initialize memory segments
+      * memory allocation can be bottleneck when using off-heap memory, allocators help to minimize this
+      * we can allocate a large memory and then use allocator to distribute through the application
+      * we can create an allocator using an already allocated memory segment
+        * the segments allocated by the allocator will have the same bounded lifetime
+      * ```java
+        MemorySegment segment = Arena.ofAuto().allocate(1024 * 1024 * 1024); // 1 GB
+        SegmentAllocator allocator = SegmentAllocator.slicingAllocator(segment);
+        for (int i = 0; i < 10; i++) {
+            MemorySegment msi = allocator.allocateFrom(ValueLayout.JAVA_INT, i);
+        }
+        ```
   * Memory layout:
     * [Value layout](https://cr.openjdk.org/~mcimadamore/jdk/FFM_22_PR/javadoc/java.base/java/lang/foreign/ValueLayout.html):
       * abstraction to facilitate the memory value layout usage
-      * eg.: to work with int, we can use `ValueLayout.JAVA_INT` to read 4 bytes using the platform endianess to correctly extract an int from a memory segment
+        * eg.: to work with int, we can use `ValueLayout.JAVA_INT` to read 4 bytes using the platform endianness to correctly extract an int from a memory segment
+        * `MemorySegment int = Arena.global().allocateFrom(ValueLayout.JAVA_INT, 42)`
+        * `MemorySegment intArray = Arena.global().allocateFrom(ValueLayout.JAVA_INT, 0, 1, 2, 3, 4, 5)`
+        * `MemorySegment text = Arena.global().allocateFrom("Hello World!")`
       * memory segments have simple dereference methods to read values from and write values to memory segments, these methods accept a value layout
       * example how to write value from 1 to 10 in a memory segment:
         * ```java
           MemorySegment segment = Arena.ofAuto().allocate(
-            ValueLayout.JAVA_INT.byteSize() * 10, // memory size
-            ValueLayout.JAVA_INT.byteAlignment() // memory alignment
+              ValueLayout.JAVA_INT.byteSize() * 10, // memory size
+              ValueLayout.JAVA_INT.byteAlignment() // memory alignment
           );
           for (int i = 0; i < 10; i++) {
-            int value = i + 1;
-            // the memory offset is calculated from: value layout byte size * index
-            segment.setAtIndex(ValueLayout.JAVA_INT, i, value);
+              int value = i + 1;
+              // the memory offset is calculated from: value layout byte size * index
+              segment.setAtIndex(ValueLayout.JAVA_INT, i, value);
           }
           ```
     * Structured access:
@@ -117,24 +133,67 @@ To run each example use: `java --enable-preview --source 22 <FileName.java>`
         * we can manually declare the memory layout:
         ```java
         MemorySegment segment = Arena.ofAuto().allocate(
-          2 * ValueLayout.JAVA_INT.byteSize() * 10,
-          ValueLayout.JAVA_INT.byteAlignment()
+            2 * ValueLayout.JAVA_INT.byteSize() * 10,
+            ValueLayout.JAVA_INT.byteAlignment()
         );
         ```
         * we can use memory layout to describe the content of a memory segment and use `VarHandle` to write the values in the struct:
         ```java
         SequenceLayout ptsLayout = MemoryLayout.sequenceLayout(
-          10, // size
-          MemoryLayout.structLayout( // declare a C struct
-            ValueLayout.JAVA_INT.withName("x"),
-            ValueLayout.JAVA_INT.withName("y")
-          )
+            10, // size
+            MemoryLayout.structLayout( // declare a C struct
+                ValueLayout.JAVA_INT.withName("x"),
+                ValueLayout.JAVA_INT.withName("y")
+            )
         );
         MemorySegment segment = Arena.ofAuto().allocate(ptsLayout);
         ```
+  * Foreign functions:
+    * native library loaded from a lookup doesn'n belong to any class loader (unlike JNI), allowing the native library to be reloaded by any other class
+      * JNI requires the native library to be loaded by only one class loader
+    * FFM API doesn't provides any function for native code to access the Java environment (unlike JNI)
+      * but we can pass a Java code as function pointer to native function
+    * FFM API uses `MethodHandle` to interoperate between Java code and native function
+    * steps need to call a foreign function:
+      * find the address of a given symbol in a loaded native library
+      * link the Java code to a foreign function
+    * Symbol lookup:
+      * we can use `SymbolLookup` to lookup a function address:
+        * `SymbolLookup::libraryLookup(String, Arena)`: creates a library lookup, loads the libreary and associates with the given Arena object;
+        * `SymbolLookup::loaderLookup()`: creates a loader lookup that locates all the symbols in all the native libraries that have been loaded by classes in the current class loader (`System::loadLibrary` and `System::load`);
+        * `Linker::defaultLookup()`: creates a default lookup that locates all the symbols that are commonly used in the native platform (OS).
+      * we can use `SymbolLookup::find(String)` to find a function by its name
+        * if it is present then a memory segment, which points to funtion's entry point, is returned
+    * Linking Java code to foreign function:
+      * interface `Linker` is the main point to allow Java code to interoperate with native code
+      * calls:
+        * downcall: call from Java code to native code;
+        * upcall: call from native code back to Java code (linker a function pointer).
+      * the native linker conforms to the Application Binary Interface (BNI) of the native platform
+        * ABNI specifies the calling convension, the size, alignment, endianness of scalar types and others details
+        * `Linker linker = Linker.nativeLinker()`
+      * downcall:
+        * we use `Linker::downcallHandle` to link Java code to a foreign function
+        * `Linker::downcallHandle(MemorySegment, FunctionDescriptor)` returns a `MethodHandle` to be used to invoke the native function
+          * we must provide a `FunctionDescriptor` to define the native function signature (return type and the parameters types)
+            * we can create one using `FunctionDescriptor.of` or `FunctionDescriptor.ofVoid` passing the memory layout to define the signature
+            * developer must be aware of the current native platform that will be used (size of scalar types used in C functions)
+              * eg.: on Linux and macOS, a long is JAVA_LONG; on Windows, a long is JAVA_INT
+            * we can use `Linker::canonicalLayouts()` to see the association between scalar C types and Java's ValueLayout
+          * JVM guarantee that the functions arguments used in `MethodHandle` will match the `FunctionDescriptor` used to downcall the function
+          * this way our types will be verified in the Java level
+        * if the native function returns a by-value struct, we must provide an additional `SegmentAllocator` argument that will be used to allocate the memory to hold the struct returned
+        * if the native function allocates a memory and returns a pointer to it, a zero-length memory segment is return to Java code
+          * because the JVM cannot guarantee the allocated memory size off-heap
+          * the client must call `MemorySegment::reinterpret` to tell the JVM the memory's size (the user may not know)
+          * this is an unsafe operation (could crash the JVM or leave the memory in a corruption stat)
+      * upcall:
+        * we can pass Java code as a function pointer to be called by the foreign function
+        * we use `Linker::upcallStub` to "externalize" a Java code
+          * we must provide a `MethodHandle` that points to the Java method, a `FunctionDescriptor` with the method signature
 * **Unnamed Variables and Patterns**
   * promotion to standard
-  * no change from JDK 21
+  * no change from JDK 2
 * **Class-File API**
   * provide standard API for parsing, generating and transforming Java class file
 * **Launch Multi-File Source-Code Programs**
@@ -200,4 +259,6 @@ To run each example use: `java --enable-preview --source 22 <FileName.java>`
 
 * [JDK 22 - JEP Dashboard](https://bugs.openjdk.org/secure/Dashboard.jspa?selectPageId=21900)
 * [Gathering the Streams](https://cr.openjdk.org/~vklang/Gatherers.html)
+* Presentations:
+  * [Foreign Function & Memory API - A (Quick) Peek Under the Hood](https://www.youtube.com/watch?v=iwmVbeiA42E)
 

java-22/person_validator.c

@@ -0,0 +1,28 @@
+/**
+ * Compile: `gcc -shared -o libpersonvalidator.so -I $(pwd) person_validator.c`
+ */
+#include <string.h>
+
+struct Person {
+	char* name;
+	short age;
+};
+
+char* validate_person(struct Person* person) {
+	if (person == NULL) {
+		return "Invalid person (null)";
+	}
+	if (person->name == NULL) {
+		return "Invalid name (null)";
+	}
+	if (strlen(person->name) < 1) {
+		return "Invalid name (empty)";
+	}
+	if (person->age < 1 || person->age > 150) {
+		return "Invalid age";
+	}
+	if (person->age < 18) {
+		return "Person is too young";
+	}
+	return "Person is valid";
+}