The Foreign Function & Memory API (FFM) introduced in Project Panama provides MemorySegment and Arena for safe and efficient memory management outside the Java heap. These are crucial for interacting with native code and managing off-heap memory.
Why MemorySegment and Arena?
Traditional Challenges:
ByteBufferlimitations (size, lifecycle management)Unsafeoperations are… unsafe- Manual memory management prone to errors
- No bounds checking or segmentation
FFM API Benefits:
- Type-safe memory access
- Bounds checking
- Automatic resource cleanup
- Segmented memory management
- Integration with native libraries
Core Concepts
MemorySegment
A region of memory with specific bounds and access permissions.
Arena
Manages the lifecycle of memory segments. Different arena types for different use cases.
Arena Types
| Arena Type | Lifetime | Use Case |
|---|---|---|
| Global | JVM lifetime | Static/global native data |
| Automatic | Method scope | Short-lived allocations |
| Confined | Thread-bound | Thread-local allocations |
| Shared | Multi-threaded | Concurrent allocations |
Basic MemorySegment Operations
Example 1: Basic Memory Allocation and Access
import java.lang.foreign.*;
import java.lang.invoke.VarHandle;
public class BasicMemorySegmentDemo {
public static void main(String[] args) {
// Using automatic arena - automatically closed when out of scope
try (Arena arena = Arena.ofAuto()) {
// Allocate memory for 100 integers
MemorySegment segment = arena.allocate(ValueLayout.JAVA_INT, 100);
// Write values to memory
for (int i = 0; i < 100; i++) {
segment.setAtIndex(ValueLayout.JAVA_INT, i, i * 10);
}
// Read values back
for (int i = 0; i < 100; i++) {
int value = segment.getAtIndex(ValueLayout.JAVA_INT, i);
System.out.printf("Index %d: %d%n", i, value);
}
// Get segment information
System.out.printf("Segment size: %d bytes%n", segment.byteSize());
System.out.printf("Segment address: %s%n", segment.address());
System.out.printf("Is alive: %b%n", segment.scope().isAlive());
} // Arena automatically closed here, memory reclaimed
}
}
Example 2: Working with Different Data Types
import java.lang.foreign.*;
import java.nio.charset.StandardCharsets;
public class DataTypesMemoryDemo {
public static void main(String[] args) {
try (Arena arena = Arena.ofAuto()) {
// Allocate memory for different data types
MemorySegment segment = arena.allocate(
ValueLayout.JAVA_INT.byteSize() +
ValueLayout.JAVA_DOUBLE.byteSize() +
ValueLayout.JAVA_BOOLEAN.byteSize() +
50 // For string
);
// Write different data types at specific offsets
long offset = 0;
// Integer at offset 0
segment.set(ValueLayout.JAVA_INT, offset, 42);
offset += ValueLayout.JAVA_INT.byteSize();
// Double at offset 4
segment.set(ValueLayout.JAVA_DOUBLE, offset, 3.14159);
offset += ValueLayout.JAVA_DOUBLE.byteSize();
// Boolean at offset 12
segment.set(ValueLayout.JAVA_BOOLEAN, offset, true);
offset += ValueLayout.JAVA_BOOLEAN.byteSize();
// String at offset 13
String text = "Hello, MemorySegment!";
byte[] textBytes = text.getBytes(StandardCharsets.UTF_8);
MemorySegment.copy(
textBytes, 0,
segment, ValueLayout.JAVA_BYTE, offset,
textBytes.length
);
// Read back the values
offset = 0;
System.out.printf("Integer: %d%n",
segment.get(ValueLayout.JAVA_INT, offset));
offset += ValueLayout.JAVA_INT.byteSize();
System.out.printf("Double: %f%n",
segment.get(ValueLayout.JAVA_DOUBLE, offset));
offset += ValueLayout.JAVA_DOUBLE.byteSize();
System.out.printf("Boolean: %b%n",
segment.get(ValueLayout.JAVA_BOOLEAN, offset));
offset += ValueLayout.JAVA_BOOLEAN.byteSize();
// Read string back
String readText = segment.getString(offset, StandardCharsets.UTF_8);
System.out.printf("String: %s%n", readText);
}
}
}
Arena Allocation Strategies
Example 3: Different Arena Types
import java.lang.foreign.*;
import java.util.concurrent.*;
public class ArenaTypesDemo {
// Global Arena - lives for the entire JVM lifetime
private static final Arena GLOBAL_ARENA = Arena.global();
private static final MemorySegment GLOBAL_DATA =
GLOBAL_ARENA.allocate(ValueLayout.JAVA_INT, 1);
public static void automaticArenaDemo() {
System.out.println("=== Automatic Arena Demo ===");
// Automatic arena - automatically closed when method exits
try (Arena arena = Arena.ofAuto()) {
MemorySegment segment = arena.allocate(ValueLayout.JAVA_INT, 10);
for (int i = 0; i < 10; i++) {
segment.setAtIndex(ValueLayout.JAVA_INT, i, i * 5);
}
System.out.println("Automatic arena allocated memory");
System.out.printf("Segment scope alive: %b%n", segment.scope().isAlive());
} // Automatically closed here
System.out.println("Automatic arena closed");
}
public static void confinedArenaDemo() throws Exception {
System.out.println("\n=== Confined Arena Demo ===");
// Confined arena - bound to current thread
try (Arena arena = Arena.ofConfined()) {
MemorySegment segment = arena.allocate(ValueLayout.JAVA_LONG, 5);
// This works - same thread
segment.setAtIndex(ValueLayout.JAVA_LONG, 0, 100L);
// Try accessing from different thread (will fail)
ExecutorService executor = Executors.newSingleThreadExecutor();
try {
Future<?> future = executor.submit(() -> {
// This will throw IllegalStateException - confined to creator thread
segment.setAtIndex(ValueLayout.JAVA_LONG, 1, 200L);
});
future.get(); // Wait for completion
} catch (Exception e) {
System.out.println("Expected error from different thread: " + e.getCause());
} finally {
executor.shutdown();
}
}
}
public static void sharedArenaDemo() throws Exception {
System.out.println("\n=== Shared Arena Demo ===");
// Shared arena - can be accessed by multiple threads
try (Arena arena = Arena.ofShared()) {
MemorySegment segment = arena.allocate(ValueLayout.JAVA_INT, 100);
// Initialize with zeros
for (int i = 0; i < 100; i++) {
segment.setAtIndex(ValueLayout.JAVA_INT, i, 0);
}
// Access from multiple threads
int threadCount = 10;
ExecutorService executor = Executors.newFixedThreadPool(threadCount);
CountDownLatch latch = new CountDownLatch(threadCount);
for (int i = 0; i < threadCount; i++) {
final int threadId = i;
executor.submit(() -> {
try {
// Each thread writes to different portions
int startIndex = threadId * 10;
for (int j = 0; j < 10; j++) {
segment.setAtIndex(ValueLayout.JAVA_INT, startIndex + j, threadId);
}
System.out.printf("Thread %d completed writing%n", threadId);
} finally {
latch.countDown();
}
});
}
latch.await();
executor.shutdown();
// Verify writes
for (int i = 0; i < 100; i++) {
int expected = i / 10;
int actual = segment.getAtIndex(ValueLayout.JAVA_INT, i);
if (actual != expected) {
System.out.printf("Mismatch at index %d: expected %d, got %d%n",
i, expected, actual);
}
}
System.out.println("Shared arena multi-threaded access completed");
}
}
public static void main(String[] args) throws Exception {
automaticArenaDemo();
confinedArenaDemo();
sharedArenaDemo();
// Global arena persists
System.out.println("\n=== Global Arena ===");
GLOBAL_DATA.set(ValueLayout.JAVA_INT, 0, 999);
System.out.printf("Global data value: %d%n",
GLOBAL_DATA.get(ValueLayout.JAVA_INT, 0));
}
}
Advanced MemorySegment Operations
Example 4: Structured Data (Like C Structs)
import java.lang.foreign.*;
import java.lang.invoke.VarHandle;
public class StructMemoryDemo {
// Define a struct layout similar to:
// struct Person {
// int id;
// double salary;
// char name[50];
// boolean active;
// }
private static final GroupLayout PERSON_STRUCT = MemoryLayout.structLayout(
ValueLayout.JAVA_INT.withName("id"),
ValueLayout.JAVA_DOUBLE.withName("salary"),
MemoryLayout.sequenceLayout(50, ValueLayout.JAVA_BYTE).withName("name"),
ValueLayout.JAVA_BOOLEAN.withName("active")
);
// Create VarHandles for type-safe access
private static final VarHandle ID_HANDLE =
PERSON_STRUCT.varHandle(MemoryLayout.PathElement.groupElement("id"));
private static final VarHandle SALARY_HANDLE =
PERSON_STRUCT.varHandle(MemoryLayout.PathElement.groupElement("salary"));
private static final VarHandle ACTIVE_HANDLE =
PERSON_STRUCT.varHandle(MemoryLayout.PathElement.groupElement("active"));
public static void main(String[] args) {
try (Arena arena = Arena.ofAuto()) {
// Allocate memory for the struct
MemorySegment personSegment = arena.allocate(PERSON_STRUCT);
// Write data using VarHandles
ID_HANDLE.set(personSegment, 0L, 12345);
SALARY_HANDLE.set(personSegment, 0L, 75000.50);
ACTIVE_HANDLE.set(personSegment, 0L, true);
// Write string to name field
String name = "John Doe";
MemorySegment nameSegment = personSegment.asSlice(
PERSON_STRUCT.byteOffset(MemoryLayout.PathElement.groupElement("name")),
50
);
MemorySegment.copy(
name.getBytes(), 0,
nameSegment, ValueLayout.JAVA_BYTE, 0,
Math.min(name.length(), 49)
);
// Null terminate
nameSegment.set(ValueLayout.JAVA_BYTE, name.length(), (byte) 0);
// Read data back
int id = (int) ID_HANDLE.get(personSegment, 0L);
double salary = (double) SALARY_HANDLE.get(personSegment, 0L);
boolean active = (boolean) ACTIVE_HANDLE.get(personSegment, 0L);
String readName = nameSegment.getString(0);
System.out.printf("Person: id=%d, name=%s, salary=%.2f, active=%b%n",
id, readName, salary, active);
// Array of structs
System.out.println("\n=== Array of Structs ===");
int arraySize = 5;
MemorySegment arraySegment = arena.allocate(
PERSON_STRUCT.byteSize() * arraySize
);
for (int i = 0; i < arraySize; i++) {
MemorySegment element = arraySegment.asSlice(
i * PERSON_STRUCT.byteSize(),
PERSON_STRUCT.byteSize()
);
ID_HANDLE.set(element, 0L, 1000 + i);
SALARY_HANDLE.set(element, 0L, 50000.0 + (i * 10000));
ACTIVE_HANDLE.set(element, 0L, i % 2 == 0);
// Write name
MemorySegment elementName = element.asSlice(
PERSON_STRUCT.byteOffset(MemoryLayout.PathElement.groupElement("name")),
50
);
String personName = "Person-" + i;
MemorySegment.copy(
personName.getBytes(), 0,
elementName, ValueLayout.JAVA_BYTE, 0,
Math.min(personName.length(), 49)
);
elementName.set(ValueLayout.JAVA_BYTE, personName.length(), (byte) 0);
}
// Read array back
for (int i = 0; i < arraySize; i++) {
MemorySegment element = arraySegment.asSlice(
i * PERSON_STRUCT.byteSize(),
PERSON_STRUCT.byteSize()
);
int elementId = (int) ID_HANDLE.get(element, 0L);
double elementSalary = (double) SALARY_HANDLE.get(element, 0L);
boolean elementActive = (boolean) ACTIVE_HANDLE.get(element, 0L);
MemorySegment elementName = element.asSlice(
PERSON_STRUCT.byteOffset(MemoryLayout.PathElement.groupElement("name")),
50
);
String nameStr = elementName.getString(0);
System.out.printf(" [%d] id=%d, name=%s, salary=%.2f, active=%b%n",
i, elementId, nameStr, elementSalary, elementActive);
}
}
}
}
Example 5: Memory Segments and Slicing
import java.lang.foreign.*;
public class SegmentSlicingDemo {
public static void main(String[] args) {
try (Arena arena = Arena.ofAuto()) {
// Allocate a large segment
MemorySegment largeSegment = arena.allocate(1024); // 1KB
// Initialize with pattern
for (long i = 0; i < largeSegment.byteSize(); i++) {
largeSegment.set(ValueLayout.JAVA_BYTE, i, (byte) (i % 256));
}
// Create slices (views) of the original segment
MemorySegment slice1 = largeSegment.asSlice(0, 100); // Bytes 0-99
MemorySegment slice2 = largeSegment.asSlice(100, 200); // Bytes 100-299
MemorySegment slice3 = largeSegment.asSlice(300, 724); // Bytes 300-1023
System.out.printf("Original segment size: %d bytes%n", largeSegment.byteSize());
System.out.printf("Slice 1 size: %d bytes%n", slice1.byteSize());
System.out.printf("Slice 2 size: %d bytes%n", slice2.byteSize());
System.out.printf("Slice 3 size: %d bytes%n", slice3.byteSize());
// Verify slices point to same underlying memory
slice1.set(ValueLayout.JAVA_BYTE, 0, (byte) 0xFF);
byte originalValue = largeSegment.get(ValueLayout.JAVA_BYTE, 0);
System.out.printf("Modified slice1[0]=0x%02X, largeSegment[0]=0x%02X%n",
slice1.get(ValueLayout.JAVA_BYTE, 0) & 0xFF,
originalValue & 0xFF);
// Working with aligned slices
System.out.println("\n=== Aligned Access ===");
MemorySegment alignedSegment = arena.allocate(
ValueLayout.JAVA_INT.byteSize() * 10
);
// Ensure aligned access for better performance
for (int i = 0; i < 10; i++) {
long offset = i * ValueLayout.JAVA_INT.byteSize();
alignedSegment.set(ValueLayout.JAVA_INT, offset, i * 1000);
}
// Read back aligned values
for (int i = 0; i < 10; i++) {
long offset = i * ValueLayout.JAVA_INT.byteSize();
int value = alignedSegment.get(ValueLayout.JAVA_INT, offset);
System.out.printf("Aligned[%d] = %d%n", i, value);
}
}
}
}
Real-World Use Cases
Example 6: Native Library Integration
import java.lang.foreign.*;
import java.lang.invoke.MethodHandle;
public class NativeLibraryDemo {
// Load standard C library
private static final Linker LINKER = Linker.nativeLinker();
private static final SymbolLookup STD_LIB = LINKER.defaultLookup();
public static void callStringFunctions() throws Throwable {
try (Arena arena = Arena.ofAuto()) {
// Get method handles for C functions
MethodHandle strlenHandle = LINKER.downcallHandle(
STD_LIB.find("strlen").orElseThrow(),
FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
);
MethodHandle strcpyHandle = LINKER.downcallHandle(
STD_LIB.find("strcpy").orElseThrow(),
FunctionDescriptor.of(ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.ADDRESS)
);
// Allocate memory for strings
String source = "Hello, Native World!";
MemorySegment sourceSegment = arena.allocateUtf8String(source);
MemorySegment destSegment = arena.allocate(source.length() + 1);
// Call strcpy
MemorySegment result = (MemorySegment) strcpyHandle.invoke(
destSegment, sourceSegment
);
// Call strlen
long length = (long) strlenHandle.invoke(destSegment);
System.out.printf("Copied string: %s%n", destSegment.getString(0));
System.out.printf("String length: %d%n", length);
}
}
public static void customNativeFunction() throws Throwable {
try (Arena arena = Arena.ofAuto()) {
// Define a function that processes an array of integers
FunctionDescriptor processArrayDesc = FunctionDescriptor.of(
ValueLayout.JAVA_INT, // return type
ValueLayout.ADDRESS, // array pointer
ValueLayout.JAVA_INT // array size
);
// Allocate and initialize array
int[] javaArray = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
MemorySegment nativeArray = arena.allocate(
ValueLayout.JAVA_INT.byteSize() * javaArray.length
);
// Copy Java array to native memory
for (int i = 0; i < javaArray.length; i++) {
nativeArray.setAtIndex(ValueLayout.JAVA_INT, i, javaArray[i]);
}
// In real scenario, you'd link to actual native library
System.out.println("Native array allocated and initialized");
System.out.printf("Array address: %s%n", nativeArray.address());
// Process array and copy back (simulated)
for (int i = 0; i < javaArray.length; i++) {
int value = nativeArray.getAtIndex(ValueLayout.JAVA_INT, i);
nativeArray.setAtIndex(ValueLayout.JAVA_INT, i, value * 2);
}
// Copy back to Java array
for (int i = 0; i < javaArray.length; i++) {
javaArray[i] = nativeArray.getAtIndex(ValueLayout.JAVA_INT, i);
}
System.out.print("Processed array: ");
for (int value : javaArray) {
System.out.print(value + " ");
}
System.out.println();
}
}
public static void main(String[] args) {
try {
callStringFunctions();
System.out.println();
customNativeFunction();
} catch (Throwable t) {
t.printStackTrace();
}
}
}
Memory Management Best Practices
Example 7: Resource Management Patterns
import java.lang.foreign.*;
import java.util.concurrent.atomic.AtomicBoolean;
public class ResourceManagementDemo {
// Resource that uses native memory
public static class NativeImage implements AutoCloseable {
private final MemorySegment pixelData;
private final Arena arena;
private final AtomicBoolean closed;
public NativeImage(int width, int height) {
this.arena = Arena.ofConfined();
this.closed = new AtomicBoolean(false);
// Allocate memory for image pixels (RGBA format)
long imageSize = (long) width * height * 4; // 4 bytes per pixel
this.pixelData = arena.allocate(imageSize);
// Initialize with transparent black
for (long i = 0; i < imageSize; i++) {
pixelData.set(ValueLayout.JAVA_BYTE, i, (byte) 0);
}
System.out.printf("Allocated image: %dx%d (%d bytes)%n",
width, height, imageSize);
}
public void setPixel(int x, int y, byte r, byte g, byte b, byte a) {
if (closed.get()) {
throw new IllegalStateException("Image already closed");
}
long offset = ((long) y * getWidth() + x) * 4;
pixelData.set(ValueLayout.JAVA_BYTE, offset, r);
pixelData.set(ValueLayout.JAVA_BYTE, offset + 1, g);
pixelData.set(ValueLayout.JAVA_BYTE, offset + 2, b);
pixelData.set(ValueLayout.JAVA_BYTE, offset + 3, a);
}
public int getWidth() {
// Simplified - in real scenario, store dimensions separately
return 1024;
}
public int getHeight() {
return 768;
}
public MemorySegment getPixelData() {
if (closed.get()) {
throw new IllegalStateException("Image already closed");
}
return pixelData;
}
@Override
public void close() {
if (closed.compareAndSet(false, true)) {
System.out.println("Closing NativeImage and freeing memory");
arena.close();
}
}
@Override
protected void finalize() throws Throwable {
if (!closed.get()) {
System.err.println("Warning: NativeImage not properly closed!");
close();
}
super.finalize();
}
}
public static void main(String[] args) {
// Using try-with-resources for automatic cleanup
try (NativeImage image = new NativeImage(1024, 768)) {
// Use the image
image.setPixel(100, 100, (byte) 255, (byte) 0, (byte) 0, (byte) 255); // Red
image.setPixel(101, 100, (byte) 0, (byte) 255, (byte) 0, (byte) 255); // Green
image.setPixel(102, 100, (byte) 0, (byte) 0, (byte) 255, (byte) 255); // Blue
System.out.println("Image operations completed");
} // Automatic close() called here
System.out.println("Image resources freed");
// Manual management example
NativeImage manualImage = new NativeImage(512, 512);
try {
manualImage.setPixel(50, 50, (byte) 255, (byte) 255, (byte) 255, (byte) 255);
} finally {
manualImage.close();
}
}
}
Performance Considerations
- Arena Selection: Choose the right arena type for your use case
- Alignment: Use aligned access for better performance
- Bounds Checking: FFM provides bounds checking - balance safety vs performance
- Memory Layout: Optimize memory layout for cache efficiency
- Resource Cleanup: Always close arenas to prevent memory leaks
Conclusion
MemorySegment and Arena provide:
- Type-safe memory access
- Bounds-checked operations
- Automatic resource management
- Structured memory layouts
- Native interoperability
Key Benefits:
- Safety: No more segmentation faults in Java
- Performance: Efficient memory access patterns
- Productivity: High-level API for complex memory operations
- Interoperability: Seamless native library integration
When to Use:
- High-performance computing
- Native library integration
- Large off-heap data structures
- Real-time data processing
- Memory-mapped I/O operations
The FFM API represents a significant step forward in Java's capabilities for systems programming and high-performance applications.
Next Steps: Explore the jextract tool for automatically generating Java bindings from C header files, and practice with real native libraries to master MemorySegment and Arena usage patterns.