From 7ff117e24a97ce98ac13671ea140c45a67400b5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Fri, 21 May 2010 16:00:21 +0200
Subject: Add erlang:nif_error/1,2

A stub function that is supposed to be replaced by a NIF usually
calls erlang:error/1 to cause an exception if the NIF library
is not loaded. For example:

  foo() ->
      erlang:error(nif_not_loaded).

The problem is that although erlang:error/1 will normally never be
called, Dialyzer will think that any call to the function will fail
and thus generate false warnings. Adding a spec for the function
will not help because Dialyzer will not believe the spec.

Add erlang:nif_error/1,2 that work exactly like erlang:error/1,2.

Define the return types for both BIFs to be t_any().

erlang:nif_error is used like this:

  -spec foo() -> binary().

  foo() ->
      erlang:nif_error(nif_not_loaded).

(The -spec is optional but highly recommended, since Dialyzer
otherwise has no chance to figure out the types.)
---
 erts/doc/src/erlang.xml | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

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

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index e683f161f1..7ff52c5b50 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2643,6 +2643,37 @@ os_prompt%</pre>
           option list is malformed.</p>
       </desc>
     </func>
+    <func>
+      <name>erlang:nif_error(Reason)</name>
+      <fsummary>Stop execution with a given reason</fsummary>
+      <type>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Works exactly like
+	 <seealso marker="#error/1">erlang:error/1</seealso>,
+	 but Dialyzer thinks that this BIF will return an arbitrary term.
+	 When used in a stub function for a NIF to generate an
+	 exception when the NIF library is not loaded, Dialyzer
+	 will not generate false warnings.</p>
+      </desc>
+    </func>
+    <func>
+      <name>erlang:nif_error(Reason, Args)</name>
+      <fsummary>Stop execution with a given reason</fsummary>
+      <type>
+        <v>Reason = term()</v>
+        <v>Args = [term()]</v>
+      </type>
+      <desc>
+        <p>Works exactly like
+	 <seealso marker="#error/2">erlang:error/2</seealso>,
+	 but Dialyzer thinks that this BIF will return an arbitrary term.
+	 When used in a stub function for a NIF to generate an
+	 exception when the NIF library is not loaded, Dialyzer
+	 will not generate false warnings.</p>
+      </desc>
+    </func>
     <func>
       <name>node() -> Node</name>
       <fsummary>Name of the local node</fsummary>
-- 
cgit v1.2.3