Library for fast mapping of Java records to native memory

TypedMemory is a Java library that enables strongly typed access to off-heap memory by mapping Java record types onto native memory. Built on the Java Foreign Function & Memory (FFM) API, it simplifies low-level memory management for performance-critical applications such as simulation, graphics, native interop, and data-oriented programming. The library targets Java 25 and later, leveraging modern Java features including records and the ClassFile API.

Overview

TypedMemory provides a type-safe abstraction over contiguous off-heap memory regions allocated via FFM’s Arena API. Instead of manually defining memory layouts, offsets, and access patterns, developers declare data structures using Java records. The library automatically derives the corresponding MemoryLayout, enabling direct get/set operations on structured memory with compile-time type safety.

The library is experimental and may introduce breaking changes. It is available from Maven Central under version 0.1.0 and is licensed under Apache 2.0.

What it does

Key capabilities include:

• Mapping Java record types to off-heap memory using Mem.of(Class<T>, Arena, count)
• Reading and writing elements via get(index) and set(index, value)
• Preserving exact memory layout for native interoperation
• Supporting nested records and fixed-size arrays via @size(n) annotation
• Wrapping existing MemorySegment instances with Mem.wrap(Class<T>, segment)
• Performing bulk operations: fill, init, copyTo, copyFrom, swap
• Exposing layout introspection through layout() for debugging and alignment verification

Example usage:

record Color(float r, float g, float b, float a) {}

try (Arena arena = Arena.ofConfined()) {
    Mem<Color> colors = Mem.of(Color.class, arena, 3);
    colors.set(0, new Color(1f, 0f, 0f));
    Color c = colors.get(0);
}

Structured records with arrays are supported:

record Pixel(int i, int j) {}
record Point(byte x, @size(3) Pixel[] y, @size(3) int[] z) {}

Tradeoffs

TypedMemory requires Java 25 or greater due to its reliance on the ClassFile API. When using reinterpret operations, applications must be launched with --enable-native-access=ALL-UNNAMED for unnamed modules or --enable-native-access=your.module.name for named modules.

Limitations include:

• No support for union types
• Arrays within records are heap-allocated, which may impact performance
• Not all schema shapes are supported; depends on carrier class evolution in Java

The project does not aim to replace the FFM API but to sit one level above it—reducing boilerplate while preserving explicit memory control and layout fidelity.

When to use it

TypedMemory is suitable for developers working on high-performance systems in Java that require off-heap data structures with native compatibility. Use cases include:

• Graphics and rendering pipelines
• Simulation or game engines
• Native interop layers
• Binary protocol processing
• Large structured datasets stored off-heap

It is particularly valuable when type safety, memory layout precision, and developer ergonomics are prioritized without sacrificing low-level control.

Benchmarks are not yet published, but early reports suggest 2x to 5x speedups over traditional approaches.