add support for checking if an ERL_NIF_TERM is an exception

Add the enif_is_exception function to allow callers to determine
whether an ERL_NIF_TERM represents an exception. (Currently the only
supported exception is badarg since only enif_make_badarg exists, but
this will likely be expanded in future releases.) This allows NIF code
to call other NIF functions that return ERL_NIF_TERM and properly
check to see if the returned terms are exceptions. Without the
enif_is_exception function, developers have to create their own means
of checking whether a function creates an exception, such as returning
boolean success/failure indicators or some other special value
indicating that an exception is in effect.

The declaration of enif_is_exception in erl_nif_api_funcs.h respects
the order of declarations required to keep compatibility on Windows.

Add a new test to verify the operation of enif_is_exception.

Modify the erl_nif man page to add a description of enif_is_exception
and also to clarify the requirements of calling the enif_make_badarg
function. If code calls enif_make_badarg, the env passed in gets set
with exception information and so the return value of the calling
function MUST be the badarg term returned from enif_make_badarg. Also
clarify that the result of enif_make_badarg may be passed only to
enif_is_exception and not to any other NIF API functions.

1 files changed, 12 insertions, 1 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 4bbd4e2a54..cdce4ec0b8 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -688,6 +688,10 @@ typedef enum {
       <fsummary>Determine if a term is an empty list</fsummary>
       <desc><p>Return true if <c>term</c> is an empty list.</p></desc>
     </func>
+    <marker id="enif_is_exception"/><func><name><ret>int</ret><nametext>enif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
+      <fsummary>Determine if a term is an exception</fsummary>
+      <desc><p>Return true if <c>term</c> is an exception.</p></desc>
+    </func>
     <func><name><ret>int</ret><nametext>enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
       <fsummary>Determine if a term is a fun</fsummary>
       <desc><p>Return true if <c>term</c> is a fun.</p></desc>
@@ -738,7 +742,14 @@ typedef enum {
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name>
       <fsummary>Make a badarg exception.</fsummary>
-      <desc><p>Make a badarg exception to be returned from a NIF.</p></desc>
+      <desc><p>Make a badarg exception to be returned from a NIF, and set
+      an associated exception reason in <c>env</c>. If
+      <c>enif_make_badarg</c> is called, the term it returns <em>must</em>
+      be returned from the function that called it. No other return value
+      is allowed. Also, the term returned from <c>enif_make_badarg</c> may
+      be passed only to
+      <seealso marker="#enif_is_exception">enif_is_exception</seealso> and
+      not to any other NIF API function.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
       <fsummary>Make a binary term.</fsummary>