Merge branch 'bg/on_load' into ccase/r13b04_dev

* bg/on_load:
  Test on_load functions that don't return 'ok'
  Change the expected return value for on_load functions

OTP-8339  The expected return value for an on_load function has been
          changed. (See the section about code loading in the Reference
          manual.)

1 files changed, 23 insertions, 11 deletions

diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml
index 0e148298b1..f56e1ff408 100644
--- a/system/doc/reference_manual/code_loading.xml
+++ b/system/doc/reference_manual/code_loading.xml
@@ -121,8 +121,10 @@ loop() ->
     <title>Running a function when a module is loaded</title>
 
     <warning>
-    <p>This section describes an experimental feature introduced in R13B03.
-    There may be backward-incompatible changes in the feature in future releases.</p>
+    <p>This section describes an experimental feature that was
+      introduced in R13B03, and changed in a backwards-incompatible
+      way in R13B04. There may be more backward-incompatible changes
+      in future releases.</p>
     </warning>
 
     <p>The <c>-on_load()</c> directive names a function that should
@@ -133,25 +135,35 @@ loop() ->
 
     <p>It is not necessary to export the function. It will be called in a
     freshly spawned process (which will be terminated as soon as the function
-    returns). The function must return <c>true</c> if the module is to
-    be remained loaded and be callable, or <c>false</c> if the module
-    is to be unloaded. Returning any other value or generating an exception
-    will also cause the module to be unloaded.</p>
+    returns). The function must return <c>ok</c> if the module is to
+    be remained loaded and become callable, or any other value if the module
+    is to be unloaded. Generating an exception will also cause the
+    module to be unloaded. If the return value is not an atom,
+    a warning error report will be sent to the error logger.</p>
 
     <p>A process that calls any function in a module whose <c>on_load</c>
     function has not yet returned will be suspended until the <c>on_load</c>
     function has returned.</p>
 
+    <p>In embedded mode, all modules will be loaded first and then
+      will all on_load functions be called. The system will be
+      terminated unless all of the on_load functions return
+      <c>ok</c></p>.
+
     <p>Example:</p>
 
     <pre>
 -module(m).
--on_load(run_me/0).
+-on_load(load_my_nifs/0).
+
+load_my_nifs() ->
+    NifPath = ...,    %Set up the path to the NIF library.
+    Info = ...,       %Initialize the Info term
+    erlang:load_nif(NifPath, Info).</pre>
 
-run_me() ->
-    %% Do something with side effects here, for instance load a library
-    %% containing native-implemented functions.
-    true.</pre>
+    <p>If the call to <c>erlang:load_nif/2</c> fails, the module
+      will be unloaded and there will be warning report sent to
+      the error loader.</p>
 
   </section>