Roray FFM Utils Quickstart

Early Development Notice

All MVP.Express projects are currently in active development (pre-1.0.0) and should not be used in production environments. APIs may change without notice, and breaking changes are expected until each project reaches version 1.0.0. We welcome early adopters and contributors, but please use at your own risk.

Get started with high-performance memory management in 5 minutes.

Prerequisites

  • Java 24+ with preview features enabled
  • Gradle 8.5+ or Maven 3.9+

Installation

Add to your build.gradle.kts:

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

Quick Example

Memory Segment Pool

Efficiently allocate and release off-heap memory:

import express.mvp.roray.utils.memory.MemorySegmentPool;
import java.lang.foreign.MemorySegment;

// Create a pool with 64 segments of 4KB each
var pool = MemorySegmentPool.create(64, 4096);

// Borrow a segment (zero-allocation after warmup)
MemorySegment segment = pool.borrow();

try {
    // Write data directly to off-heap memory
    segment.set(ValueLayout.JAVA_LONG, 0, 42L);
    segment.set(ValueLayout.JAVA_DOUBLE, 8, 3.14159);
    
    // Read it back
    long value = segment.get(ValueLayout.JAVA_LONG, 0);
} finally {
    // Return segment to the pool
    pool.release(segment);
}

Zero-Copy String Handling

Work with UTF-8 strings without allocating:

import express.mvp.roray.utils.memory.Utf8View;

// Wrap a memory region as a UTF-8 view
Utf8View view = Utf8View.wrap(segment, offset, length);

// Compare strings without allocation
if (view.equalsString("expected")) {
    // Handle match
}

// Convert to String only when needed
String str = view.toString();

JVM Arguments

Enable FFM preview features:

java --enable-preview --enable-native-access=ALL-UNNAMED -jar myapp.jar

For Gradle:

tasks.withType<JavaCompile> {
    options.compilerArgs.add("--enable-preview")
}

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

Next Steps