本文详解使用 jna 调用接收 `byte**` 参数的 c 原生函数（如 voicevox core 的 `voicevox_wav_synthesize`）时，如何在 scala/java 中安全传入指针引用、读取动态分配的字节数组，并正确释放内存。
在 Java/Scala 中通过 JNA 调用 C 原生库时，遇到形如 int func(byte** output) 的函数签名，核心难点在于：byte** 并非指向 Java 数组的简单指针，而是「指向指针的指针」——即 C 函数将*动态分配一块内存（如 malloc）并将该内存首地址写入你提供的 `byte变量所指向的位置**。因此，Java 端必须提供一个可被原生代码修改的「指针容器」，而非直接传入数组或Memory`。
JNA 提供的标准解决方案是 com.sun.jna.PointerByReference。它封装了一个可被原生代码写入的 Pointer 地址，完美对应 C 中的 byte** 语义。
✅ 正确声明与调用方式
首先，在 JNA 接口类中正确定义方法：
import com.sun.jna.{Library, Pointer, PointerByReference}
import com.sun.jna.win32.W32APIOptions
trait NativeLibrary extends Library {
// ✅ 正确：接受 PointerByReference，对应 C 的 byte**
def voicevox_wav_synthesize(
coreHandle: Pointer,
query: Pointer,
speakerId: Int,
output: PointerByReference
): Int
// ✅ 对应 C 的 void voicevox_wav_free(byte* ptr)
def voicevox_wav_free(ptr: Pointer): Unit
}⚠️ 注意：不要尝试使用 Array[Byte]（对应 byte*）、Array[Array[Byte]]（JNA 不支持）或裸 Memory（虽能编译但语义错误，易导致 SEGV 或内存泄漏）。
✅ 完整调用流程（含内存管理）
以下为生产级调用示例（以 VOICEVOX Core 为例），包含关键步骤与错误规避点：
val pbr = new PointerByReference() // 创建指针引用容器
// 调用原生函数：它将 malloc 一块内存，并把地址写入 pbr 内部
val resultCode = NativeLibrary.INSTANCE.voicevox_wav_synthesize(
coreHandle,
queryPtr,
speakerId,
pbr
)
if (resultCode != 0) {
throw new RuntimeException(s"Synthesis failed with code $resultCode")
}
// ✅ 获取原生函数分配的 byte*（即实际数据起始地址）
val dataPtr = pbr.getValue()
if (dataPtr == null || dataPtr.equals(Pointer.NULL)) {
throw new IllegalStateException("Native function returned null pointer")
}
// ? 关键：必须知道返回数据的实际长度！
// VOICEVOX Core 的 wav 相关函数通常配套提供 size 获取接口（如 voicevox_wav_get_size）
// 或需在调用前预估/约定长度（如 WAV 头 + PCM 数据）。此处假设已知 size:
val wavSize = getWavDataSize() // 请根据实际 API 补充实现（例如调用 voicevox_wav_get_size）
// ✅ 安全读取为 Java byte 数组
val wavBytes = dataPtr.getByteArray(0, wavSize)
// ✅ 必须显式释放原生内存！否则造成内存泄漏
NativeLibrary.INSTANCE.voicevox_wav_free(dataPtr)⚠️ 重要注意事项
- 长度不可猜测：getByteArray(0, size) 的 size 必须准确。若传入过大，会读取非法内存（崩溃）；过小则数据截断。务必通过配套 API（如 voicevox_wav_get_size()）或协议约定获取真实长度。
- 及时释放：所有由原生函数 malloc/new 分配、并通过 byte** 返回的内存，必须调用对应的 free 函数（如 voicevox_wav_free）释放。JNA 不会自动管理此类跨语言堆内存。
- 线程安全：PointerByReference 实例不可复用。每次调用都应创建新实例，避免多线程竞争。
- 空值检查：始终检查 pbr.getValue() 是否为 null 或 Pointer.NULL，防止空解引用。
- Scala 兼容性：上述代码在 Scala 2/3 中完全适用，无需额外适配。
通过 PointerByReference 这一语义精准的工具，你就能安全、高效地桥接 Java/Scala 与要求 byte** 的 C 原生世界，既避免了段错误（SEGV），也杜绝了内存泄漏风险。
