roray.dev - backend

Java FFM - Foreign Function & Memory Access API (Project Panama)

2025-08-28T00:00:00+00:00

TL;DR</h1>
Java’s Foreign Function & Memory (FFM) API enables safe, high-performance interaction with native code and memory, improving interoperability with other languages and access to low-level system resources. Entire source code available on GitHub</a>.

</p>

Overview</h1>
The Foreign Function & Memory (FFM) API in Java, finalized in JDK 22 with JEP 454, provides a robust and safe mechanism for Java code to interact with foreign functions (native code) and foreign memory (memory outside the Java heap). </p>
The FFM API is designed to be a safer, more efficient, and more user-friendly alternative to the Java Native Interface (JNI). JNI is known for its complexity and potential for introducing errors, whereas FFM aims to provide a more "Java-first" programming model for native interoperability. </p>
The FFM API introduces several key concepts and components that facilitate foreign function and memory access in Java: </p>

Memory Segments</strong>: A memory segment is a contiguous block of memory that can be accessed by Java programs. The FFM API provides a way to create and manage memory segments, allowing developers to allocate and deallocate memory as needed.</p> </li>

Arena Allocation</strong>: The FFM API introduces the concept of arenas, which are memory pools that can be used for efficient allocation and deallocation of memory. Arenas help reduce fragmentation and improve performance when working with native memory.</p> </li>

Value Layouts</strong>: Value layouts define the memory layout of data structures in a platform-independent way. The FFM API allows developers to create value layouts for both Java and foreign types, ensuring compatibility between the two.</p> </li>

Memory Access</strong>: The FFM API provides a set of APIs for reading and writing data to memory segments, making it easy to manipulate native data from Java.</p> </li>

Foreign Functions</strong>: Foreign functions are native functions written in languages like C or C++ that can be called from Java. The FFM API provides a way to define and invoke foreign functions, enabling seamless integration between Java and native code.</p> </li> </ol>

Note: While the primary use case of the Java Foreign Function & Memory (FFM) API is to call C functions from Java (downcalls), it also supports the reverse: calling Java functions from C (upcalls). This is particularly useful for scenarios like C callbacks, where a C library needs to invoke a function provided by Java code.</em></p> </blockquote>

FFM Use cases</h1>
By leveraging these components, developers can build high-performance applications that take advantage of native libraries and system resources while maintaining the safety and ease of use that Java provides especially in below use cases:</p>

Performance-Critical Applications</strong>: Applications that require high performance such as game engines, scientific computing, Ultra Low Level (ULL) High Frequency Trading (HFT) systems and real-time systems can benefit from direct access to native code and memory.</li>
Big Data and Machine Learning</strong>: Libraries like TensorFlow and PyTorch often require efficient memory management and native code execution, making FFM a suitable choice for integrating these libraries into Java applications.</li>
Interoperability with Other Languages</strong>: FFM allows Java applications to easily call functions written in other languages, such as C or C++, enabling developers to leverage existing libraries and codebases</li>
Low-Level System Access</strong>: Applications that need to interact with low-level system resources, such as hardware devices or operating system APIs, can use FFM to access these resources directly from Java e.g. accessing NIC for Kernel bypass networking, accessing GPU for parallel processing, etc.</li>
High Performance Computing (HPC)</strong>: FFM can be used in HPC applications where performance is critical, such as simulations, numerical computations, and data processing tasks that require efficient memory management and native code execution.</li>
High Performance File/Data I/O</strong>: Database files, large binary files, and other data-intensive applications can benefit by using techniques like memory-mapped files which allow direct access to file contents in memory, random access, bulk read, minimize OS calls, Zero copy & low GC pressure by avoiding Heap, multi-process file coordination with locks improving I/O performance and reducing latency.</li>
Custom High Performance Low Latency RPC</strong>: Remote Procedure Calls (RPC) can be optimized using FFM to reduce serialization/deserialization overhead, enabling faster communication with high throughput between distributed systems.</li> </ul>
Demo Example</h1>
Let’s see a small example of effective usage of FFM. As a Proof of Concept, we will create a TCP server using io_uring</a> (Linux kernel interface for asynchronous I/O operations) and Java FFM API. The actual TCP server using io_uring is implemented in C. We will use various APIs (standard TCP operations) viz. accept, listen, connect, send, receive etc. in Java through Foreign Functions mapping the actual C functions.</p>
This is by no means a production ready code. The goal is to showcase the ease of use and integration of FFM with existing C libraries. We also won’t be going into details of TCP server implementation in C nor what is io_uring as it’s beyond the scope of this article.</p>

TCP server in C using async io-uring</h2>
Let’s look at the C code</a> first especially the below APIs:</p>

`io_uring_global_init</code> - Initializes the global io_uring context and sets up the underlying ring buffers for asynchronous I/O operations</li>`
`io_uring_listen</code> - Creates a TCP socket, binds it to a specified port, and starts listening for incoming connections</li>`
`io_uring_accept</code> - Accepts an incoming connection request and returns a new socket file descriptor for the client</li>`
`io_uring_connect</code> - Establishes an outbound TCP connection to a remote server at the specified address and port</li>`
`io_uring_send</code> - Sends data through an established TCP connection using io_uring’s asynchronous write operations</li>`
io_uring_receive</code> - Receives data from an established TCP connection using io_uring’s asynchronous read operations</li> </ul> Java - FFM Integration</h2> Now let’s look at the Java side which is the point of interest of this article. We have 2 classes:</p> FfmReceiver</code> - Responsible for receiving data from the TCP server</li> FfmSender</code> - Responsible for sending data to the TCP server</li> </ul> Note: The actual TCP server is implemented in C using io_uring. The C library exposes lifecycle methods for managing the server. These methods are then called in Java using FFM.</strong></em></p> FfmReceiver</h3> 1</td> import java.lang.foreign.Arena; </span></td></tr> 2</td> import java.lang.foreign.FunctionDescriptor; </span></td></tr> 3</td> import java.lang.foreign.Linker; </span></td></tr> 4</td> import java.lang.foreign.MemorySegment; </span></td></tr> 5</td> import java.lang.foreign.SymbolLookup; </span></td></tr> 6</td> import java.lang.foreign.ValueLayout; </span></td></tr> 7</td> import java.lang.invoke.MethodHandle; </span></td></tr> 8</td> import java.nio.charset.StandardCharsets; </span></td></tr> 9</td> </span></td></tr> 10</td> public class FfmReceiver { </span></td></tr> 11</td> </span></td></tr> 12</td> private static final ValueLayout.OfByte BYTE = ValueLayout.Java_BYTE; </span></td></tr> 13</td> </span></td></tr> 14</td> public static void main(String[] args) throws Throwable { </span></td></tr> 15</td> int queueDepth = 32; </span></td></tr> 16</td> int port = 22345; </span></td></tr> 17</td> int backlog = 128; </span></td></tr> 18</td> long bufferSize = 8 * 1024 * 1024; // 8 MB buffer per client </span></td></tr> 19</td> </span></td></tr> 20</td> try (Arena arena = Arena.ofShared()) { </span></td></tr> 21</td> </span></td></tr> 22</td> // Load the shared library </span></td></tr> 23</td> SymbolLookup lib = SymbolLookup.libraryLookup("./libiouring_tcp.so", arena); </span></td></tr> 24</td> Linker linker = Linker.nativeLinker(); </span></td></tr> 25</td> </span></td></tr> 26</td> // 1️⃣ Global Init </span></td></tr> 27</td> MemorySegment globalInitAddr = lib.find("io_uring_global_init").get(); </span></td></tr> 28</td> MethodHandle mhGlobalInit = linker.downcallHandle(globalInitAddr, </span></td></tr> 29</td> FunctionDescriptor.of(ValueLayout.Java_INT, ValueLayout.Java_INT)); </span></td></tr> 30</td> int ret = (int) mhGlobalInit.invokeExact(queueDepth); </span></td></tr> 31</td> System.out.println("io_uring_global_init returned: " + ret); </span></td></tr> 32</td> </span></td></tr> 33</td> // 2️⃣ Listen (server socket) </span></td></tr> 34</td> MemorySegment listenAddr = lib.find("io_uring_listen").get(); </span></td></tr> 35</td> MethodHandle mhListen = linker.downcallHandle(listenAddr, </span></td></tr> 36</td> FunctionDescriptor.of(ValueLayout.Java_INT, ValueLayout.Java_INT, ValueLayout.Java_INT)); </span></td></tr> 37</td> int listenFd = (int) mhListen.invokeExact(port, backlog); </span></td></tr> 38</td> if (listenFd < 0) { </span></td></tr> 39</td> throw new RuntimeException("io_uring_listen failed, fd=" + listenFd); </span></td></tr> 40</td> } </span></td></tr> 41</td> System.out.println("Server listening on port " + port + ", fd=" + listenFd); </span></td></tr> 42</td> </span></td></tr> 43</td> // 3️⃣ Accept clients in a loop </span></td></tr> 44</td> MemorySegment acceptAddr = lib.find("io_uring_accept").get(); </span></td></tr> 45</td> MethodHandle mhAccept = linker.downcallHandle(acceptAddr, </span></td></tr> 46</td> FunctionDescriptor.of(ValueLayout.Java_INT, ValueLayout.Java_INT)); </span></td></tr> 47</td> </span></td></tr> 48</td> MemorySegment recvAddr = lib.find("io_uring_recv").get(); </span></td></tr> 49</td> MethodHandle mhRecv = linker.downcallHandle(recvAddr, </span></td></tr> 50</td> FunctionDescriptor.of(ValueLayout.Java_INT, ValueLayout.Java_INT, ValueLayout.ADDRESS, ValueLayout.Java_LONG)); </span></td></tr> 51</td> </span></td></tr> 52</td> while (true) { </span></td></tr> 53</td> int clientFd = (int) mhAccept.invokeExact(listenFd); </span></td></tr> 54</td> if (clientFd < 0) { </span></td></tr> 55</td> System.err.println("Accept failed, fd=" + clientFd); </span></td></tr> 56</td> continue; </span></td></tr> 57</td> } </span></td></tr> 58</td> System.out.println("Client connected, fd=" + clientFd); </span></td></tr> 59</td> </span></td></tr> 60</td> // Allocate buffer for this client </span></td></tr> 61</td> MemorySegment buffer = arena.allocate(bufferSize); </span></td></tr> 62</td> </span></td></tr> 63</td> int bytesReceived = (int) mhRecv.invokeExact(clientFd, buffer, bufferSize); </span></td></tr> 64</td> if (bytesReceived < 0) { </span></td></tr> 65</td> System.err.println("io_uring_recv failed, bytes=" + bytesReceived); </span></td></tr> 66</td> continue; </span></td></tr> 67</td> } </span></td></tr> 68</td> System.out.println("Received bytes: " + bytesReceived); </span></td></tr> 69</td> </span></td></tr> 70</td> // Print first 128 bytes for debugging (optional) </span></td></tr> 71</td> int displayLen = Math.min(128, bytesReceived); </span></td></tr> 72</td> byte[] arr = new byte[displayLen]; </span></td></tr> 73</td> for (int i = 0; i < displayLen; i++) { </span></td></tr> 74</td> arr[i] = buffer.get(BYTE, i); </span></td></tr> 75</td> } </span></td></tr> 76</td> System.out.println("First " + displayLen + " bytes:\n" + </span></td></tr> 77</td> new String(arr, StandardCharsets.US_ASCII)); </span></td></tr> 78</td> </span></td></tr> 79</td> // Close client socket </span></td></tr> 80</td> MemorySegment closeAddr = lib.find("io_uring_close").get(); </span></td></tr> 81</td> MethodHandle mhClose = linker.downcallHandle(closeAddr, </span></td></tr> 82</td> FunctionDescriptor.ofVoid(ValueLayout.Java_INT)); </span></td></tr> 83</td> mhClose.invokeExact(clientFd); </span></td></tr> 84</td> System.out.println("Client fd " + clientFd + " closed."); </span></td></tr> 85</td> } </span></td></tr> 86</td> </span></td></tr> 87</td> // 4️⃣ Optional: shutdown ring (never reached in infinite loop) </span></td></tr> 88</td> // MemorySegment shutdownAddr = lib.find("io_uring_global_shutdown").get(); </span></td></tr> 89</td> // MethodHandle mhShutdown = linker.downcallHandle(shutdownAddr, FunctionDescriptor.ofVoid()); </span></td></tr> 90</td> // mhShutdown.invokeExact(); </span></td></tr> 91</td> } </span></td></tr> 92</td> } </span></td></tr> 93</td> } </span></td></tr></tbody></table></code></pre> This FfmReceiver class demonstrates a complete FFM workflow for calling native C functions from Java. Here’s the high-level technical breakdown:</p> Library Loading & Symbol Resolution</strong></p> FFM loads the compiled C shared library containing io_uring functions. SymbolLookup provides a bridge to find C function symbols by name.</p> Key FFM Components in Action</strong></p> Arena: Manages native memory lifecycle - automatically frees all allocated memory when closed (safe malloc/free).</li> SymbolLookup: This is how Java finds function pointers in a native library. Think of SymbolLookup as a “directory of functions” inside the .so file.</li> Linker: The bridge between Java and native code, which knows how to convert between Java calling conventions and the platform’s native ABI (x86_64 Linux, ARM64, etc.).</li> FunctionDescriptor: Defines the C/native function signature (return type + parameter types)</li> ValueLayout: Maps Java types to native types (Java_INT → C int, ADDRESS → C pointer)</li> MethodHandle: Type-safe wrapper for C/native function calls</li> MemorySegment: Represents native memory buffers for data exchange; essentially a safe pointer with guardrails.</li> </ul> Memory Management</strong></p> Native memory is allocated outside the Java heap. Data is directly read/written to native buffers without copying (zero copy). Arena ensures safe & automatic cleanup when the try-with-resources block exits.</p> Here, arena is used both to load the library and allocate buffers for receiving data.</p> Here, libraryLookup loads our custom shared library (.so) and lets us find symbols like io_uring_global_init, io_uring_listen, etc.</p> Then with linker, we can create MethodHandles that behave like normal Java methods but actually invoke C functions. We can think of a MethodHandle as a Java wrapper around a native C function. A linker can be thought of as a translator between Java’s JVM world and C’s native/binary code.</p> Next, we define the function signature with FunctionDescriptor.of(Java_INT, Java_INT) which includes parameter(input) types & all return types. In this case, the function says it takes one int argument & returns one int as the result. invokeExact(queueDepth) → actually executes the C function.</p> Safety & Type Checking</strong></p> invokeExact() enforces exact type matching between Java and C function signatures. Compile-time validation prevents type mismatches that would cause runtime errors. No manual memory management or pointer arithmetic required. This approach eliminates JNI’s complexity while providing direct, high-performance access to native libraries with Java’s safety guarantees intact.</p> Click here</a> to see a more detailed AI generated walk through of FfmReceiver implementation.</em></p> Sample Output:</p> </p> FfmSender</h3> 1</td> import java.lang.foreign.; </span></td></tr> 2</td> import java.lang.invoke.MethodHandle; </span></td></tr> 3</td> import java.nio.charset.StandardCharsets; </span></td></tr> 4</td> </span></td></tr> 5</td> public class FfmSender { </span></td></tr> 6</td> public static void main(String[] args) throws Throwable { </span></td></tr> 7</td> int queueDepth = 32; </span></td></tr> 8</td> int port = 22345; </span></td></tr> 9</td> long bufferSize = 4 1024; // 4 KB buffer per client </span></td></tr> 10</td> </span></td></tr> 11</td> System.out.println("FfmSender running..."); </span></td></tr> 12</td> try (Arena arena = Arena.ofShared()) { </span></td></tr> 13</td> String hi = "ping"; </span></td></tr> 14</td> </span></td></tr> 15</td> // Load the shared library </span></td></tr> 16</td> SymbolLookup lib = SymbolLookup.libraryLookup("./libiouring_tcp.so", arena); </span></td></tr> 17</td> Linker linker = Linker.nativeLinker(); </span></td></tr> 18</td> </span></td></tr> 19</td> // Global IO URing Init </span></td></tr> 20</td> MemorySegment globalInitAddrMS = lib.find("io_uring_global_init").get(); </span></td></tr> 21</td> FunctionDescriptor globalInitFD = FunctionDescriptor.of( </span></td></tr> 22</td> ValueLayout.Java_INT, </span></td></tr> 23</td> ValueLayout.Java_INT); </span></td></tr> 24</td> MethodHandle globalInitMH = linker.downcallHandle(globalInitAddrMS, globalInitFD); </span></td></tr> 25</td> int ret = (int) globalInitMH.invokeExact(queueDepth); </span></td></tr> 26</td> System.out.println("io_uring_global_init returned: " + ret); </span></td></tr> 27</td> </span></td></tr> 28</td> // TCP Open Socket FD </span></td></tr> 29</td> MemorySegment tcpSocketAddrMS = lib.find("io_uring_connect").get(); </span></td></tr> 30</td> FunctionDescriptor tcpConnectFD = FunctionDescriptor.of( </span></td></tr> 31</td> ValueLayout.Java_INT, // return value of socket File Descriptor </span></td></tr> 32</td> ValueLayout.ADDRESS, // server address </span></td></tr> 33</td> ValueLayout.Java_INT); // server port </span></td></tr> 34</td> MethodHandle tcpConnectMH = linker.downcallHandle(tcpSocketAddrMS, tcpConnectFD); </span></td></tr> 35</td> </span></td></tr> 36</td> String ip = "127.0.0.1"; // destination IP </span></td></tr> 37</td> byte[] ipBytes = ip.getBytes(StandardCharsets.UTF_8); </span></td></tr> 38</td> MemorySegment ipStr = arena.allocate(ipBytes.length + 1); </span></td></tr> 39</td> ipStr.asSlice(0, ipBytes.length).copyFrom(MemorySegment.ofArray(ipBytes)); </span></td></tr> 40</td> ipStr.set(ValueLayout.Java_BYTE, ipBytes.length, (byte) 0); // Null-terminate for C </span></td></tr> 41</td> </span></td></tr> 42</td> int socketFD = (int) tcpConnectMH.invokeExact(ipStr, port); </span></td></tr> 43</td> </span></td></tr> 44</td> // IO URing send data through memory segment off-heap buffer </span></td></tr> 45</td> MemorySegment sendBufAddrMS = lib.find("io_uring_send_all").get(); </span></td></tr> 46</td> FunctionDescriptor sendBufFD = FunctionDescriptor.of( </span></td></tr> 47</td> ValueLayout.Java_INT, // return value: total sent bytes </span></td></tr> 48</td> ValueLayout.Java_INT, // socket fd </span></td></tr> 49</td> ValueLayout.ADDRESS, // buffer address </span></td></tr> 50</td> ValueLayout.Java_LONG); // buffer length </span></td></tr> 51</td> MethodHandle sendBufMH = linker.downcallHandle(sendBufAddrMS, sendBufFD); </span></td></tr> 52</td> </span></td></tr> 53</td> // Prepare buffer </span></td></tr> 54</td> MemorySegment sendBuf = arena.allocateFrom(hi); </span></td></tr> 55</td> </span></td></tr> 56</td> int totalBytesSent = (int) sendBufMH.invokeExact(socketFD, sendBuf, (long) hi.length()); </span></td></tr> 57</td> </span></td></tr> 58</td> System.out.println("Total bytes sent Java FFM: " + totalBytesSent); </span></td></tr> 59</td> </span></td></tr> 60</td> } </span></td></tr> 61</td> </span></td></tr> 62</td> } </span></td></tr> 63</td> } </span></td></tr></tbody></table></code></pre> Sample Output:</p> </p> This FfmSender class demonstrates sending data to the TCP server using FFM. The flow is similar to FfmReceiver. We send “ping” text to the TCP Server > FfmReceiver.</p> Appendix</h1> Java Versions support</h3> JDK Version</th> API Status</th> Enabling Preview Features</th> Key Enhancements (FFM API versions)</th> Package</th></tr></thead> JDK 14</strong></td> Foreign-Memory Access API (Incubator)</td> Not applicable (Incubator)</td> Memory segments, Arenas (via Foreign-Memory Access API)</td> jdk.incubator.foreign</a></td></tr> JDK 16</strong></td> Incubator</td> Not applicable (Incubator)</td> Calling native functions (via Foreign Linker API)</td> jdk.incubator.foreign</a></td></tr> JDK 17</strong></td> Incubator</td> Not applicable (Incubator)</td> Unified FFM API, enhancements to MemorySegment and MemoryAddress abstractions, improved memory layout hierarchy</td> jdk.incubator.foreign</a></td></tr> JDK 18</strong></td> Incubator</td> Not applicable (Incubator)</td> Refinements based on feedback</td> jdk.incubator.foreign</a></td></tr> JDK 19</strong></td> Preview</td> –enable-preview flag required</td> Refinements based on feedback</td> java.lang.foreign</a></td></tr> JDK 20</strong></td> Second Preview</td> –enable-preview flag required</td> Refinements based on feedback, including linker option for heap segments, Enable-Native-Access attribute, programmatic function descriptors</td> java.lang.foreign</a></td></tr> JDK 21</strong></td> Third Preview</td> –enable-preview flag required</td> Further refinements based on feedback</td> java.lang.foreign</a></td></tr> JDK 22+</strong></td> Finalized</td> Not required (Finalized)</td> API stabilization, minor refinements</td> java.lang.foreign</a></td></tr> </tbody></table> Explanation</strong></p> Incubator Phase: The initial steps of the FFM API were as incubating features, meaning they were experimental and subject to change. These releases introduced the core concepts like memory access and foreign function invocation. JEP 434 mentions that the FFM API was in its incubator phase in JDK 17 and JDK 18.</li> Preview Phase: In the preview phase, the API's design and implementation were complete, but still subject to potential changes based on user feedback. OpenJDK JEP 424 describes the Foreign Function & Memory API as a preview API in JDK 19.</li> Finalized: In JDK 22, the FFM API was declared stable and ready for production use, removing the need for preview flags and providing a more robust and reliable native interoperability solution.</li> Key Enhancements: This section highlights the significant changes and refinements introduced in each version of the FFM API as it evolved.</li> </ul> 📝 Walking Through FfmReceiver — A First Taste of Java FFM (AI generated</em>)</h3> In this demo, we’re calling native io_uring functions in C from Java, to build a high-performance TCP receiver</strong>.</p> 1. Arena</code> — Memory Lifetime Manager</strong></p> try</span> (</span>Arena</span> arena =</span> Arena</span>.</span>ofShared</span>(</span>)</span></span></span>)</span></span> {</span> </span></span> .</span>.</span>.</span> </span></span>}</span></span> </span></code></pre> Arena</strong> is a memory allocator with automatic cleanup.</p> </li> Think of it as a “scope for native memory”</strong>: allocate native buffers inside it, and when the try</code> block exits, the arena frees them automatically.</p> </li> Variants:</p> </li> </ul> Arena Type</th> Bounded Lifetime</th> Manual Close (arena.close())</th> Thread Access</th> Common Use Case</th></tr></thead> Global</td> No</td> No</td> Yes (accessible by any thread)</td> For memory that needs to persist for the entire lifetime of the application.</td></tr> Automatic</td> Yes</td> No (managed by Garbage Collector)</td> Yes (accessible by any thread)</td> Simplest memory management for bounded lifetimes. The memory is deallocated when the arena becomes unreachable by the garbage collector.</td></tr> Confined</td> Yes</td> Yes (mandatory)</td> No (only by the creating thread)</td> Perfect for single-threaded applications. Provides deterministic deallocation of memory when the arena is closed, often used with try-with-resources.</td></tr> Shared</td> Yes</td> Yes (mandatory)</td> Yes (accessible by multiple threads)</td> For concurrent applications where memory segments must be shared between threads. Closing the arena is safe and atomic, even when accessed by multiple threads.</td></tr> </tbody></table> Here we use ofShared()</code> because multiple native calls may work with the allocated memory.</p> 2. SymbolLookup</code> — Finding Functions in a Shared Library</strong></p> SymbolLookup</span> lib =</span> SymbolLookup</span>.</span>libraryLookup</span>(</span>"</span>./libiouring_tcpa.so"</span></span>,</span> arena)</span></span></span>;</span> </span></code></pre> SymbolLookup</code> is how Java finds functions or variables inside a native shared library (.so</code>, .dll</code>, .dylib</code>).</li> You pass the library name and a scope (arena</code>).</li> Later, we’ll do lib.find("io_uring_listen")</code> to grab the raw address of that function.</li> </ul> 👉 Without SymbolLookup</code>, Java wouldn’t know where in memory</em> the C function lives.</p> 3. Linker</code> — Bridging Java ↔ Native</strong></p> Linker</span> linker =</span> Linker</span>.</span>nativeLinker</span>(</span>)</span></span></span>;</span> </span></code></pre> Linker</strong> builds a bridge between Java and C functions.</li> It knows how to: Translate Java values to C values (e.g., int</code> ↔ int32_t</code>)</li> Call into native functions and return values back</li> </ul> </li> </ul> nativeLinker()</code> automatically picks the system ABI (x86_64, ARM64, etc.).</p> 4. MemorySegment</code> — Safe, Structured Native Memory</strong></p> MemorySegment</span> buffer =</span> arena.</span>allocate</span>(</span>bufferSize)</span></span></span>;</span> </span></code></pre> MemorySegment</strong> is a safe view of native memory.</li> Unlike ByteBuffer</code> (which is limited and unsafe), a MemorySegment</code> tracks bounds, lifetime, and thread access.</li> Example:</li> </ul> byte</span> b =</span> buffer.</span>get</span>(</span>ValueLayout</span>.</span>Java_BYTE</span>,</span> offset)</span></span></span>;</span> </span>buffer.</span>set</span>(</span>ValueLayout</span>.</span>Java_BYTE</span>,</span> offset,</span> (</span>byte</span>)</span></span> 42</span>)</span></span>;</span> </span></code></pre> Here, we allocate an 8 MB receive buffer</strong> per client.</li> Later, we copy received bytes into a Java byte[]</code> for debugging.</li> </ul> 5. MethodHandle</code> — Calling Native Functions</strong></p> Every native function we call has 3 steps:</p> Find its address</strong>:</li> </ol> MemorySegment</span> addr =</span> lib.</span>find</span>(</span>"</span>io_uring_global_init"</span></span>)</span></span>.</span>get</span>(</span>)</span></span></span>;</span> </span></code></pre> Describe its signature</strong> using FunctionDescriptor</code>:</li> </ol> FunctionDescriptor</span>.</span>of</span>(</span>ValueLayout</span>.</span>Java_INT</span>,</span> ValueLayout</span>.</span>Java_INT</span>)</span></span> </span></code></pre> → “returns int, takes an int argument”</p> Bind with a</strong> MethodHandle</code>:</li> </ol> MethodHandle</span> mhGlobalInit =</span> linker.</span>downcallHandle</span>(</span>globalInitAddr,</span> descriptor)</span></span></span>;</span> </span></code></pre> Call it</strong> like a Java method:</li> </ol> int</span> ret =</span> (</span>int</span>)</span></span> mhGlobalInit.</span>invokeExact</span>(</span>queueDepth)</span></span></span>;</span> </span></code></pre> 👉 A MethodHandle</code> is like a strongly-typed function pointer.</p> It hides the messy details of JNI — no boilerplate, no unsafe casts.</p> 6. ValueLayout</code> — Mapping Java ↔ C Types</strong></p> ValueLayout</code> tells the FFM API how Java types map to C types.</li> Examples: Java_INT</code> → C int32_t</code></li> Java_LONG</code> → C int64_t</code></li> Java_BYTE</code> → C int8_t</code></li> ADDRESS</code> → C pointers</li> </ul> </li> </ul> So when we say:</p> FunctionDescriptor</span>.</span>of</span>(</span>ValueLayout</span>.</span>Java_INT</span>,</span> ValueLayout</span>.</span>Java_INT</span>,</span> ValueLayout</span>.</span>ADDRESS</span>,</span> ValueLayout</span>.</span>Java_LONG</span>)</span></span> </span></code></pre> We mean:</p> int</span> io_uring_recv</span></span>(</span></span></span>int</span> clientFd</span>,</span> void</span></span> buffer</span>,</span> long</span> length</span>)</span></span></span>;</span> </span></code></pre> 7. Putting It All Together</strong></p> In the demo flow:</p> Initialize io_uring</li> </ol> mhGlobalInit.</span>invokeExact</span>(</span>queueDepth)</span></span>;</span> </span></code></pre> Create a TCP server socket</li> </ol> int</span> listenFd =</span> (</span>int</span>)</span></span> mhListen.</span>invokeExact</span>(</span>port,</span> backlog)</span></span></span>;</span> </span></code></pre> Accept connections</li> </ol> int</span> clientFd =</span> (</span>int</span>)</span></span> mhAccept.</span>invokeExact</span>(</span>listenFd)</span></span></span>;</span> </span></code></pre> Receive data into a native buffer</li> </ol> int</span> bytesReceived =</span> (</span>int</span>)</span></span> mhRecv.</span>invokeExact</span>(</span>clientFd,</span> buffer,</span> bufferSize)</span></span></span>;</span> </span></code></pre> Inspect data in Java (first 128 bytes)</li> </ol> byte</span>[]</span> arr =</span> new</span> byte</span>[</span>displayLen]</span></span></span></span>;</span> </span>arr[i] =</span> buffer.</span>get</span>(</span>BYTE</span>,</span> i)</span></span></span>;</span> </span></code></pre> Close the socket</li> </ol> mhClose.</span>invokeExact</span>(</span>clientFd)</span></span>;</span> </span></code></pre> 8. Why This Matters</strong></p> Traditionally, Java needed JNI</strong> for native calls — painful, verbose, unsafe.</p> With FFM</strong>, we now have:</p> Memory safety</strong> (bounds checks, lifetime control)</li> Performance</strong> (zero-copy native memory access)</li> Clarity</strong> (call native functions like Java methods)</li> Portability</strong> (same code runs across OS/CPU with correct ABI handling)</li> </ul> This demo shows: pure Java controlling a high-performance Linux feature (io_uring)</strong> — something unimaginable/complex with old JNI boilerplate.</p> A Console Routine on Channeling NATS. Let's GO! 2025-04-05T00:00:00+00:00 TL;DR</h1> This article is a short example of NATS</a> - an open source messaging system, TVIEW</a> - Golang based Terminal UI library, concurrency in Golang using Channels and Goroutines. The source code can be found on Github</a>. </p> What</h1> I have recently started working on a personal Golang project to develop something similar to Uptime Kuma</a> which is a self-hosted monitoring tool. I believe it’s a perfect project with the right complexity to learn advanced concepts of Go.</p> </p> The project code in Github</a> has 4 directories:</p> Server</strong> - The central server which stores servers & resource details, configs etc</li> Client</strong> - TUI based native client app to manage resources that need to be monitored. Also gives TUI based views into historical/real-time monitoring data.</li> Agent</strong> - Remote light-weight agent running on target host servers responsible for shipping telemetry data to the central server</li> Proto</strong> - Protobuf</a> based API contracts between server, client & agent. </li> </ol> NATS</h2> NATS is a simple, secure and performant communications system and data layer for digital systems, services and devices. It’s used in this example project for pub-sub messaging (shipping) telemetry data from target remote servers to the central server.</p> The NATS server</h3> To keep things simple for this example, we are using an embedded NATS server which is setup in the central server as below:</p> 1</td> opts := &natsServer.Options{ </span></td></tr> 2</td> Port: 4222, </span></td></tr> 3</td> } </span></td></tr> 4</td> ns, err := natsServer.NewServer(opts) </span></td></tr> 5</td> if err != nil { </span></td></tr> 6</td> log.Fatal(err) </span></td></tr> 7</td> } </span></td></tr> 8</td> go ns.Start() </span></td></tr></tbody></table></code></pre> Line #2</em> denotes that the embedded NATS server should run on port 4222.</p> Line #8</em> go ns.Start()</code> The go keyword creates a new goroutine, which is a lightweight thread managed by the Go runtime. Goroutines are a fundamental part of Go’s concurrency model.</p> When this line executes, ns.Start()</code> runs concurrently with the rest of the program. The main execution doesn’t wait for this method to complete but continues immediately to the next line. Such pattern is commonly used when launching background services, servers, or long-running processes that need to operate independently of the main program flow. </p> Publishing NATS message</h3> Let’s look at the agent code</p> 1</td> func main() { </span></td></tr> 2</td> nc, err := nats.Connect("nats://127.0.0.1:4222") </span></td></tr> 3</td> if err != nil { </span></td></tr> 4</td> log.Fatal(err) </span></td></tr> 5</td> } </span></td></tr> 6</td> defer nc.Close() </span></td></tr> 7</td> log.Println("Connected to NATS server at", nc.ConnectedUrl()) </span></td></tr> 8</td> for c := time.Tick(1 time.Second); ; <-c { </span></td></tr> 9</td> v, _ := mem.VirtualMemory() </span></td></tr> 10</td> cpuPercent, _ := cpu.Percent(0, false) </span></td></tr> 11</td> diskUsage, _ := disk.Usage("/") </span></td></tr> 12</td> </span></td></tr> 13</td> stats := &api.BaseStatsReply{ </span></td></tr> 14</td> Cpu: &cpuPercent[0], </span></td></tr> 15</td> Mem: &v.UsedPercent, </span></td></tr> 16</td> Disk: &diskUsage.UsedPercent, </span></td></tr> 17</td> } </span></td></tr> 18</td> msg, err := proto.Marshal(stats) </span></td></tr> 19</td> if err != nil { </span></td></tr> 20</td> log.Fatal(err) </span></td></tr> 21</td> } </span></td></tr> 22</td> err = nc.Publish("host.stats.1", msg) </span></td></tr> 23</td> if err != nil { </span></td></tr> 24</td> log.Fatal(err) </span></td></tr> 25</td> } </span></td></tr> 26</td> log.Printf("Published message to NATS server, #%v", stats) </span></td></tr> 27</td> } </span></td></tr> 28</td> } </span></td></tr></tbody></table></code></pre> Line 2</strong> nats.Connect("nats://127.0.0.1:4222")</code> initializes client connection to the NATS server.</p> Line 22</strong> nc.Publish("host.stats.1", msg)</code> publishes a single Protobuf serialized message containing the host base stats viz. CPU utilization, Memory utilization & Disk Usage.</p> Why</h1> Learn advanced concepts in Golang with real-life projects</li> (Try to)</em> Build a better Golang based open-source alternative to https://uptime.kuma.pet</li> To pique my interest in terminal user interface (TUI)</li> </ol>