Java FFM FunctionDescriptor 映射 C 结构体参数的布局方法

Java FFM（Foreign Function and Memory API）映射 C 结构体参数时，关键不是把每个字段都写成 Java 方法参数，而是先用 MemoryLayout 描述结构体，再把这个布局放进 FunctionDescriptor 的参数列表。这样才能把字段顺序、大小、对齐和“传结构体还是传结构体地址”分开处理。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/foreign/FunctionDescriptor.html

先把结构体布局和函数参数拆开

假设 C 侧有一个简单结构体：包含一个 32 位整数和一个双精度数，函数接收它并返回一个整数。Java 侧第一步只描述“这块内存长什么样”，不要急着写 Linker 或本地符号查找。

import java.lang.foreign.FunctionDescriptor;
import java.lang.foreign.MemoryLayout;
import java.lang.foreign.ValueLayout;

// 结构体成员按 C 声明顺序排列；字段名只是阅读和定位用的标识。
var pointLayout = MemoryLayout.structLayout(
    ValueLayout.JAVA_INT.withName("count"),
    ValueLayout.JAVA_DOUBLE.withName("score")
).withName("Point");

// 这里把整个结构体作为一个函数参数布局，而不是拆成 count、score 两个参数。
var descriptor = FunctionDescriptor.of(
    ValueLayout.JAVA_INT,
    pointLayout
);

这里的 pointLayout 是一个复合布局，descriptor 则表示“返回 int，并接收一个 Point”。两者职责不同：前者回答字段如何排列，后者回答调用边界有哪些输入和输出。

结构体值、结构体指针不能混写

C API 常见的另一种写法是 int score_point(const Point* p)。这时函数参数不是结构体本体，而是一块结构体内存的地址，FunctionDescriptor 应该使用地址布局：

import java.lang.foreign.ValueLayout;

// 指针参数表示“传入结构体所在地址”，不是把结构体字段展开。
var pointerDescriptor = FunctionDescriptor.of(
    ValueLayout.JAVA_INT,
    ValueLayout.ADDRESS
);

// 如果 C 函数没有返回值，使用 ofVoid 保留参数布局。
var fillDescriptor = FunctionDescriptor.ofVoid(
    ValueLayout.ADDRESS
);

判断标准很简单：C 声明是 Point，讨论结构体值的 ABI 布局；声明是 Point* 或 const Point*，讨论的是地址布局以及那块地址指向的目标布局。不要因为目标地址最终指向 pointLayout，就把 FunctionDescriptor 的参数直接写成 pointLayout。

对齐、字段顺序与 carrier 要一起核对

structLayout 按成员顺序组合布局，大小和自然对齐会影响它能否表达目标 ABI。字段中间若有 C 编译器插入的填充，Java 侧需要显式加入 paddingLayout，不能只看字段的逻辑类型。

可以先用 toMethodType() 看布局对应的 carrier 类型，但它主要帮助理解 Java 侧调用形状，不能替代目标平台 ABI 文档。尤其是结构体按值传递、寄存器拆分和返回规则，不能仅靠一个 Java 类型推断。

把生命周期问题留给 Arena

FunctionDescriptor 只描述签名，不负责分配或释放本地内存。实际调用时，结构体值或结构体地址必须落在仍然有效的 MemorySegment 上；Arena 的作用是控制这块内存何时失效。关闭 Arena 后，原地址即使数值没有变化，也不能继续当作有效参数。

工程上可以按下面的清单收口：

• 先从 C 声明确定是结构体值还是结构体指针。
• 再用 MemoryLayout 表达字段、填充和对齐。
• 最后把完整布局或 ADDRESS 放入 FunctionDescriptor。
• 跨平台时核对 ABI，不把 toMethodType() 当成布局验证器。

常见问题

结构体字段可以直接变成多个 FunctionDescriptor 参数吗？

只有 C 函数本身确实声明了多个独立参数时才可以。C 参数是结构体时，应保留结构体布局，避免改变 ABI 形状。

为什么传结构体指针还要保留目标布局？

FunctionDescriptor 只需要表达地址参数；目标布局用于访问或分配该地址指向的内存，两者是签名和数据的两个层次。

paddingLayout 是不是所有结构体都要手写？

不是。先按目标 ABI 计算并核对自然对齐；只有 Java 布局无法自然表达 C 侧填充时才显式加入 padding。