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') 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