17370845950

本文详解使用 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），也杜绝了内存泄漏风险。