From 745284f2e3701556ee8aee28ae1dd3bd346f9efb Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 4 Jan 2019 09:47:27 -0500 Subject: [PATCH] doc: add clarification for exception behaviour Document current behaviour where some methods can be called when an exception is pending, while others cannot and explain the behaviour. PR-URL: https://github.com/nodejs/node/pull/25339 Refs: https://github.com/nodejs/abi-stable-node/issues/356 Reviewed-By: Colin Ihrig Reviewed-By: Anna Henningsen Reviewed-By: Luigi Pinca --- doc/api/n-api.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index db277b5cdec5e3..4628d9e4bb9b2b 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -468,6 +468,15 @@ 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 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. The first approach is to do any appropriate cleanup and then return so that