mamba-studio/TypedMemory 来源：https://github.com/mamba-studio/TypedMemory # TypedMemory

适用于 Java 25 及更高版本的类型化堆外内存。

TypedMemory 是一个 Java 库，用于通过强类型视图操作连续堆外内存。它基于 Java Foreign Function & Memory (FFM) API 构建，让您能够通过简单、 expressive 的 API 将 Java 记录类型映射到原生内存。

TypedMemory 无需为每个结构手动管理布局、偏移量和底层访问模式，它在内存之上提供了类型安全的抽象，同时保留了系统、互操作、图形、模拟和面向数据编程所需的底层控制。

import module com.mamba.typedmemory;

record Point(float x, float y) {}

void main() {
    try (Arena arena = Arena.ofConfined()) {
        Mem<Point> points = Mem.of(Point.class, arena, 10);
        points.set(0, new Point(5, 3));
        Point point = points.get(0);
        IO.println(point);
    }
}

为什么选择 TypedMemory？

直接在 Java 中操作原始内存功能强大，但通常繁琐且重复。TypedMemory 旨在通过提供以下内容使堆外编程感觉更自然：

• 连续内存的强类型视图
• 用于描述结构化数据的基于记录的模式
• 对分配和生命周期的显式控制
• 保留用于原生互操作的底层布局
• 用于快速初始化和复制的批量操作
• 设计紧密贴合 FFM 模型，而不完全隐藏内存概念

这使得它适用于：

• 原生互操作
• 面向数据编程
• 高性能内存布局
• 模拟和游戏/图形工作负载
• 存储在堆外的大型结构化数据集

特性

• 将 Java 记录类型映射到连续堆外内存
• 使用 Arena 分配内存
• 使用 get(index) / set(index, value) 读写元素
• 检查生成的 MemoryLayout
• 包装现有的 MemorySegment
• 在给定大小或地址处重新解释内存
• 填充、初始化、交换和复制内存区域
• 支持嵌套结构化数据
• 支持固定大小数组字段

状态

TypedMemory 目前处于实验阶段。核心 API 已经可用，但项目仍在演变中，随着设计的完善，可能会引入破坏性变更。

当前状态

已实现：

• 类型化内存分配
• 记录布局推导
• 类型化 get/set 访问
• 包装现有段
• 重新解释支持
• 基本批量操作

未来特性

计划实施的特性：

• 超出手动使用 long 地址的指针类型字段
• 联合体 (Unions)

要求

• Java 25 或更高版本，因为需要 ClassFile API。
• 对于重新解释调用，您的应用程序需要命令标志才能工作。
• 对于 jar 包：java --enable-native-access=ALL-UNNAMED -jar app.jar
• 对于命名模块：java --enable-native-access=your.module.name -m your.module.name/com.example.Main

构建

TypedMemory 使用 Maven 构建，目标是 Java 25。

<properties>
    <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
    <maven.compiler.release>25</maven.compiler.release>
</properties>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.2.5</version>
        </plugin>
    </plugins>
</build>

编译库：

mvn clean compile

运行测试：

mvn test

构建 jar 包：

mvn clean package

将 TypedMemory 安装到本地 Maven 仓库：

mvn clean install

在 Maven 项目中使用 / 安装

TypedMemory 可从 Maven Central 获取，因此您可以直接将其添加到项目的 pom.xml 中：

<dependency>
    <groupId>io.github.mambastudio</groupId>
    <artifactId>typedmemory</artifactId>
    <version>0.1.0</version>
</dependency>

如果您的应用程序使用 Java 模块系统，请将此添加到 module-info.java：

requires com.mamba.typedmemory;

快速示例

import module com.mamba.typedmemory;

record Color(float r, float g, float b, float a) {
    Color(float r, float g, float b) {
        this(r, g, b, 1.0f);
    }
}

void main(){
    try (Arena arena = Arena.ofConfined()) {
        Mem<Color> colors = Mem.of(Color.class, arena, 3);
        colors.set(0, new Color(1f, 0f, 0f));
        colors.set(1, new Color(0f, 1f, 0f));
        colors.set(2, new Color(0f, 0f, 1f));
        Color c = colors.get(1);
        IO.println(c); // Color[r=0.0, g=1.0, b=0.0, a=1.0]
    }
}

结构化记录示例

import module com.mamba.typedmemory;

record Pixel(int i, int j) {}

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

void main(){
    try (Arena arena = Arena.ofConfined()) {
        Mem<Point> points = Mem.of(Point.class, arena, 10);
        points.set(0, new Point(
            (byte) 7,
            new Pixel[] { new Pixel(1, 2), new Pixel(3, 4), new Pixel(5, 6) },
            new int[] { 10, 20, 30 }
        ));
        Point p = points.get(0);
        IO.println(p);
    }
}

布局内省

TypedMemory 保留底层内存布局，使其更容易检查和推理存储在堆外的实际结构。

try (Arena arena = Arena.ofConfined()) {
    Mem<Color> colors = Mem.of(Color.class, arena, 4);
    IO.println(colors.layout());
}

这在以下情况下特别有用：

• 验证原生互操作布局
• 检查对齐/填充
• 调试结构化堆外数据

包装现有内存

TypedMemory 还可以在现有的 MemorySegment 上创建类型化视图。

MemorySegment segment = ...;
Mem<Color> colors = Mem.wrap(Color.class, segment);

当内存来自以下来源时很有用：

• 原生库
• 外部分配器
• 现有的 FFM 工作流

核心 API

典型操作包括：

Mem<MyRecord> mem = Mem.of(MyRecord.class, arena, count);
mem.get(index);
mem.set(index, value);
mem.fill(value);
mem.init(i -> ...);
mem.copyTo(other);
mem.copyFrom(other);
mem.swap(i, j);
mem.segment();
mem.layout();
mem.size();
mem.type();

设计理念

TypedMemory 并不试图替换 FFM API。相反，它位于其上一层：

• 保持内存显式
• 保持布局有意义
• 减少样板代码
• 提高结构化堆外数据的可读性

目标是让底层 Java 内存编程感觉类型化、直接且实用。

为什么选择记录 (Records)？

记录为结构化内存提供了自然的类模式模型。它们提供：

• 显式状态描述
• 稳定的组件顺序
• 简洁的语法
• 非常适合生成的布局/访问代码

TypedMemory 利用这一点桥接 Java 数据定义和底层内存表示。

基准测试

即将推出。

用例

TypedMemory 尤其适用于：

• 图形和渲染管道
• 模拟系统
• 原生互操作层
• 二进制协议结构
• 高性能数据容器
• 实验性面向数据的 Java 编程

项目目标

• 使 Java 中的结构化堆外内存更易于使用
• 保留布局级推理和原生兼容性
• 提供干净的 API 而不牺牲控制
• 探索现代 Java 在底层编程中能走多远

局限性

以下是局限性：

• 需要 Java 25 或更高版本。
• 尚无联合体类型（关于如何实现有什么想法吗？）。
• 并非所有模式形状都已受支持。（让我们看看载体类将如何进展 (https://openjdk.org/projects/amber/design-notes/beyond-records)）
• Java 中的数组主要在堆上分配，因此作为记录字段的数组性能会受到影响。

贡献

欢迎反馈、问题和建议。如果您感兴趣：

• Java FFM
• 堆外数据结构
• 面向数据编程
• 原生互操作
• 底层 Java 性能

那么非常欢迎贡献和讨论。

仓库

GitHub: mamba-studio/TypedMemory

许可证

TypedMemory 根据 Apache License 2.0 许可。