aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-02-26 13:09:07 +0100
committerBjörn Gustavsson <[email protected]>2016-02-26 13:09:07 +0100
commit6336e0dda8d668c24412775fb45aa8ad19ac384f (patch)
tree2e063c4bd6fdea8a5f3e76738bc96ce6ac8fdaf4 /lib/kernel/doc
parente76103a4549bc25937af5cdccbe43c1683613d07 (diff)
parent1703b979ffcbfbe44c9014f28384305fea930511 (diff)
downloadotp-6336e0dda8d668c24412775fb45aa8ad19ac384f.tar.gz
otp-6336e0dda8d668c24412775fb45aa8ad19ac384f.tar.bz2
otp-6336e0dda8d668c24412775fb45aa8ad19ac384f.zip
Merge branch 'bjorn/multiple-load/OTP-13111'
* bjorn/multiple-load/OTP-13111: code: Add functions that can load multiple modules Refactor post_beam_load handling Simplify and robustify code_server:all_loaded/1 Update preloaded modules Add erl_prim_loader:get_modules/3 Add has_prepared_code_on_load/1 BIF Allow erlang:finish_loading/1 to load more than one module beam_load.c: Add a function to check for an on_load function
Diffstat (limited to 'lib/kernel/doc')
-rw-r--r--lib/kernel/doc/src/code.xml136
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>