Introducing Panama architecture and terminology – Foreign (Function) Memory API

141. Introducing Panama architecture and terminology

When we talk about architecture, we have to present a meaningful diagram, so here it is:

Figure 7.8 – Project Panama architecture

This diagram reveals the interoperability of Panama’s components. The climax of this diagram is the Jextract tool. As you’ll see in this chapter, Jextract is a very handy tool capable to consume the headers of native libraries and producing low-level Java native bindings. These bindings are the unit of work for two major APIs of the Project Panama:

Foreign Memory API – used to allocate/deallocate off-heap/on-heap memory

Foreign Linker API – used to call foreign functions directly from Java and vice versa

The process described so far is entirely mechanical. When these APIs and the low-level Java native bindings are not enough for our tasks then we can make a step further and create a set of higher-level Java bindings. Of course, this is not a task for novices but it is very powerful. For instance, you may have an existing automation tool for generating JNI bindings and now you want to modernize your tool to generate a higher-level of pure Java bindings in Panama’s style. Among the abstractions used by Project Panama we have the following:

java.lang.foreign.MemorySegment – This API shapes a heap or native memory segment. A heap segment accesses on-heap memory, while a native segment accesses off-heap memory. In both cases, we talk about a contiguous region of memory that has a lifespan bounded by space and time.

java.lang.foreign.Arena (or, MemorySession in JDK versions earlier than 20) – This API can control the memory segment’s lifespan.

java.lang.foreign.SegmentScope – This API represents the scope of a memory segment (global, auto, or arena scope)

java.lang.foreign.MemoryLayout – This API describes the content of memory segments as memory layouts. For instance, among the available memory layouts, in the context of basic Java data types (int, double, long, and so on), we have memory value layouts (java.lang.foreign.ValueLayout).

Of course, next to these three pillars, we have many other classes and helpers. In the next problems, we will cover several scenarios meant to get us familiar with the major aspects of using the Project Panama’s APIs.