From 884afd8efb8672df2889df98b5b94f3dbb53952c Mon Sep 17 00:00:00 2001
From: Steve Vinoski <vinoski@ieee.org>
Date: Mon, 27 Apr 2015 23:39:37 -0400
Subject: Enhance enif_has_pending_exception

Sverker Eriksson came up with the following idea: to handle a future
ability for NIFs to raise more than just badarg exceptions, modify the
recently-added enif_has_pending_exception function to take a second
argument: a pointer to ERL_NIF_TERM. If this argument is a null
pointer, ignore it. Otherwise, if the first argument, an ErlNifEnv*,
has an associated exception, set the pointed-to ERL_NIF_TERM of the
second argument to the value of the exception term. Add new tests and
documentation for this modification.
---
 erts/doc/src/erl_nif.xml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

(limited to 'erts/doc/src/erl_nif.xml')

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 4bad8b253c..155aee2f42 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -778,11 +778,17 @@ typedef enum {
       and return true, or return false if <c>term</c> is not an unsigned integer or is
       outside the bounds of type <c>unsigned long</c>.</p></desc>
     </func>
-    <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env)</nametext></name>
+    <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason)</nametext></name>
       <fsummary>Check if an exception has been raised.</fsummary>
       <desc><p>Return true if a pending exception is associated
-      with the environment <c>env</c>. The only possible exception is currently
-      <c>badarg</c> (see <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>).</p></desc>
+      with the environment <c>env</c>. If <c>reason</c> is a null pointer, ignore it.
+      Otherwise, if there's a pending exception associated with <c>env</c>, set the ERL_NIF_TERM
+      to which <c>reason</c> points to the value of the exception's term. For example, if
+      <seealso marker="#enif_make_badarg">enif_make_badarg</seealso> is called to set a
+      pending <c>badarg</c> exception, a subsequent call to <c>enif_has_pending_exception(env, &amp;reason)</c>
+      will set <c>reason</c> to the atom <c>badarg</c>, then return true.</p>
+      <p>See also: <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.</p>
+      </desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name>
       <fsummary>Inspect the content of a binary</fsummary>
-- 
cgit v1.2.3


From 17735c9f3879145f43a3e4be0369b7117b1b7b84 Mon Sep 17 00:00:00 2001
From: Steve Vinoski <vinoski@ieee.org>
Date: Wed, 6 May 2015 23:15:04 -0400
Subject: Add enif_raise_exception

Add enif_raise_exception function to allow NIFs to raise error
exceptions holding any Erlang terms. This does not replace or
deprecate the enif_make_badarg function, though, because raising
badarg errors is so idiomatic in NIFs. Reimplement enif_make_badarg on
top of enif_raise_exception. Add new tests for enif_raise_exception
for both normal and dirty NIFs. Add documentation for
enif_raise_exception.
---
 erts/doc/src/erl_nif.xml | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

(limited to 'erts/doc/src/erl_nif.xml')

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 155aee2f42..104d90c937 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -787,7 +787,8 @@ typedef enum {
       <seealso marker="#enif_make_badarg">enif_make_badarg</seealso> is called to set a
       pending <c>badarg</c> exception, a subsequent call to <c>enif_has_pending_exception(env, &amp;reason)</c>
       will set <c>reason</c> to the atom <c>badarg</c>, then return true.</p>
-      <p>See also: <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.</p>
+      <p>See also: <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>
+      and <seealso marker="#enif_raise_exception">enif_raise_exception</seealso>.</p>
       </desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name>
@@ -902,12 +903,13 @@ typedef enum {
       it calls invokes <c>enif_make_badarg</c>, the runtime ensures that a
       <c>badarg</c> exception is raised when the NIF returns, even if the NIF
       attempts to return a non-exception term instead.
-      The return value from <c>enif_make_badarg</c> may only be used as
-      return value from the NIF that invoked it (direct or indirectly)
+      The return value from <c>enif_make_badarg</c> may be used only as the
+      return value from the NIF that invoked it (directly or indirectly)
       or be passed to
       <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but
       not to any other NIF API function.</p>
-      <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso>.
+      <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso>
+      and <seealso marker="#enif_raise_exception">enif_raise_exception</seealso>
       </p>
       <note><p>In earlier versions (older than erts-7.0, OTP 18) the return value
       from <c>enif_make_badarg</c> had to be returned from the NIF. This
@@ -1174,6 +1176,19 @@ typedef enum {
       <c>reload</c> or <c>upgrade</c>.</p>
       <p>Was previously named <c>enif_get_data</c>.</p></desc>
     </func>
+    <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_raise_exception(ErlNifEnv* env, ERL_NIF_TERM reason)</nametext></name>
+      <fsummary>Raise a NIF error exception</fsummary>
+      <desc><p>Create an error exception with the term <c>reason</c> to be returned from a NIF,
+      and associate it with the environment <c>env</c>. Once a NIF or any function it calls
+      invokes <c>enif_raise_exception</c>, the runtime ensures that the exception it creates
+      is raised when the NIF returns, even if the NIF attempts to return a non-exception
+      term instead. The return value from <c>enif_raise_exception</c> may be used only as
+      the return value from the NIF that invoked it (directly or indirectly) or be passed
+      to <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but
+      not to any other NIF API function.</p>
+      <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso>
+      and <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.</p></desc>
+    </func>
     <func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name>
       <fsummary>Change the size of a binary.</fsummary>
       <desc><p>Change the size of a binary <c>bin</c>. The source binary
-- 
cgit v1.2.3