From 1af1642fb7eb6605df1ce060cd43fa45dbf78801 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Tue, 9 Mar 2021 13:06:40 +0100 Subject: [PATCH 1/3] doc: warn about SuppressDestruct() Not sure how this ever made its way into the API, but people should *never* use this. --- napi.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/napi.h b/napi.h index 485176157..3ecf1dfc6 100644 --- a/napi.h +++ b/napi.h @@ -1167,6 +1167,8 @@ namespace Napi { // Call this on a reference that is declared as static data, to prevent its destructor // from running at program shutdown time, which would attempt to reset the reference when // the environment is no longer valid. + // Avoid using this if at all possible. If you do need to use static data, + // MAKE SURE to warn your users that your addon is NOT threadsafe. void SuppressDestruct(); protected: From 46e41d961b10a9ff433a9f2332fe6be843b74a35 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Tue, 9 Mar 2021 13:09:42 +0100 Subject: [PATCH 2/3] fixup --- napi.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/napi.h b/napi.h index 3ecf1dfc6..ab4abc1e3 100644 --- a/napi.h +++ b/napi.h @@ -1164,11 +1164,11 @@ namespace Napi { void Reset(); void Reset(const T& value, uint32_t refcount = 0); - // Call this on a reference that is declared as static data, to prevent its destructor - // from running at program shutdown time, which would attempt to reset the reference when - // the environment is no longer valid. - // Avoid using this if at all possible. If you do need to use static data, - // MAKE SURE to warn your users that your addon is NOT threadsafe. + // Call this on a reference that is declared as static data, to prevent its + // destructor from running at program shutdown time, which would attempt to + // reset the reference when the environment is no longer valid. Avoid using + // this if at all possible. If you do need to use static data, MAKE SURE to + // warn your users that your addon is NOT threadsafe. void SuppressDestruct(); protected: From 69d0d98be47279b38c5f035f6d592158f4af153d Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Tue, 9 Mar 2021 13:10:45 +0100 Subject: [PATCH 3/3] fixup --- doc/reference.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/reference.md b/doc/reference.md index 108c009bb..b1033775f 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -4,7 +4,7 @@ Holds a counted reference to a [`Napi::Value`](value.md) object; initially a wea The referenced `Napi::Value` is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the `Napi::Value`. -`Napi::Reference` objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. +`Napi::Reference` objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. Avoid using this if at all possible. The following classes inherit, either directly or indirectly, from `Napi::Reference`: @@ -109,3 +109,5 @@ void Napi::Reference::SuppressDestruct(); ``` Call this method on a `Napi::Reference` that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. + + Avoid using this if at all possible. If you do need to use static data, **MAKE SURE** to warn your users that your addon is **NOT** threadsafe.