Merge branch 'vinoski/enif-raise-exception/OTP-12770'

* vinoski/enif-raise-exception/OTP-12770:
  Add enif_raise_exception
  Enhance enif_has_pending_exception
  Fix for enif_schedule_nif and exceptions

Conflicts:
	erts/doc/src/erl_nif.xml

1 files changed, 27 insertions, 6 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index e915c3b693..f64381c99d 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -790,11 +790,18 @@ 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>
+      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>
       <fsummary>Inspect the content of a binary</fsummary>
@@ -912,12 +919,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
@@ -1281,6 +1289,19 @@ enif_map_iterator_destroy(env, &amp;iter);
       <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