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, 19 insertions, 2 deletions

diff --git a/erts/emulator/beam/erl_nif_api_funcs.h b/erts/emulator/beam/erl_nif_api_funcs.h
index eca506593d..c991b61abe 100644
--- a/erts/emulator/beam/erl_nif_api_funcs.h
+++ b/erts/emulator/beam/erl_nif_api_funcs.h
@@ -1,7 +1,7 @@
 /*
  * %CopyrightBegin%
  *
- * Copyright Ericsson AB 2009-2010. All Rights Reserved.
+ * Copyright Ericsson AB 2009-2011. All Rights Reserved.
  *
  * The contents of this file are subject to the Erlang Public License,
  * Version 1.1, (the "License"); you may not use this file except in
@@ -21,6 +21,13 @@
 #  error This file should not be included directly
 #endif
 
+/*
+** WARNING: add new ERL_NIF_API_FUNC_DECL entries at the bottom of the list
+** to keep compatibility on Windows!!!
+**
+** And don't forget to increase ERL_NIF_MINOR_VERSION in erl_nif.h
+** when adding functions to the API.
+*/
 #ifdef ERL_NIF_API_FUNC_DECL
 ERL_NIF_API_FUNC_DECL(void*,enif_priv_data,(ErlNifEnv*));
 ERL_NIF_API_FUNC_DECL(void*,enif_alloc,(size_t size));
@@ -128,12 +135,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));
 #endif
+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!!!
 */
 #endif
 
+/*
+** Please keep the ERL_NIF_API_FUNC_MACRO list below in the same order
+** as the ERL_NIF_API_FUNC_DECL list above
+*/
 #ifdef ERL_NIF_API_FUNC_MACRO
 #  define enif_priv_data ERL_NIF_API_FUNC_MACRO(enif_priv_data)
 #  define enif_alloc ERL_NIF_API_FUNC_MACRO(enif_alloc)
@@ -243,6 +255,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)
 #endif
 
+#  define enif_is_exception ERL_NIF_API_FUNC_MACRO(enif_is_exception)
+
+/*
+** Add new entries here
+*/
 #endif
 
 #ifndef enif_make_list1