diff options
Diffstat (limited to 'system/doc/reference_manual/code_loading.xml')
| -rw-r--r-- | system/doc/reference_manual/code_loading.xml | 158 |
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><flags></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> + |