From 79bc97c94c4efe7b88ca2e20a26d3889bcd0f615 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 4 Jan 2019 09:47:27 -0500 Subject: [PATCH 1/6] doc: add clarification for exception behaviour Refs: https://github.com/nodejs/abi-stable-node/issues/356 Document current behaviour where some methods can be called when an exception is pending, while others cannot and explain the behaviour. --- doc/api/n-api.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 1a02711f8e106e..3823fdff11d29f 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -527,6 +527,17 @@ exception is pending and no additional action is required. If the instead of simply returning immediately, [`napi_is_exception_pending`][] must be called in order to determine if an exception is pending or not. +In many cases when an N-API function is called and an exception is +already pending the function will return immediately with a +`napi_status` of `napi_pending_exception`. However, this is not the case +for all functions. N-API allows a subset of the functions to be +called in order to allow for some minimal cleanup to be completed +before returning to JavaScript. For those functions, `napi_status` +will reflect the success/error/exception for that function, irrespective of +whether an exception was pending when the function was called. +In order to avoid confusion it is important to check the +error status after every function call. + When an exception is pending one of two approaches can be employed. The first approach is to do any appropriate cleanup and then return so that From 9b164244158f95abfb8e057eae9409ffa2db854f Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 7 Jan 2019 11:19:30 -0500 Subject: [PATCH 2/6] Update doc/api/n-api.md Co-Authored-By: mhdawson --- 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 3823fdff11d29f..94871aa1da2650 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -535,7 +535,7 @@ called in order to allow for some minimal cleanup to be completed before returning to JavaScript. For those functions, `napi_status` will reflect the success/error/exception for that function, irrespective of whether an exception was pending when the function was called. -In order to avoid confusion it is important to check the +To avoid confusion, check the error status after every function call. When an exception is pending one of two approaches can be employed. From b4783ca7cb6744ed2be29ed8be539fbb59e7a552 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 7 Jan 2019 11:19:59 -0500 Subject: [PATCH 3/6] squash: accept suggestion Co-Authored-By: mhdawson --- 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 94871aa1da2650..f066652e43f63d 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -528,7 +528,7 @@ instead of simply returning immediately, [`napi_is_exception_pending`][] must be called in order to determine if an exception is pending or not. In many cases when an N-API function is called and an exception is -already pending the function will return immediately with a +already pending, the function will return immediately with a `napi_status` of `napi_pending_exception`. However, this is not the case for all functions. N-API allows a subset of the functions to be called in order to allow for some minimal cleanup to be completed From 73fa299ce26994608cc5ba681ee1f56b84aca816 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 7 Jan 2019 11:20:33 -0500 Subject: [PATCH 4/6] squash: accept suggestion Co-Authored-By: mhdawson --- 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 f066652e43f63d..4e0f877926b8f9 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -531,7 +531,7 @@ In many cases when an N-API function is called and an exception is already pending, the function will return immediately with a `napi_status` of `napi_pending_exception`. However, this is not the case for all functions. N-API allows a subset of the functions to be -called in order to allow for some minimal cleanup to be completed +called to allow for some minimal cleanup before returning to JavaScript. For those functions, `napi_status` will reflect the success/error/exception for that function, irrespective of whether an exception was pending when the function was called. From 450ee9c3b618150cb46555bd0088cdaa4bae236c Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 7 Jan 2019 11:25:19 -0500 Subject: [PATCH 5/6] squash: address comments --- doc/api/n-api.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 4e0f877926b8f9..d06b95df56dc16 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -532,11 +532,9 @@ already pending, the function will return immediately with a `napi_status` of `napi_pending_exception`. However, this is not the case for all functions. N-API allows a subset of the functions to be called to allow for some minimal cleanup -before returning to JavaScript. For those functions, `napi_status` -will reflect the success/error/exception for that function, irrespective of -whether an exception was pending when the function was called. -To avoid confusion, check the -error status after every function call. +before returning to JavaScript. In that case, `napi_status` will reflect +the status for the function. It will not reflect previous pending exceptions. +To avoid confusion, check the error status after every function call. When an exception is pending one of two approaches can be employed. From 39b0ca3fec93e7d6e92b098c9d96dda77e984146 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 7 Jan 2019 11:27:17 -0500 Subject: [PATCH 6/6] squash: fixup line formatting after changes. --- doc/api/n-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index d06b95df56dc16..bcda526f875f0c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -531,10 +531,10 @@ In many cases when an N-API function is called and an exception is already pending, the function will return immediately with a `napi_status` of `napi_pending_exception`. However, this is not the case for all functions. N-API allows a subset of the functions to be -called to allow for some minimal cleanup -before returning to JavaScript. In that case, `napi_status` will reflect -the status for the function. It will not reflect previous pending exceptions. -To avoid confusion, check the error status after every function call. +called to allow for some minimal cleanup before returning to JavaScript. +In that case, `napi_status` will reflect the status for the function. It +will not reflect previous pending exceptions. To avoid confusion, check +the error status after every function call. When an exception is pending one of two approaches can be employed.