Browse files

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.
  • Loading branch information...
1 parent 7bc8802 commit f8cc2b035a20fa007fcd50c97ee256d9063646f7 @vinoski committed Feb 22, 2011
@@ -683,6 +683,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>
+ <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>
@@ -733,7 +737,14 @@ typedef enum {
<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><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
<fsummary>Make a binary term.</fsummary>
@@ -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)
@@ -21,6 +21,10 @@
# error This file should not be included directly
+** WARNING: add new ERL_NIF_API_FUNC_DECL entries at the bottom of the list
+** to keep compatibility on Windows!!!
ERL_NIF_API_FUNC_DECL(void*,enif_alloc,(size_t size));
@@ -128,12 +132,17 @@ ERL_NIF_API_FUNC_DECL(int,enif_get_uint64,(ErlNifEnv*, ERL_NIF_TERM term, ErlNif
ERL_NIF_API_FUNC_DECL(ERL_NIF_TERM,enif_make_int64,(ErlNifEnv*, ErlNifSInt64));
ERL_NIF_API_FUNC_DECL(ERL_NIF_TERM,enif_make_uint64,(ErlNifEnv*, ErlNifUInt64));
+ERL_NIF_API_FUNC_DECL(int,enif_is_exception,(ErlNifEnv*, ERL_NIF_TERM term));
-** Add last to keep compatibility on Windows!!!
+** Add new entries here to keep compatibility on Windows!!!
+** Please keep the ERL_NIF_API_FUNC_MACRO list below in the same order
+** as the ERL_NIF_API_FUNC_DECL list above
# define enif_priv_data ERL_NIF_API_FUNC_MACRO(enif_priv_data)
# define enif_alloc ERL_NIF_API_FUNC_MACRO(enif_alloc)
@@ -243,6 +252,11 @@ ERL_NIF_API_FUNC_DECL(ERL_NIF_TERM,enif_make_uint64,(ErlNifEnv*, ErlNifUInt64));
# define enif_make_uint64 ERL_NIF_API_FUNC_MACRO(enif_make_uint64)
+# define enif_is_exception ERL_NIF_API_FUNC_MACRO(enif_is_exception)
+** Add new entries here
#ifndef enif_make_list1
@@ -1121,7 +1121,14 @@ is_checks(Config) when is_list(Config) ->
?line ensure_lib_loaded(Config, 1),
?line ok = check_is(hejsan, <<19,98>>, make_ref(), ok, fun() -> ok end,
self(), hd(erlang:ports()), [], [1,9,9,8],
- {hejsan, "hejsan", [$h,"ejs",<<"an">>]}).
+ {hejsan, "hejsan", [$h,"ejs",<<"an">>]}),
+ try
+ ?line error = check_is_exception(),
+ ?line throw(expected_badarg)
+ catch
+ error:badarg ->
+ ?line ok
+ end.
get_length(doc) -> ["Test all enif_get_length functions"];
get_length(Config) when is_list(Config) ->
@@ -1245,6 +1252,7 @@ release_resource(_) -> ?nif_stub.
last_resource_dtor_call() -> ?nif_stub.
make_new_resource(_,_) -> ?nif_stub.
check_is(_,_,_,_,_,_,_,_,_,_) -> ?nif_stub.
+check_is_exception() -> ?nif_stub.
length_test(_,_,_,_,_) -> ?nif_stub.
make_atoms() -> ?nif_stub.
make_strings() -> ?nif_stub.
@@ -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},

0 comments on commit f8cc2b0

Please sign in to comment.