Skip to content

Commit

Permalink
doc: clarify behavior of napi_extended_error_info
Browse files Browse the repository at this point in the history
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: nodejs/node-addon-api#1089

Signed-off-by: Michael Dawson <mdawson@devrus.com>

PR-URL: #40458
Reviewed-By: Gabriel Schulhof <gabrielschulhof@gmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
  • Loading branch information
mhdawson authored and targos committed Oct 23, 2021
1 parent d4b45cc commit 34e244b
Showing 1 changed file with 9 additions and 3 deletions.
12 changes: 9 additions & 3 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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; \
} \
Expand Down Expand Up @@ -1005,7 +1006,12 @@ 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. 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
Expand Down

0 comments on commit 34e244b

Please sign in to comment.