aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-05-04 15:26:38 +0200
committerBjörn Gustavsson <[email protected]>2016-05-04 15:26:38 +0200
commitaf326dd9bc558eaf317a78f197f114d60290a536 (patch)
treeab773a37cb028cdc29712c212691300bff2586eb /system/doc
parentd9f30be07f6ebb014f6021ac2bd3a99894da4c53 (diff)
parent72fc3ab8b5bd19cbd7c9d0b507d97a942d4177de (diff)
downloadotp-af326dd9bc558eaf317a78f197f114d60290a536.tar.gz
otp-af326dd9bc558eaf317a78f197f114d60290a536.tar.bz2
otp-af326dd9bc558eaf317a78f197f114d60290a536.zip
Merge branch 'bjorn/fix-on_load/OTP-12593'
* bjorn/fix-on_load/OTP-12593: Update documentation regarding improvements Correctly handle multiple load attempts when on_load is pending Avoid deadlock when an on_load function makes an external call to the module itself code_server: Eliminate unnecessary Tag in handle_call/3 Reimplement -on_load() Refactor erts_finish_loading() and insert_new_code() code_SUITE: Make on_load_binary/1 clearer by using merl
Diffstat (limited to 'system/doc')
-rw-r--r--system/doc/reference_manual/code_loading.xml55
1 files 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() ->
<marker id="on_load"></marker>
<title>Running a Function When a Module is Loaded</title>
- <warning>
- <p>The <c>on_load</c> 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:</p>
- <list>
- <item><p>Doing external call in <c>on_load</c> to the module itself
- leads to deadlock.</p></item>
- <item><p>At module upgrade, other processes calling the module
- get suspended waiting for <c>on_load</c> to finish. This can be very bad
- for applications with demands on realtime characteristics.</p></item>
- <item><p>At module upgrade, no rollback is done if the
- <c>on_load</c> function fails.
- The system is left in a bad limbo state without any working
- and reachable instance of the module.</p></item>
- </list>
- <p>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 <c>on_load</c> function has successfully returned.</p>
- </warning>
-
<p>The <c>-on_load()</c> directive names a function that is to
be run automatically when a module is loaded.</p>
<p>Its syntax is as follows:</p>
@@ -159,20 +139,35 @@ loop() ->
<p>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 <c>ok</c> 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.</p>
-
- <p>A process that calls any function in a module whose <c>on_load</c>
- function has not yet returned, is suspended until the <c>on_load</c>
- function has returned.</p>
+ returns).</p>
+
+ <p>The function must return <c>ok</c> if the module is to
+ become the new current code for the module and become
+ callable.</p>
+
+ <p>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.</p>
+
+ <p>If there already is current code for the module, that code will
+ remain current and can be called until the <c>on_load</c> function
+ has returned. If the <c>on_load</c> 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 <c>on_load</c> function has finished will be suspended
+ until the <c>on_load</c> function have finished.</p>
+
+ <note>
+ <p>Before OTP 19, if the <c>on_load</c> 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.</p>
+ </note>
<p>In embedded mode, first all modules are loaded.
Then all <c>on_load</c> functions are called. The system is
terminated unless all of the <c>on_load</c> functions return
- <c>ok</c></p>.
+ <c>ok</c>.</p>
<p><em>Example:</em></p>