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, 18 insertions, 0 deletions

diff --git a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
index 8489124966..dc047394b5 100644
--- a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
+++ b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
@@ -802,6 +802,23 @@ static ERL_NIF_TERM check_is(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]
 }
 
 /*
+ * no arguments
+ *
+ * This function is separate from check_is because it calls enif_make_badarg
+ * and so it must return the badarg exception as its return value. Thus, the
+ * badarg exception indicates success. Failure is indicated by returning an
+ * error atom.
+ */
+static ERL_NIF_TERM check_is_exception(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
+{
+    ERL_NIF_TERM error_atom = enif_make_atom(env, "error");
+    ERL_NIF_TERM badarg = enif_make_badarg(env);
+    if (enif_is_exception(env, error_atom)) return error_atom;
+    if (!enif_is_exception(env, badarg)) return error_atom;
+    return badarg;
+}
+
+/*
  * argv[0] atom with length of 6
  * argv[1] list with length of 6
  * argv[2] empty list
@@ -1383,6 +1400,7 @@ static ErlNifFunc nif_funcs[] =
     {"last_resource_dtor_call", 0, last_resource_dtor_call},
     {"make_new_resource", 2, make_new_resource},
     {"check_is", 10, check_is},
+    {"check_is_exception", 0, check_is_exception},
     {"length_test", 5, length_test},
     {"make_atoms", 0, make_atoms},
     {"make_strings", 0, make_strings},