aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/code_loading.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2015-03-12 15:35:13 +0100
committerBjörn Gustavsson <[email protected]>2015-03-12 17:42:20 +0100
commit9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd (patch)
tree270f6981da41809e5085f6aec6c7a8b6675caa85 /system/doc/reference_manual/code_loading.xml
parentb61ee25ee7e922b36bb4ae6d505a5f6cbe5b23e6 (diff)
downloadotp-9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd.tar.gz
otp-9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd.tar.bz2
otp-9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd.zip
Update Erlang Reference Manual
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder.
Diffstat (limited to 'system/doc/reference_manual/code_loading.xml')
-rw-r--r--system/doc/reference_manual/code_loading.xml117
1 files changed, 64 insertions, 53 deletions
diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml
index b5b5704df5..48ec32d6df 100644
--- a/system/doc/reference_manual/code_loading.xml
+++ b/system/doc/reference_manual/code_loading.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2014</year>
+ <year>2003</year><year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -29,35 +29,39 @@
<file>code_loading.xml</file>
</header>
<p>How code is compiled and loaded is not a language issue, but
- is system dependent. This chapter describes compilation and
- code loading in Erlang/OTP with pointers to relevant parts of
+ is system-dependent. This section describes compilation and
+ code loading in Erlang/OTP with references to relevant parts of
the documentation.</p>
<section>
<title>Compilation</title>
<p>Erlang programs must be <em>compiled</em> to object code.
- The compiler can generate a new file which contains the object
- code. The current abstract machine which runs the object code is
+ The compiler can generate a new file that contains the object
+ code. The current abstract machine, which runs the object code, is
called BEAM, therefore the object files get the suffix
<c>.beam</c>. The compiler can also generate a binary which can
be loaded directly.</p>
- <p>The compiler is located in the Kernel module <c>compile</c>, see
- <c>compile(3)</c>.</p>
+ <p>The compiler is located in the module <c>compile</c> (see the
+ <seealso marker="compiler:compile">compile(3)</seealso> manual page in
+ Compiler).</p>
<pre>
compile:file(Module)
compile:file(Module, Options)</pre>
<p>The Erlang shell understands the command <c>c(Module)</c> which
both compiles and loads <c>Module</c>.</p>
- <p>There is also a module <c>make</c> which provides a set of
- functions similar to the UNIX type Make functions, see
- <c>make(3)</c>.</p>
- <p>The compiler can also be accessed from the OS prompt, see
- <c>erl(1)</c>.</p>
+ <p>There is also a module <c>make</c>, which provides a set of
+ functions similar to the UNIX type Make functions, see the
+ <seealso marker="tools:make">make(3)</seealso>
+ manual page in Tools.</p>
+ <p>The compiler can also be accessed from the OS prompt, see the
+ <seealso marker="erts:erl">erl(1)</seealso> manual page in ERTS.</p>
<pre>
% erl -compile <input>Module1</input>...<input>ModuleN</input>
% erl -make</pre>
<p>The <c>erlc</c> program provides an even better way to compile
- modules from the shell, see <c>erlc(1)</c>. It understands a
+ modules from the shell, see the
+ <seealso marker="erts:erlc">erlc(1)</seealso> manual page in ERTS.
+ It understands a
number of flags that can be used to define macros, add search
paths for include files, and more.</p>
<pre>
@@ -68,13 +72,17 @@ compile:file(Module, Options)</pre>
<marker id="loading"></marker>
<title>Code Loading</title>
<p>The object code must be <em>loaded</em> into the Erlang runtime
- system. This is handled by the <em>code server</em>, see
- <c>code(3)</c>.</p>
- <p>The code server loads code according to a code loading strategy
+ system. This is handled by the <em>code server</em>, see the
+ <seealso marker="kernel:code">code(3)</seealso>
+ manual page in Kernel.</p>
+ <p>The code server loads code according to a code loading strategy,
which is either <em>interactive</em> (default) or
- <em>embedded</em>. In interactive mode, code are searched for in
+ <em>embedded</em>. In interactive mode, code is searched for in
a <em>code path</em> and loaded when first referenced. In
- embedded mode, code is loaded at start-up according to a <em>boot script</em>. This is described in <em>System Principles</em>.</p>
+ embedded mode, code is loaded at start-up according to a
+ <em>boot script</em>. This is described in
+ <seealso marker="doc/system_principles:system_principles#code_loading">
+ System Principles </seealso>.</p>
</section>
<section>
@@ -86,16 +94,17 @@ compile:file(Module, Options)</pre>
the system for the first time, the code becomes 'current'. If then
a new instance of the module is loaded, the code of the previous
instance becomes 'old' and the new instance becomes 'current'.</p>
- <p>Both old and current code is valid, and may be evaluated
+ <p>Both old and current code is valid, and can be evaluated
concurrently. Fully qualified function calls always refer to
- current code. Old code may still be evaluated because of processes
+ current code. Old code can still be evaluated because of processes
lingering in the old code.</p>
- <p>If a third instance of the module is loaded, the code server will
- remove (purge) the old code and any processes lingering in it will
- be terminated. Then the third instance becomes 'current' and
+ <p>If a third instance of the module is loaded, the code server
+ removes (purges) the old code and any processes lingering in it is
+ terminated. Then the third instance becomes 'current' and
the previously current code becomes 'old'.</p>
<p>To change from old code to current code, a process must make a
- fully qualified function call. Example:</p>
+ fully qualified function call.</p>
+ <p><em>Example:</em></p>
<pre>
-module(m).
-export([loop/0]).
@@ -109,60 +118,62 @@ loop() ->
loop()
end.</pre>
<p>To make the process change code, send the message
- <c>code_switch</c> to it. The process then will make a fully
- qualified call to <c>m:loop()</c> and change to current code.
- Note that <c>m:loop/0</c> must be exported.</p>
- <p>For code replacement of funs to work, the syntax
- <c>fun Module:FunctionName/Arity</c> should be used.</p>
+ <c>code_switch</c> to it. The process then makes a fully
+ qualified call to <c>m:loop()</c> and changes to current code.
+ Notice that <c>m:loop/0</c> must be exported.</p>
+ <p>For code replacement of funs to work, use the syntax
+ <c>fun Module:FunctionName/Arity</c>.</p>
</section>
<section>
<marker id="on_load"></marker>
- <title>Running a function when a module is loaded</title>
+ <title>Running a Function When a Module is Loaded</title>
<warning>
- <p>The <c>on_load</c> feature should be considered experimental
- as there are a number of known weak points in current semantics
- which therefore might also change in future releases:</p>
+ <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 on_load to the module itself
+ <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 on_load to finish. This can be very bad
+ 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 on_load function fails.
- The system will be left in a bad limbo state without any working
+ <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 could be fixed in future
- releases by changing the behaviour to not make the module reachable until
- after the on_load function has successfully returned.</p>
+ <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 should
- be run automatically when a module a loaded. Its syntax is:</p>
+ <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>
<pre>
-on_load(Name/0).</pre>
- <p>It is not necessary to export the function. It will be called in a
- freshly spawned process (which will be terminated as soon as the function
+ <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
- be remained loaded and become callable, or any other value if the module
- is to be unloaded. Generating an exception will also cause the
+ 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 will be sent to the error logger.</p>
+ 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 will be suspended until the <c>on_load</c>
+ function has not yet returned, is suspended until the <c>on_load</c>
function has returned.</p>
- <p>In embedded mode, all modules will be loaded first and then
- will all on_load functions be called. The system will be
- terminated unless all of the on_load functions return
+ <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>.
- <p>Example:</p>
+ <p><em>Example:</em></p>
<pre>
-module(m).
@@ -174,7 +185,7 @@ load_my_nifs() ->
erlang:load_nif(NifPath, Info).</pre>
<p>If the call to <c>erlang:load_nif/2</c> fails, the module
- will be unloaded and there will be warning report sent to
+ is unloaded and a warning report is sent to
the error loader.</p>
</section>