How do you call a native C function from Java with the Linker (downcall), and what is an upcall?

## The goal: cross the Java/native boundary in both directions Native interop has two directions. **Downcall** = Java code calls a C function. **Upcall** = C code calls back into Java (because the C API expects a *callback function pointer*). The FFM API handles both through the **`Linker`**. ## Step 1 — get the Linker ```java Linker linker = Linker.nativeLinker(); ``` `Linker.nativeLinker()` returns the linker for the **native ABI** (Application Binary Interface — the platform's calling convention for how arguments are passed in registers/stack). You normally don't think about the ABI; the linker implements it for you. ## Step 2 — find the function's address (SymbolLookup) A C function lives at an **address** in a loaded library. A **`SymbolLookup`** finds that address by name: - `linker.defaultLookup()` — symbols already available to the process (standard C library, etc.). - `SymbolLookup.libraryLookup("mylib", arena)` — load *your* shared library and look up its symbols; the `arena` controls how long the library stays loaded. ```java MemorySegment addr = linker.defaultLookup().find("strlen").orElseThrow(); ``` The address comes back as a `MemorySegment` (a pointer). ## Step 3 — describe the signature (FunctionDescriptor) C is not self-describing, so you must tell the linker the function's **signature**. A **`FunctionDescriptor`** maps C types to FFM **layouts**: - `FunctionDescriptor.of(returnLayout, argLayouts...)` for a function with a return value. - `FunctionDescriptor.ofVoid(argLayouts...)` for `void` functions. - Pointers map to `ValueLayout.ADDRESS`; `int`→`JAVA_INT`; `long`→`JAVA_LONG`; etc. For `size_t strlen(const char*)`: ```java FunctionDescriptor desc = FunctionDescriptor.of( ValueLayout.JAVA_LONG, // returns size_t (a long) ValueLayout.ADDRESS); // takes a char* (a pointer) ``` ## Step 4 — get a MethodHandle and invoke (the downcall) ```java MethodHandle strlen = linker.downcallHandle(addr, desc); try (Arena arena = Arena.ofConfined()) { MemorySegment cString = arena.allocateUtf8String("hello"); long len = (long) strlen.invoke(cString); // -> 5 } ``` A **`MethodHandle`** is a directly-invokable, typed reference to executable code. Here it *is* the C function: you call `.invoke(...)` with Java values, passing `MemorySegment`s where C wants pointers. No handwritten C glue, no separate compile step. ## Upcalls — letting C call Java Many C APIs take a **callback**: e.g. `qsort` needs a comparison function pointer. To supply one from Java you create an **upcall stub**: 1. Write a Java method matching the callback's signature and obtain a `MethodHandle` to it (via `MethodHandles.lookup().findStatic(...)`). 2. Describe the callback signature with a `FunctionDescriptor`. 3. `linker.upcallStub(handle, descriptor, arena)` returns a **`MemorySegment`** — a *native function pointer* — that C can call. Invoking it runs your Java method. ```java MethodHandle cmpHandle = MethodHandles.lookup().findStatic( MyClass.class, "compare", MethodType.methodType(int.class, MemorySegment.class, MemorySegment.class)); FunctionDescriptor cmpDesc = FunctionDescriptor.of( ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS); MemorySegment cmpPtr = linker.upcallStub(cmpHandle, cmpDesc, arena); // pass cmpPtr to a C function that expects a comparator pointer ``` The `arena` controls the **stub's lifetime**: when it closes, the function pointer becomes invalid, so don't let C hold it past that. ## Tuning the call: Linker.Option `downcallHandle`/`upcallStub` accept `Linker.Option` values, e.g.: - **`Linker.Option.isTrivial()`** — promise the call is very short/non-blocking so the JVM can use a cheaper transition (less overhead, but misuse can hurt the JVM). - **`captureCallState("errno")`** — capture the native `errno` (the C error variable) right after the call, since the JVM might otherwise clobber it. ## How this compares to JNI With **JNI** you'd write and compile a C shim per function and per platform, juggling `jstring`/`jint` conversions and manual reference management — easy to crash. With FFM, the *entire* binding is pure Java: a descriptor, a lookup, a method handle. That, plus `Arena`/`MemorySegment` safety, is why FFM supersedes JNI for most use cases.