在使用 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 仍然会阻止事件循环退出。
解决方案：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 -> AdapterWrapperpublic: 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);}
在上述修改后的代码中：
在 SetOnScanStart 和 SetOnScanStop 方法的开始处添加了 Napi::HandleScope scope(env);。这确保了在这些方法中创建的任何 N-API 句柄（例如 info[0].As() 产生的临时句柄）在方法结束时得到正确清理。在创建 Napi::ThreadSafeFunction 实例后，紧接着调用了 this->onScanStartFn.Unref(env); 和 this->onScanStopFn.Unref(env);。这会将 ThreadSafeFunction 的引用类型更改为弱引用，允许 Node.js 进程在没有其他强引用时正常退出。修正了 onScanStart 方法中对 onScanStartFn 的访问，现在通过 adapter->onScanStartFn 正确访问了 AdapterWrapper 实例的成员。补充了 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 模块。
以上就是N-API 中 ThreadSafeFunction 阻塞事件循环退出的解决方案的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1522815.html
微信扫一扫 
支付宝扫一扫 
