node_api_nogc_finalize

用于附加组件提供函数的函数指针类型，当关联的对象已被垃圾回收且外部拥有的数据可以清理时，允许用户接收通知。用户必须提供一个满足以下签名的函数，该函数将在对象被回收时被调用。目前，可以使用 node_api_nogc_finalize 来了解具有外部数据的对象何时被回收。

【Function pointer type for add-on provided functions that allow the user to be notified when externally-owned data is ready to be cleaned up because the object it was associated with has been garbage-collected. The user must provide a function satisfying the following signature which would get called upon the object's collection. Currently, node_api_nogc_finalize can be used for finding out when objects that have external data are collected.】

typedef void (*node_api_nogc_finalize)(node_api_nogc_env env,
                                      void* finalize_data,
                                      void* finalize_hint); 拷贝

除非出于 对象生命周期管理 中讨论的原因，否则在函数体内创建 handle 和/或回调作用域并非必要。

【Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.】

由于这些函数可能在 JavaScript 引擎处于无法执行 JavaScript 代码的状态时被调用，因此只能调用接受 node_api_nogc_env 作为第一个参数的 Node-API。node_api_post_finalizer 可用于调度需要访问 JavaScript 引擎状态的 Node-API 调用，以便在当前垃圾回收周期完成后运行。

【Since these functions may be called while the JavaScript engine is in a state where it cannot execute JavaScript code, only Node-APIs which accept a node_api_nogc_env as their first parameter may be called. node_api_post_finalizer can be used to schedule Node-API calls that require access to the JavaScript engine's state to run after the current garbage collection cycle has completed.】

在 node_api_create_external_string_latin1 和 node_api_create_external_string_utf16 的情况下，env 参数可能为 null，因为外部字符串可能会在环境关闭的后期被收集。

【In the case of node_api_create_external_string_latin1 and node_api_create_external_string_utf16 the env parameter may be null, because external strings can be collected during the latter part of environment shutdown.】

变更历史：

【Change History:】

• 实验性（NAPI_EXPERIMENTAL）：

  只有接受 node_api_nogc_env 作为第一个参数的 Node-API 调用可以执行，否则应用将以相应的错误信息终止。通过定义 NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT 可以关闭此功能。