diff options
Diffstat (limited to 'system')
| -rw-r--r-- | system/doc/design_principles/code_lock.dia | bin | 2955 -> 2932 bytes | |||
| -rw-r--r-- | system/doc/design_principles/code_lock.png | bin | 58823 -> 59160 bytes | |||
| -rw-r--r-- | system/doc/design_principles/code_lock_2.dia | bin | 2646 -> 2621 bytes | |||
| -rw-r--r-- | system/doc/design_principles/code_lock_2.png | bin | 51848 -> 48927 bytes | |||
| -rw-r--r-- | system/doc/design_principles/fsm.xml | 2 | ||||
| -rw-r--r-- | system/doc/reference_manual/code_loading.xml | 55 | ||||
| -rw-r--r-- | system/doc/reference_manual/macros.xml | 48 |
7 files changed, 74 insertions, 31 deletions
diff --git a/system/doc/design_principles/code_lock.dia b/system/doc/design_principles/code_lock.dia Binary files differindex bed6d8ee86..8e6ff8a898 100644 --- a/system/doc/design_principles/code_lock.dia +++ b/system/doc/design_principles/code_lock.dia diff --git a/system/doc/design_principles/code_lock.png b/system/doc/design_principles/code_lock.png Binary files differindex e40f0320aa..745fd91920 100644 --- a/system/doc/design_principles/code_lock.png +++ b/system/doc/design_principles/code_lock.png diff --git a/system/doc/design_principles/code_lock_2.dia b/system/doc/design_principles/code_lock_2.dia Binary files differindex 4e82a9e1d6..142909a2f5 100644 --- a/system/doc/design_principles/code_lock_2.dia +++ b/system/doc/design_principles/code_lock_2.dia diff --git a/system/doc/design_principles/code_lock_2.png b/system/doc/design_principles/code_lock_2.png Binary files differindex 138fbdef6c..ecf7b0d799 100644 --- a/system/doc/design_principles/code_lock_2.png +++ b/system/doc/design_principles/code_lock_2.png diff --git a/system/doc/design_principles/fsm.xml b/system/doc/design_principles/fsm.xml index 3468f93ae0..4f2b75e6e8 100644 --- a/system/doc/design_principles/fsm.xml +++ b/system/doc/design_principles/fsm.xml @@ -33,7 +33,7 @@ <note> <p> There is a new behaviour - <seealso marker="gen_statem"><c>gen_statem</c></seealso> + <seealso marker="statem"><c>gen_statem</c></seealso> that is intended to replace <c>gen_fsm</c> for new code. It has the same features and add some really useful. This module will not be removed for the foreseeable future 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> diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml index 42ea639b54..350bb1d123 100644 --- a/system/doc/reference_manual/macros.xml +++ b/system/doc/reference_manual/macros.xml @@ -234,6 +234,53 @@ or </section> <section> + <title>-error() and -warning() directives</title> + + <p>The directive <c>-error(Term)</c> causes a compilation error.</p> + + <p><em>Example:</em></p> + <code type="none"> +-module(t). +-export([version/0]). + +-ifdef(VERSION). +version() -> ?VERSION. +-else. +-error("Macro VERSION must be defined."). +version() -> "". +-endif.</code> + + <p>The error message will look like this:</p> + + <pre> +% <input>erlc t.erl</input> +t.erl:7: -error("Macro VERSION must be defined.").</pre> + + <p>The directive <c>-warning(Term)</c> causes a compilation warning.</p> + + <p><em>Example:</em></p> + <code type="none"> +-module(t). +-export([version/0]). + +-ifndef(VERSION). +-warning("Macro VERSION not defined -- using default version."). +-define(VERSION, "0"). +-endif. +version() -> ?VERSION.</code> + + <p>The warning message will look like this:</p> + + <pre> +% <input>erlc t.erl</input> +t.erl:5: Warning: -warning("Macro VERSION not defined -- using default version.").</pre> + + <p>The <c>-error()</c> and <c>-warning()</c> directives were added + in OTP 19.</p> + + </section> + + <section> <title>Stringifying Macro Arguments</title> <p>The construction <c>??Arg</c>, where <c>Arg</c> is a macro argument, is expanded to a string containing the tokens of @@ -253,5 +300,6 @@ io:format("Call ~s: ~w~n",["you : function ( 2 , 1 )",you:function(2,1)]).</code <p>That is, a trace output, with both the function called and the resulting value.</p> </section> + </chapter> |
