The R13B03 release.OTP_R13B03

1 files changed, 158 insertions, 0 deletions

diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml
new file mode 100644
index 0000000000..8861b3bea5
--- /dev/null
+++ b/system/doc/reference_manual/code_loading.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2003</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Compilation and Code Loading</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <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
+    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
+      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>
+    <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>
+    <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
+      number of flags that can be used to define macros, add search
+      paths for include files, and more.</p>
+    <pre>
+% erlc <input>&lt;flags&gt;</input> <input>File1.erl</input>...<input>FileN.erl</input></pre>
+  </section>
+
+  <section>
+    <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
+      which is either <em>interactive</em> (default) or
+      <em>embedded</em>. In interactive mode, code are 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>
+  </section>
+
+  <section>
+    <title>Code Replacement</title>
+    <p>Erlang supports change of code in a running system. Code
+      replacement is done on module level.</p>
+    <p>The code of a module can exist in two variants in a system:
+      <em>current</em> and <em>old</em>. When a module is loaded into
+      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
+      concurrently. Fully qualified function calls always refer to
+      current code. Old code may 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
+      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>
+    <pre>
+-module(m).
+-export([loop/0]).
+
+loop() ->
+    receive
+        code_switch ->
+            m:loop();
+        Msg ->
+            ...
+            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 tuple syntax
+      <c>{Module,FunctionName}</c> must be used to represent the fun.</p>
+  </section>
+
+  <section>
+    <title>Running a function when a module is loaded</title>
+
+    <warning>
+    <p>This section describes an experimental feature introduced in R13B03.
+    There may be backward-incompatible changes in the feature in future releases.</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>
+
+<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
+    returns). The function must return <c>true</c> if the module is to
+    be remained loaded and be callable, or <c>false</c> if the module
+    is to be unloaded. Returning any other value or generating an exception
+    will also cause the module to be unloaded.</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 returned.</p>
+
+    <p>Example:</p>
+
+    <pre>
+-module(m).
+-on_load(run_me/0).
+
+run_me() ->
+    %% Do something with side effects here, for instance load a library
+    %% containing native-implemented functions.
+    true.</pre>
+
+  </section>
+
+</chapter>
+