From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- system/doc/reference_manual/code_loading.xml | 158 +++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 system/doc/reference_manual/code_loading.xml (limited to 'system/doc/reference_manual/code_loading.xml') 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 @@ + + + + +
+ + 20032009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Compilation and Code Loading + + + + + code_loading.xml +
+

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.

+ +
+ Compilation +

Erlang programs must be compiled 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 + .beam. The compiler can also generate a binary which can + be loaded directly.

+

The compiler is located in the Kernel module compile, see + compile(3).

+ 
+compile:file(Module)
+compile:file(Module, Options)
+

The Erlang shell understands the command c(Module) which + both compiles and loads Module.

+

There is also a module make which provides a set of + functions similar to the UNIX type Make functions, see + make(3).

+

The compiler can also be accessed from the OS prompt, see + erl(1).

+ 
+% erl -compile Module1...ModuleN
+% erl -make
+

The erlc program provides an even better way to compile + modules from the shell, see erlc(1). It understands a + number of flags that can be used to define macros, add search + paths for include files, and more.

+ 
+% erlc <flags> File1.erl...FileN.erl
+
+ +
+ + Code Loading +

The object code must be loaded into the Erlang runtime + system. This is handled by the code server, see + code(3).

+

The code server loads code according to a code loading strategy + which is either interactive (default) or + embedded. In interactive mode, code are searched for in + a code path and loaded when first referenced. In + embedded mode, code is loaded at start-up according to a boot script. This is described in System Principles.

+
+ +
+ Code Replacement +

Erlang supports change of code in a running system. Code + replacement is done on module level.

+

The code of a module can exist in two variants in a system: + current and old. 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'.

+

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.

+

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'.

+

To change from old code to current code, a process must make a + fully qualified function call. Example:

+ 
+-module(m).
+-export([loop/0]).
+
+loop() ->
+    receive
+        code_switch ->
+            m:loop();
+        Msg ->
+            ...
+            loop()
+    end.
+

To make the process change code, send the message + code_switch to it. The process then will make a fully + qualified call to m:loop() and change to current code. + Note that m:loop/0 must be exported.

+

For code replacement of funs to work, the tuple syntax + {Module,FunctionName} must be used to represent the fun.

+
+ +
+ Running a function when a module is loaded + + +

This section describes an experimental feature introduced in R13B03. + There may be backward-incompatible changes in the feature in future releases.

+ + +

The -on_load() directive names a function that should + be run automatically when a module a loaded. Its syntax is:

+ +
+-on_load(Name/0).
+ +

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 true if the module is to + be remained loaded and be callable, or false if the module + is to be unloaded. Returning any other value or generating an exception + will also cause the module to be unloaded.

+ +

A process that calls any function in a module whose on_load + function has not yet returned will be suspended until the on_load + function has returned.

+ +

Example:

+ + 
+-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.
+ +
+ + + -- cgit v1.2.3