From dfbd981080abe68f011f6eec3c5e02387a709f11 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 14 Oct 2021 10:28:38 -0400 Subject: [PATCH 1/3] doc: clarify behavior of napi_extended_error_info Fix up example and make it more explicit on how you need to use napi_extended_error_info in order to help people avoid what might be a common mistake that we made in node-addon-api. Refs: https://github.com/nodejs/node-addon-api/issues/1089 Signed-off-by: Michael Dawson --- doc/api/n-api.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 9c1d9b896e694c..0d3f45aa9e1610 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -403,12 +403,13 @@ napi_value create_addon(napi_env env); if (status != napi_ok) { \ const napi_extended_error_info* error_info = NULL; \ napi_get_last_error_info((env), &error_info); \ + const char* err_message = error_info->error_message; \ bool is_pending; \ napi_is_exception_pending((env), &is_pending); \ if (!is_pending) { \ - const char* message = (error_info->error_message == NULL) \ + const char* message = (err_message == NULL) \ ? "empty error message" \ - : error_info->error_message; \ + : err_message; \ napi_throw_error((env), NULL, message); \ return NULL; \ } \ @@ -977,7 +978,9 @@ This API retrieves a `napi_extended_error_info` structure with information about the last error that occurred. The content of the `napi_extended_error_info` returned is only valid up until -a Node-API function is called on the same `env`. +a Node-API function is called on the same `env`. This includes a call to +`napi_is_exception_pending` so it may often be necessary to make a copy +of the information so that it can be used later. Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for From eb189274e4766d62a8eb93f078e83280dc7cf8e1 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 18 Oct 2021 16:10:01 -0400 Subject: [PATCH 2/3] fixup: further clarify usage of extended info --- doc/api/n-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0d3f45aa9e1610..39583513daf3ce 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -980,7 +980,10 @@ about the last error that occurred. The content of the `napi_extended_error_info` returned is only valid up until a Node-API function is called on the same `env`. This includes a call to `napi_is_exception_pending` so it may often be necessary to make a copy -of the information so that it can be used later. +of the information so that it can be used later. Note that the pointer returned +in error_message points to a statically defined string so it is safe to use +that pointer if you have copied it out of the error_message field (which will +be overwritten) before another Node-API function was called. Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for From 6f7499c6bd654f62c16769fa12b4622d32561e87 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 18 Oct 2021 17:40:24 -0400 Subject: [PATCH 3/3] Update doc/api/n-api.md --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 39583513daf3ce..66f04c78ea4c94 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -980,7 +980,7 @@ about the last error that occurred. The content of the `napi_extended_error_info` returned is only valid up until a Node-API function is called on the same `env`. This includes a call to `napi_is_exception_pending` so it may often be necessary to make a copy -of the information so that it can be used later. Note that the pointer returned +of the information so that it can be used later. The pointer returned in error_message points to a statically defined string so it is safe to use that pointer if you have copied it out of the error_message field (which will be overwritten) before another Node-API function was called.