对生命周期比原生方法长的对象的引用

¥References to objects with a lifespan longer than that of the native method

在某些情况下，插件需要能够创建和引用生命周期比单个本地方法调用更长的对象。例如，要创建构造函数并稍后在创建实例的请求中使用该构造函数，必须可以在许多不同的实例创建请求中引用构造函数对象。这对于如前一节所述作为 napi_value 返回的普通句柄是不可能的。普通句柄的生命周期由作用域管理，所有作用域都必须在本地方法结束之前关闭。

¥In some cases an addon will need to be able to create and reference objects with a lifespan longer than that of a single native method invocation. For example, to create a constructor and later use that constructor in a request to creates instances, it must be possible to reference the constructor object across many different instance creation requests. This would not be possible with a normal handle returned as a napi_value as described in the earlier section. The lifespan of a normal handle is managed by scopes and all scopes must be closed before the end of a native method.

Node-API 提供了创建对象持久引用的方法。每个持久引用都有一个关联的计数，其值为 0 或更高。该计数确定引用是否会使相应的对象保持活动状态。计数为 0 的引用不会阻止对象被收集，通常称为 'weak' 引用。任何大于 0 的计数都将阻止收集对象。

¥Node-API provides methods to create persistent references to an object. Each persistent reference has an associated count with a value of 0 or higher. The count determines if the reference will keep the corresponding object live. References with a count of 0 do not prevent the object from being collected and are often called 'weak' references. Any count greater than 0 will prevent the object from being collected.

可以使用初始引用计数创建引用。然后可以通过 napi_reference_ref 和 napi_reference_unref 修改计数。如果在引用计数为 0 时收集对象，则所有后续调用以获取与引用 napi_get_reference_value 关联的对象将为返回的 napi_value 返回 NULL。尝试为其对象已收集的引用调用 napi_reference_ref 会导致错误。

¥References can be created with an initial reference count. The count can then be modified through napi_reference_ref and napi_reference_unref. If an object is collected while the count for a reference is 0, all subsequent calls to get the object associated with the reference napi_get_reference_value will return NULL for the returned napi_value. An attempt to call napi_reference_ref for a reference whose object has been collected results in an error.

一旦插件不再需要引用，就必须删除它们。删除引用后，将不再阻止收集相应的对象。未能删除持久引用会导致 '内存泄漏' 永久保留用于持久引用的原生内存和堆上的相应对象。

¥References must be deleted once they are no longer required by the addon. When a reference is deleted, it will no longer prevent the corresponding object from being collected. Failure to delete a persistent reference results in a 'memory leak' with both the native memory for the persistent reference and the corresponding object on the heap being retained forever.

可以创建多个指向同一个对象的持久引用，每个持久引用将根据其各自的计数使对象保持活动状态。对同一对象的多个持久引用可能会导致原生内存意外保持活动状态。持久引用的原生结构必须保持活动状态，直到执行引用对象的终结器。如果为同一对象创建新的持久引用，则不会运行该对象的终结器，并且不会释放先前持久引用指向的原生内存。这可以通过在可能的情况下除了 napi_reference_unref 之外还调用 napi_delete_reference 来避免。

¥There can be multiple persistent references created which refer to the same object, each of which will either keep the object live or not based on its individual count. Multiple persistent references to the same object can result in unexpectedly keeping alive native memory. The native structures for a persistent reference must be kept alive until finalizers for the referenced object are executed. If a new persistent reference is created for the same object, the finalizers for that object will not be run and the native memory pointed by the earlier persistent reference will not be freed. This can be avoided by calling napi_delete_reference in addition to napi_reference_unref when possible.