Roray FFM Utils

Overview

Roray FFM Utils is the foundation layer of the MVP.Express stack. It provides high-level, type-safe abstractions over JDK’s Foreign Function & Memory (FFM) API, enabling efficient off-heap memory management without the complexity of raw pointer manipulation.

Key Features

Off-Heap Memory Management

• Arena-based allocation with automatic cleanup
• Reference counting for shared memory segments
• Type-safe memory layouts with compile-time validation
• Zero-copy slicing for efficient buffer management

Native Syscall Bindings

• Linux io_uring support for async I/O
• Direct socket operations bypassing Java’s networking stack
• Memory-mapped file I/O with proper resource management

FFM Integration

• Clean abstractions over MemorySegment and Arena
• Structured access using MemoryLayout
• Automatic native library loading and symbol lookup

Quick Example

// Allocate off-heap memory with automatic cleanup
try (var arena = Arena.ofConfined()) {
    // Allocate a buffer
    var segment = arena.allocate(1024);
    
    // Type-safe structured access
    var layout = MemoryLayout.structLayout(
        ValueLayout.JAVA_INT.withName("id"),
        ValueLayout.JAVA_LONG.withName("timestamp"),
        MemoryLayout.sequenceLayout(32, ValueLayout.JAVA_BYTE).withName("data")
    );
    
    // Get a VarHandle for efficient field access
    var idHandle = layout.varHandle(PathElement.groupElement("id"));
    var timestampHandle = layout.varHandle(PathElement.groupElement("timestamp"));
    
    // Write data
    idHandle.set(segment, 0, 42);
    timestampHandle.set(segment, 0, System.currentTimeMillis());
    
    // Memory is automatically freed when arena closes
}

Use Cases

• Custom allocators for performance-critical applications
• Memory-mapped data structures for persistent storage
• Native library integration without JNI
• Zero-copy I/O with direct buffer management

Performance Characteristics

Requirements

• Java 25+ with --enable-preview and --enable-native-access
• Linux 5.1+ for io_uring features (optional)

Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("express.mvp:roray-ffm-utils:0.1.0")
}

// Enable preview features
tasks.withType<JavaCompile> {
    options.compilerArgs.addAll(listOf("--enable-preview"))
}

tasks.withType<JavaExec> {
    jvmArgs("--enable-preview", "--enable-native-access=ALL-UNNAMED")
}

Maven

<dependency>
    <groupId>express.mvp</groupId>
    <artifactId>roray-ffm-utils</artifactId>
    <version>0.1.0</version>
</dependency>