N-API 中 ThreadSafeFunction 阻塞事件循环退出的解决方案

在使用 N-API 的 ObjectWrap 封装 C++ 对象并结合 ThreadSafeFunction 进行跨线程回调时，如果未正确管理 ThreadSafeFunction 的引用，可能会导致 Node.js 事件循环无法正常退出。本文将深入探讨这一问题，并提供通过调用 Unref() 方法来解除强引用以及使用 HandleScope 确保 N-API 资源正确管理的解决方案，从而使程序在任务完成后能够顺利终止。

N-API 与 ThreadSafeFunction 概述

N-API（Node.js API）提供了一种稳定的 ABI（应用程序二进制接口），允许开发者使用 C++ 编写高性能的 Node.js 模块。Napi::ThreadSafeFunction 是 N-API 中的一个关键组件，它使得在 C++ 线程中安全地调用 JavaScript 回调函数成为可能，从而避免了线程同步问题和主线程阻塞。

当 C++ 代码需要在非主线程（例如，由底层 C 库启动的异步操作）中触发 JavaScript 回调时，ThreadSafeFunction 提供了一个可靠的桥梁。它允许将 JavaScript 函数的引用安全地传递到 C++ 线程，并在需要时通过 Call() 或 BlockingCall() 方法在 Node.js 事件循环线程中执行该 JavaScript 函数。

问题分析：ThreadSafeFunction 导致事件循环阻塞

默认情况下，当一个 Napi::ThreadSafeFunction 被创建并持有对 JavaScript 函数的引用时，它会向 Node.js 事件循环添加一个“强引用”（ref）。这意味着，只要这个 ThreadSafeFunction 实例存在且未被显式地“解引用”（unref），Node.js 事件循环就会保持活跃状态，即使没有其他待处理的事件，进程也不会退出。

在 ObjectWrap 类中，如果 ThreadSafeFunction 作为成员变量存在，并且在对象的生命周期内没有被 Release() 或 Unref()，即使所有 JavaScript 代码执行完毕，Node.js 进程也会持续运行，直到被强制终止（例如，通过 CTRL+C）。这通常发生在异步操作完成后，但 ThreadSafeFunction 仍然持有一个强引用，阻止了事件循环的正常退出。

考虑以下简化的问题代码示例：

// ... 其他 AdapterWrapper 类定义 ...

Napi::Value AdapterWrapper::SetOnScanStart(const Napi::CallbackInfo &info) {
  Napi::Env env = info.Env();
  // 仅创建 ThreadSafeFunction，未Unref
  this->onScanStartFn = Napi::ThreadSafeFunction::New(
      env, info[0].As(), "onScanStartFn", 0, 1);
  adapter_set_on_scan_start(this->handle, onScanStart, this);
  return env.Undefined(); // 返回值缺失，添加
}

Napi::Value AdapterWrapper::SetOnScanStop(const Napi::CallbackInfo &info) {
  Napi::Env env = info.Env();
  // 仅创建 ThreadSafeFunction，未Unref
  this->onScanStopFn = Napi::ThreadSafeFunction::New(
      env, info[0].As(), "onScanStopFn", 0, 1);
  adapter_set_on_scan_stop(this->handle, onScanStop, this);
  return env.Undefined(); // 返回值缺失，添加
}

void AdapterWrapper::onScanStart(adapter_t handle, void *userdata) {
  auto adapter = reinterpret_cast(userdata);
  auto callback = [](Napi::Env env, Napi::Function jsCallback) {
    jsCallback.Call({});
  };
  // 修正：应通过实例访问成员
  adapter->onScanStartFn.BlockingCall(callback);
}

void AdapterWrapper::onScanStop(adapter_t handle, void *userdata) {
  auto adapter = reinterpret_cast(userdata);
  auto callback = [](Napi::Env env, Napi::Function jsCallback) {
    jsCallback.Call({});
  };
  adapter->onScanStopFn.BlockingCall(callback);
}

在上述代码中，onScanStartFn 和 onScanStopFn 被创建后，默认持有强引用。这意味着即使 adapter_set_on_scan_start 和 adapter_set_on_scan_stop 所设置的底层 C 回调不再被触发，或者 Node.js 应用程序逻辑已经完成，这些 ThreadSafeFunction 仍然会阻止事件循环退出。

唱鸭

音乐创作全流程的AI自动作曲工具，集 AI 辅助作词、AI 自动作曲、编曲、混音于一体

下载

解决方案：Unref() 与 HandleScope

要解决 ThreadSafeFunction 阻塞事件循环的问题，关键在于理解 Node.js 的引用计数机制。当一个 ThreadSafeFunction 不再需要阻止进程退出时，应调用其 Unref() 方法。同时，为了确保 N-API 内部资源的正确管理，尤其是在 JavaScript 回调函数中，使用 Napi::HandleScope 也是一个良好的实践。

Napi::ThreadSafeFunction::Unref() 的作用

Unref() 方法将 ThreadSafeFunction 的引用类型从“强引用”更改为“弱引用”。这意味着 Node.js 事件循环在判断是否退出时，将不再考虑这个 ThreadSafeFunction 的存在。即使 ThreadSafeFunction 实例仍然活跃并可以被调用，它也不会阻止进程在没有其他强引用时自动退出。这对于那些在后台运行，但不应影响主进程生命周期的异步任务非常有用。

Napi::HandleScope 的作用

Napi::HandleScope 用于管理在 C++ 代码中创建的 N-API 值（如 Napi::Function、Napi::Object 等）的生命周期。每当 N-API 函数被调用时，通常会在内部创建一个句柄作用域。当作用域结束时，所有在该作用域内创建的 N-API 句柄都会被垃圾回收。在 C++ 回调函数（如 SetOnScanStart）中显式使用 HandleScope 可以防止潜在的内存泄漏，确保临时 N-API 值得到及时清理。

优化后的代码示例

以下是应用 Unref() 和 HandleScope 后的 AdapterWrapper 类相关方法的修改：

class AdapterWrapper : public Napi::ObjectWrap { // 修正：Adapter -> AdapterWrapper
public:
  static Napi::Object Init(Napi::Env env, Napi::Object exports);
  AdapterWrapper(const Napi::CallbackInfo &info);
  ~AdapterWrapper();

  static Napi::FunctionReference constructor;

private:
  adapter_t handle;
  Napi::ThreadSafeFunction onScanStartFn;
  Napi::ThreadSafeFunction onScanStopFn;

  static void onScanStart(adapter_t handle, void *userdata);
  static void onScanStop(adapter_t handle, void *userdata);

  Napi::Value Scan(const Napi::CallbackInfo &info); // 修正：ScanStart -> Scan
  void SetOnScanStart(const Napi::CallbackInfo &info);
  void SetOnScanStop(const Napi::CallbackInfo &info);
};

Napi::FunctionReference AdapterWrapper::constructor;

Napi::Object AdapterWrapper::Init(Napi::Env env, Napi::Object exports) {
  Napi::Function func = DefineClass(env, "Adapter", {
    InstanceMethod("scan", &AdapterWrapper::Scan), // 修正：ScanStart -> Scan
    InstanceMethod("setOnScanStart", &AdapterWrapper::SetOnScanStart),
    InstanceMethod("setOnScanStop", &AdapterWrapper::SetOnScanStop)
  });

  constructor = Napi::Persistent(func);
  constructor.SuppressDestruct();

  exports.Set("Adapter", func);
  return exports;
}

AdapterWrapper::AdapterWrapper(const Napi::CallbackInfo &info)
    : Napi::ObjectWrap(info) {
  Napi::Env env = info.Env();
  this->handle = adapter_get_handle();
}

AdapterWrapper::~AdapterWrapper() {
  adapter_release_handle(this->handle);
  if (this->onScanStartFn) {
    this->onScanStartFn.Release();
  }
  if (this->onScanStopFn) {
    this->onScanStopFn.Release();
  }
}

Napi::Value AdapterWrapper::SetOnScanStart(const Napi::CallbackInfo &info) {
  Napi::Env env = info.Env();
  Napi::HandleScope scope(env); // 添加 HandleScope

  this->onScanStartFn = Napi::ThreadSafeFunction::New(
      env, info[0].As(), "onScanStartFn", 0, 1);
  this->onScanStartFn.Unref(env); // 添加 Unref

  adapter_set_on_scan_start(this->handle, onScanStart, this);
  return env.Undefined(); // 确保返回 Napi::Value
}

Napi::Value AdapterWrapper::SetOnScanStop(const Napi::CallbackInfo &info) {
  Napi::Env env = info.Env();
  Napi::HandleScope scope(env); // 添加 HandleScope

  this->onScanStopFn = Napi::ThreadSafeFunction::New(
      env, info[0].As(), "onScanStopFn", 0, 1);
  this->onScanStopFn.Unref(env); // 添加 Unref

  adapter_set_on_scan_stop(this->handle, onScanStop, this);
  return env.Undefined(); // 确保返回 Napi::Value
}

void AdapterWrapper::onScanStart(adapter_t handle, void *userdata) {
  auto adapter = reinterpret_cast(userdata);
  auto callback = [](Napi::Env env, Napi::Function jsCallback) {
    jsCallback.Call({});
  };
  // 修正：通过 adapter 实例访问 onScanStartFn
  adapter->onScanStartFn.BlockingCall(callback);
}

void AdapterWrapper::onScanStop(adapter_t handle, void *userdata) {
  auto adapter = reinterpret_cast(userdata);
  auto callback = [](Napi::Env env, Napi::Function jsCallback) {
    jsCallback.Call({});
  };
  adapter->onScanStopFn.BlockingCall(callback);
}

在上述修改后的代码中：

1. 在 SetOnScanStart 和 SetOnScanStop 方法的开始处添加了 Napi::HandleScope scope(env);。这确保了在这些方法中创建的任何 N-API 句柄（例如 info[0].As<:function>() 产生的临时句柄）在方法结束时得到正确清理。
2. 在创建 Napi::ThreadSafeFunction 实例后，紧接着调用了 this->onScanStartFn.Unref(env); 和 this->onScanStopFn.Unref(env);。这会将 ThreadSafeFunction 的引用类型更改为弱引用，允许 Node.js 进程在没有其他强引用时正常退出。
3. 修正了 onScanStart 方法中对 onScanStartFn 的访问，现在通过 adapter->onScanStartFn 正确访问了 AdapterWrapper 实例的成员。
4. 补充了 SetOnScanStart 和 SetOnScanStop 方法的 return env.Undefined();，因为 N-API 的实例方法通常需要返回一个 Napi::Value。

注意事项与最佳实践

• 何时使用 Unref() 和 Ref()：
  • 如果 ThreadSafeFunction 对应的异步操作是后台任务，不应阻止 Node.js 进程退出，则在创建后立即调用 Unref()。
  • 如果 ThreadSafeFunction 对应的操作是应用程序核心功能，且其活跃状态应阻止进程退出（例如，一个长期运行的服务器），则可以保留其默认的强引用。
  • 如果需要暂时阻止进程退出，可以调用 Ref() 将其重新设为强引用；当不再需要时，再次调用 Unref()。
• 资源释放： 在 ObjectWrap 类的析构函数中，务必调用 ThreadSafeFunction::Release() 来释放底层资源，即使已经 Unref()。这可以确保所有与 ThreadSafeFunction 关联的 JavaScript 引用和 C++ 资源都被正确清理。
• HandleScope 的重要性： 养成在任何可能创建 N-API 值的 C++ 函数中（尤其是回调函数和实例方法）使用 Napi::HandleScope 的习惯，以避免内存泄漏。
• 错误处理： 在实际应用中，ThreadSafeFunction 的 Call() 或 BlockingCall() 方法应该包含适当的错误处理，以应对 JavaScript 回调执行失败的情况。

总结

通过在 Napi::ThreadSafeFunction 创建后及时调用 Unref() 方法，开发者可以精确控制其对 Node.js 事件循环生命周期的影响，避免不必要的进程阻塞。结合 Napi::HandleScope 的正确使用，可以确保 N-API 模块在提供高性能 C++ 功能的同时，也保持了良好的资源管理和与 Node.js 运行时环境的和谐交互。遵循这些实践，将有助于构建健壮且高效的 N-API 模块。