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

diff --git a/erts/emulator/beam/erl_nif.c b/erts/emulator/beam/erl_nif.c
index 135c6b0ccc..8b48444904 100644
--- a/erts/emulator/beam/erl_nif.c
+++ b/erts/emulator/beam/erl_nif.c
@@ -430,6 +430,11 @@ int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
     return is_list(term) || is_nil(term);
 }
 
+int enif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term)
+{
+    return term == THE_NON_VALUE;
+}
+
 static void aligned_binary_dtor(struct enif_tmp_obj_t* obj)
 {
     erts_free_aligned_binary_bytes_extra((byte*)obj,ERTS_ALC_T_TMP);