code: Add functions that can load multiple modules

Add functions to 'code' to allow loading of multiple modules
at once.

code:atomic_load(Modules) will load all modules at once, or fail
having loaded none of them. Since we cannot guarantee the atomicity if
there are modules with -on_load functions, the list of modules must
not contain any modules with an -on_load function.

Also, to make it possible to put an application into an inactive state
for as short time as possible, also add code:prepare_loading/1 and
code:finish_loading/1. They are used like this:

  {ok,Prepared} = code:prepare_loading(Modules)
    .
    .
    .
  ok = code:finish_loading(Prepared)

code:ensure_modules_loaded/1 is useful as a pure optimization to
ensure that modules that will be needed soon have indeed been
loaded. It will not reload modules that have already been loaded and
it *will* accept modules that have an on_load function. Therefore, it
does not make sense to give any atomicity guarantees.

I did consider overloading the existing code:ensure_loaded/1
function, but rejected it because the return value is very
different. Having different forms of return values depending
on the types of arguments is confusing.

1 files changed, 136 insertions, 0 deletions

diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
index d4c9a48901..819da544c3 100644
--- a/lib/kernel/doc/src/code.xml
+++ b/lib/kernel/doc/src/code.xml
@@ -310,6 +310,10 @@
     <datatype>
       <name name="load_error_rsn"/>
     </datatype>
+    <datatype>
+      <name name="prepared_code"/>
+      <desc>An opaque term holding prepared code.</desc>
+    </datatype>
   </datatypes>
 
   <funcs>
@@ -479,6 +483,138 @@
       </desc>
     </func>
     <func>
+      <name name="atomic_load" arity="1"/>
+      <fsummary>Load a list of modules atomically</fsummary>
+      <desc>
+        <p>Tries to load all of the modules in the list
+        <c><anno>Modules</anno></c> atomically.  That means that
+        either all modules are loaded at the same time, or
+        none of the modules are loaded if there is a problem with any
+	of the modules.</p>
+	<p>Loading can fail for one the following reasons:</p>
+	<taglist>
+	  <tag><c>badfile</c></tag>
+	  <item>
+	    <p>The object code has an incorrect format or the module
+	    name in the object code is not the expected module name.</p>
+	  </item>
+	  <tag><c>nofile</c></tag>
+	  <item>
+	    <p>No file with object code exists.</p>
+	  </item>
+	  <tag><c>on_load_not_allowed</c></tag>
+	  <item>
+	    <p>A module contains an
+	    <seealso marker="doc/reference_manual:code_loading#on_load">-on_load function</seealso>.</p>
+	  </item>
+	  <tag><c>duplicated</c></tag>
+	  <item>
+	    <p>A module is included more than once in
+	    <c><anno>Modules</anno></c>.</p>
+	  </item>
+	  <tag><c>not_purged</c></tag>
+	  <item>
+	    <p>The object code can not be loaded because an old version
+	    of the code already exists.</p>
+	  </item>
+	  <tag><c>sticky_directory</c></tag>
+	  <item>
+	    <p>The object code resides in a sticky directory.</p>
+	  </item>
+	  <tag><c>pending_on_load</c></tag>
+	  <item>
+	    <p>A previously loaded module contains an
+	    <c>-on_load</c> function that never finished.</p>
+	  </item>
+	</taglist>
+	<p>If it is important to minimize the time that an application
+	is inactive while changing code, use
+	<seealso marker="#prepare_loading/1">prepare_loading/1</seealso>
+	and
+	<seealso marker="#finish_loading/1">finish_loading/1</seealso>
+	instead of <c>atomic_load/1</c>. Here is an example:</p>
+<pre>
+{ok,Prepared} = code:prepare_loading(Modules),
+%% Put the application into an inactive state or do any
+%% other preparation needed before changing the code.
+ok = code:finish_loading(Prepared),
+%% Resume the application.</pre>
+      </desc>
+    </func>
+    <func>
+      <name name="prepare_loading" arity="1"/>
+      <fsummary>Prepare a list of modules atomically</fsummary>
+      <desc>
+        <p>Prepares to load the modules in the list
+        <c><anno>Modules</anno></c>.
+	Finish the loading by calling
+	<seealso marker="#finish_loading/1">finish_loading(Prepared)</seealso>.</p>
+	<p>This function can fail with one of the following error reasons:</p>
+	<taglist>
+	  <tag><c>badfile</c></tag>
+	  <item>
+	    <p>The object code has an incorrect format or the module
+	    name in the object code is not the expected module name.</p>
+	  </item>
+	  <tag><c>nofile</c></tag>
+	  <item>
+	    <p>No file with object code exists.</p>
+	  </item>
+	  <tag><c>on_load_not_allowed</c></tag>
+	  <item>
+	    <p>A module contains an
+	    <seealso marker="doc/reference_manual:code_loading#on_load">-on_load function</seealso>.</p>
+	  </item>
+	  <tag><c>duplicated</c></tag>
+	  <item>
+	    <p>A module is included more than once in
+	    <c><anno>Modules</anno></c>.</p>
+	  </item>
+	</taglist>
+      </desc>
+    </func>
+    <func>
+      <name name="finish_loading" arity="1"/>
+      <fsummary>Finish loading a list of prepared modules atomically</fsummary>
+      <desc>
+        <p>Tries to load code for all modules that have been previously
+	prepared by
+	<seealso marker="#prepare_loading/1">prepare_loading/1</seealso>.
+	The loading occurs atomically, meaning that
+        either all modules are loaded at the same time, or
+        none of the modules are loaded.</p>
+	<p>This function can fail with one of the following error reasons:</p>
+	<taglist>
+	  <tag><c>not_purged</c></tag>
+	  <item>
+	    <p>The object code can not be loaded because an old version
+	    of the code already exists.</p>
+	  </item>
+	  <tag><c>sticky_directory</c></tag>
+	  <item>
+	    <p>The object code resides in a sticky directory.</p>
+	  </item>
+	  <tag><c>pending_on_load</c></tag>
+	  <item>
+	    <p>A previously loaded module contains an
+	    <c>-on_load</c> function that never finished.</p>
+	  </item>
+	</taglist>
+      </desc>
+    </func>
+    <func>
+      <name name="ensure_modules_loaded" arity="1"/>
+      <fsummary>Ensure that a list of modules is loaded</fsummary>
+      <desc>
+        <p>Tries to load any modules not already loaded in the list
+	<c><anno>Modules</anno></c> in the same way as
+          <seealso marker="#load_file/1">load_file/1</seealso>.</p>
+	  <p>Returns <c>ok</c> if successful, or
+	  <c>{error,[{Module,Reason}]}</c> if loading of some modules fails.
+	  See <seealso marker="#error_reasons">Error Reasons for Code-Loading Functions</seealso> for a description of other possible error reasons.</p>
+      </desc>
+    </func>
+    <func>
       <name name="delete" arity="1"/>
       <fsummary>Removes current code for a module</fsummary>
       <desc>