erts: Deprecate the NIF reload mechanism

The reload mechanism is an odd feature that does not harmonize
with how module upgrade is otherwise done. We do not want its presence
to hinder future development of code loading and upgrade.

1 files changed, 19 insertions, 16 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 8daa67aa87..5fc6508aad 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -136,9 +136,7 @@ ok
      then retrieved by calling <seealso marker="#enif_priv_data">enif_priv_data</seealso>.</p>
     <p>There is no way to explicitly unload a NIF library. A library will be
      automatically unloaded when the module code that it belongs to is purged
-     by the code server. A NIF library will also be unloaded if it is replaced
-     by another version of the library by a second call to
-     <c>erlang:load_nif/2</c> from the same module code.</p> 
+     by the code server.</p> 
   </description>
   <section>
   <title>FUNCTIONALITY</title>
@@ -308,21 +306,9 @@ ok
            initialization is needed.</p> 
        </item>
 
-      <tag><marker id="reload"/>int (*reload)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag>
-       <item><p><c>reload</c> is called when the NIF library is loaded
-        and there is already a previously loaded library for this
-        module code.</p>
-        <p>Works the same as <c>load</c>. The only difference is that
-        <c>*priv_data</c> already contains the value set by the
-        previous call to <c>load</c> or <c>reload</c>.</p>
-        <p>The library will fail to load if <c>reload</c> returns
-           anything other than 0 or if <c>reload</c> is NULL.</p> 
-      </item>
-
       <tag><marker id="upgrade"/>int (*upgrade)(ErlNifEnv* env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info)</tag>
        <item><p><c>upgrade</c> is called when the NIF library is loaded
-        and there is no previously loaded library for this module
-        code, BUT there is old code of this module with a loaded NIF library.</p>
+        and there is old code of this module with a loaded NIF library.</p>
         <p>Works the same as <c>load</c>. The only difference is that
         <c>*old_priv_data</c> already contains the value set by the
          last call to <c>load</c> or <c>reload</c> for the old module
@@ -339,6 +325,23 @@ ok
        called for a replaced library as a consequence of <c>reload</c>.</p>
       </item>
 
+      <tag><marker id="reload"/>int (*reload)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag>
+     <note><p>The reload mechanism is <em>deprecated</em>. It was only intended
+     as a development feature. Do not use it as an upgrade method for
+     live production systems. It might be removed in future releases. Be sure
+     to pass <c>reload</c> as <c>NULL</c> to <seealso marker="#ERL_NIF_INIT">ERL_NIF_INIT</seealso>
+     to disable it when not used.</p>
+     </note>
+       <item><p><c>reload</c> is called when the NIF library is loaded
+        and there is already a previously loaded library for this
+        module code.</p>
+        <p>Works the same as <c>load</c>. The only difference is that
+        <c>*priv_data</c> already contains the value set by the
+        previous call to <c>load</c> or <c>reload</c>.</p>
+        <p>The library will fail to load if <c>reload</c> returns
+           anything other than 0 or if <c>reload</c> is NULL.</p> 
+      </item>
+
     </taglist>
   </section>