From 1703b979ffcbfbe44c9014f28384305fea930511 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?=
Date: Tue, 12 Jan 2016 15:15:01 +0100
Subject: 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.
---
lib/kernel/doc/src/code.xml | 136 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 136 insertions(+)
(limited to 'lib/kernel/doc/src/code.xml')
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 @@
+
+
+ An opaque term holding prepared code.
+
@@ -478,6 +482,138 @@
See Error Reasons for Code-Loading Functions for a description of the possible error reasons.
+
+
+ Load a list of modules atomically
+
+ Tries to load all of the modules in the list
+ Modules 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.
+ Loading can fail for one the following reasons:
+
+ badfile
+ -
+
The object code has an incorrect format or the module
+ name in the object code is not the expected module name.
+
+ nofile
+ -
+
No file with object code exists.
+
+ on_load_not_allowed
+ -
+
A module contains an
+ -on_load function.
+
+ duplicated
+ -
+
A module is included more than once in
+ Modules.
+
+ not_purged
+ -
+
The object code can not be loaded because an old version
+ of the code already exists.
+
+ sticky_directory
+ -
+
The object code resides in a sticky directory.
+
+ pending_on_load
+ -
+
A previously loaded module contains an
+ -on_load function that never finished.
+
+
+ If it is important to minimize the time that an application
+ is inactive while changing code, use
+ prepare_loading/1
+ and
+ finish_loading/1
+ instead of atomic_load/1. Here is an example:
+
+{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.
+
+
+
+
+ Prepare a list of modules atomically
+
+ Prepares to load the modules in the list
+ Modules.
+ Finish the loading by calling
+ finish_loading(Prepared).
+ This function can fail with one of the following error reasons:
+
+ badfile
+ -
+
The object code has an incorrect format or the module
+ name in the object code is not the expected module name.
+
+ nofile
+ -
+
No file with object code exists.
+
+ on_load_not_allowed
+ -
+
A module contains an
+ -on_load function.
+
+ duplicated
+ -
+
A module is included more than once in
+ Modules.
+
+
+
+
+
+
+ Finish loading a list of prepared modules atomically
+
+ Tries to load code for all modules that have been previously
+ prepared by
+ prepare_loading/1.
+ The loading occurs atomically, meaning that
+ either all modules are loaded at the same time, or
+ none of the modules are loaded.
+ This function can fail with one of the following error reasons:
+
+ not_purged
+ -
+
The object code can not be loaded because an old version
+ of the code already exists.
+
+ sticky_directory
+ -
+
The object code resides in a sticky directory.
+
+ pending_on_load
+ -
+
A previously loaded module contains an
+ -on_load function that never finished.
+
+
+
+
+
+
+ Ensure that a list of modules is loaded
+
+ Tries to load any modules not already loaded in the list
+ Modules in the same way as
+ load_file/1.
+ Returns ok if successful, or
+ {error,[{Module,Reason}]} if loading of some modules fails.
+ See Error Reasons for Code-Loading Functions for a description of other possible error reasons.
+
+
Removes current code for a module
--
cgit v1.2.3