Project Panama: Native Interop Without JNI

For decades, if a Java developer wanted to call a native function (like getting system details from the OS or using a high-performance C library), they had to wrestle with JNI (Java Native Interface). It was brittle, required writing "glue code" in C/C++, and a single pointer error could crash the entire JVM.

In this post, we'll implement a native interop layer using Project Panama (Java 22+). No JNI, no C++ compilers, no magic. Just pure Java code interacting directly with native memory and the operating system. By the end, you'll understand how Java handles off-heap memory and function pointers under the hood.

A Quick Overview of Project Panama

Before writing code, we need to understand the three pillars of the Foreign Function & Memory (FFM) API:

MemorySegment: A safe wrapper around a contiguous region of memory (on-heap or off-heap). Think of this as a "safe pointer."

Arena: Controls the lifecycle of memory segments. It determines when the memory is allocated and freed.

Linker: The bridge that allows Java to look up symbols (functions) in native libraries and invoke them.

Let's Build: Calling the C Standard Library

We will build a Java program that calls the standard C function strlen directly.

Input: A Java String (converted to a C-string).

Action: Call native strlen.

Output: The length of the string as a long.

Step 1: The Setup & Lookup

First, we need to find the function in the standard library and tell Java what the function signature looks like.

C Signature: size_t strlen(const char *str)

import java.lang.foreign.*;
import java.lang.invoke.MethodHandle;

public class NativeStrlen {
    public static void main(String[] args) throws Throwable {
        // 1. Get the Linker (The bridge to the OS)
        Linker linker = Linker.nativeLinker();

        // 2. Lookup the "strlen" symbol in the default system libraries
        SymbolLookup stdLib = linker.defaultLookup();
        MemorySegment strlenAddress = stdLib.find("strlen").orElseThrow();

        // 3. Define the Function Descriptor
        // C: size_t strlen(char* str)
        // Java: returns JAVA_LONG, accepts ADDRESS (pointer)
        FunctionDescriptor descriptor = FunctionDescriptor.of(
            ValueLayout.JAVA_LONG, // Return type
            ValueLayout.ADDRESS    // Argument type (pointer)
        );

        // 4. Create a MethodHandle to invoke it
        MethodHandle strlen = linker.downcallHandle(strlenAddress, descriptor);

        // ... usage comes next
    }
}

Step 2: Memory Allocation & Invocation (The Naive Way)

Now we need to convert a Java String to a native C-String (null-terminated char array) in off-heap memory.

// ... inside main method

// Using a confined arena: memory is automatically freed when the block exits
try (Arena arena = Arena.ofConfined()) {

    // Allocate off-heap memory and copy the string "Hello Panama"
    // allocateFrom automatically adds the null terminator '\0'
    MemorySegment cString = arena.allocateFrom("Hello Panama");

    // Invoke the native function
    // We must cast the result because MethodHandle returns Object
    long length = (long) strlen.invoke(cString);

    System.out.println("Length from C: " + length); // Output: 12
}

What's Happening Under the Hood?

When you run arena.allocateFrom("..."), Java is not writing to the Heap. It is:

Asking the OS for off-heap memory (similar to malloc in C).
Copying the bytes of the String into that memory.
Passing the memory address (pointer) of that segment to the strlen function.

What's Missing in This Minimal Flow?

The example above works, but for a real-world system tool, it lacks robustness:

Error Handling: C functions often return errors via errno. We aren't capturing that.
Complex Types: Real-world C APIs often use structs, not just simple integers and strings.
Memory Safety: While try-with-resources handles cleanup, we need to ensure we aren't accessing freed memory (Use-After-Free).

Advanced: Production-Ready System Info Tool

Let's build a more complex example. We will call getpid() to get the Process ID and gethostname() which requires passing a buffer for the C function to write into (an "out" parameter).

C Signatures:

int getpid(void)
int gethostname(char *name, size_t len)

package main;

import java.lang.foreign.*;
import java.lang.invoke.MethodHandle;

public class SystemInfoTool {

    public static void main(String[] args) {
        Linker linker = Linker.nativeLinker();
        SymbolLookup stdLib = linker.defaultLookup();

        // --- Define getpid ---
        MemorySegment getpidAddr = stdLib.find("getpid").orElseThrow();
        MethodHandle getpid = linker.downcallHandle(
            getpidAddr,
            FunctionDescriptor.of(ValueLayout.JAVA_INT)
        );

        // --- Define gethostname ---
        MemorySegment gethostnameAddr = stdLib.find("gethostname").orElseThrow();
        MethodHandle gethostname = linker.downcallHandle(
            gethostnameAddr,
            FunctionDescriptor.of(
                ValueLayout.JAVA_INT,   // returns int (error code)
                ValueLayout.ADDRESS,    // char* name (buffer pointer)
                ValueLayout.JAVA_LONG   // size_t len (buffer length)
            )
        );

        // --- Execution Phase ---
        // Using a Confined Arena: Memory is released deterministically
        // as soon as we exit this block.
        try (Arena arena = Arena.ofConfined()) {

            // 1. Call getpid
            int pid = (int) getpid.invoke();
            System.out.println("Current PID: " + pid);

            // 2. Call gethostname
            // We need to allocate a buffer for C to write the hostname into.
            // Equivalent to char buffer[64]; in C.
            long bufferSize = 64;
            MemorySegment hostnameBuffer = arena.allocate(bufferSize);

            // Invoke: passing the pointer (buffer) and the size
            int result = (int) gethostname.invoke(hostnameBuffer, bufferSize);

            if (result == 0) {
                // Read the data back from off-heap memory into a Java String
                String hostname = hostnameBuffer.getString(0);
                System.out.println("Hostname: " + hostname);
            } else {
                System.err.println("Failed to get hostname.");
            }

        } catch (Throwable t) {
            t.printStackTrace();
        }
    }
}

Important Runtime Note
Because Project Panama is powerful (and dangerous), you must explicitly enable it at runtime. Run your code with: java --enable-native-access=ALL-UNNAMED SystemInfoTool.java

A Note on Cross-Platform Portability

Writing native interop code introduces platform dependency. The example above uses getpid and gethostname, which are standard on Linux and macOS (POSIX). However, if you run this on Windows, the lookup might fail or require different function names (like GetCurrentProcessId from Kernel32).

When building robust native tools with Panama:

Check the OS: Use System.getProperty("os.name") to load the correct symbols.
Type Mapping: Be mindful of C types like size_t (unsigned) vs Java's long (signed). While usually compatible for lengths, bit-level discrepancies can occur in other contexts.

Key Takeaways

Zero-Copy is Real: Just like in your Go networking projects, Panama allows you to share memory between the JVM and Native OS without expensive copying overhead.
Deterministic Deallocation: The Arena API and try-with-resources block solve the biggest headache of manual memory management: leaks. When the block ends, the memory is freed.
Type Safety: ValueLayouts allow us to be precise about memory layout (e.g., specific bit-widths), reducing the "undefined behavior" risks typical in C.

By mastering the FFM API, you are no longer confined to the JVM. You can optimize critical paths, use specialized hardware libraries, or interact with the OS kernel-all while writing type-safe Java code.