From 72fc3ab8b5bd19cbd7c9d0b507d97a942d4177de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?=
Date: Wed, 4 May 2016 09:45:24 +0200
Subject: Update documentation regarding improvements
---
system/doc/reference_manual/code_loading.xml | 55 +++++++++++++---------------
1 file changed, 25 insertions(+), 30 deletions(-)
diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml
index e9da40e02f..f6fd2911fa 100644
--- a/system/doc/reference_manual/code_loading.xml
+++ b/system/doc/reference_manual/code_loading.xml
@@ -130,26 +130,6 @@ loop() ->
Running a Function When a Module is Loaded
-
- The on_load feature is to be considered experimental
- as there are a number of known weak points in current semantics,
- which therefore might change in future Erlang/OTP releases:
-
- Doing external call in on_load to the module itself
- leads to deadlock.
- At module upgrade, other processes calling the module
- get suspended waiting for on_load to finish. This can be very bad
- for applications with demands on realtime characteristics.
- At module upgrade, no rollback is done if the
- on_load function fails.
- The system is left in a bad limbo state without any working
- and reachable instance of the module.
-
- The problems with module upgrade described above can be fixed in future
- Erlang/OTP releases by changing the behaviour to not make the module reachable until
- after the on_load function has successfully returned.
-
-
The -on_load() directive names a function that is to
be run automatically when a module is loaded.
Its syntax is as follows:
@@ -159,20 +139,35 @@ loop() ->
It is not necessary to export the function. It is called in a
freshly spawned process (which terminates as soon as the function
- returns). The function must return ok if the module is to
- remain loaded and become callable, or any other value if the module
- is to be unloaded. Generating an exception also causes the
- module to be unloaded. If the return value is not an atom,
- a warning error report is sent to the error logger.
-
- A process that calls any function in a module whose on_load
- function has not yet returned, is suspended until the on_load
- function has returned.
+ returns).
+
+ The function must return ok if the module is to
+ become the new current code for the module and become
+ callable.
+
+ Returning any other value or generating an exception
+ causes the new code to be unloaded. If the return value is not an
+ atom, a warning error report is sent to the error logger.
+
+ If there already is current code for the module, that code will
+ remain current and can be called until the on_load function
+ has returned. If the on_load function fails, the current
+ code (if any) will remain current. If there is no current code for
+ a module, any process that makes an external call to the module
+ before the on_load function has finished will be suspended
+ until the on_load function have finished.
+
+
+ Before OTP 19, if the on_load function failed, any
+ previously current code would become old, essentially leaving
+ the system without any working and reachable instance of the
+ module. That problem has been eliminated in OTP 19.
+
In embedded mode, first all modules are loaded.
Then all on_load functions are called. The system is
terminated unless all of the on_load functions return
- ok
.
+ ok.
Example:
--
cgit v1.2.3