From 8bc16512498bf54516a2bd943254343cc5b95e60 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 1a02711f8e106e..bcda526f875f0c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -527,6 +527,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