From 9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update Erlang Reference Manual Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder. --- system/doc/reference_manual/code_loading.xml | 117 +++++++++++++++------------ 1 file changed, 64 insertions(+), 53 deletions(-) (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 index b5b5704df5..48ec32d6df 100644 --- a/system/doc/reference_manual/code_loading.xml +++ b/system/doc/reference_manual/code_loading.xml @@ -4,7 +4,7 @@
- 20032014 + 20032015 Ericsson AB. All Rights Reserved. @@ -29,35 +29,39 @@ 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 + is system-dependent. This section describes compilation and + code loading in Erlang/OTP with references 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 + 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 .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).

+

The compiler is located in the module compile (see the + compile(3) manual page in + Compiler).

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

+

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

+

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

 % 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 + modules from the shell, see the + erlc(1) 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.

@@ -68,13 +72,17 @@ compile:file(Module, Options)
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 + system. This is handled by the code server, see the + code(3) + manual page in Kernel.

+

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 + embedded. In interactive mode, code is 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.

+ embedded mode, code is loaded at start-up according to a + boot script. This is described in + + System Principles .

@@ -86,16 +94,17 @@ compile:file(Module, Options) 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 +

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.

-

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 +

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

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

+ fully qualified function call.

+

Example:

 -module(m).
 -export([loop/0]).
@@ -109,60 +118,62 @@ loop() ->
             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 syntax - fun Module:FunctionName/Arity should be used.

+ code_switch to it. The process then makes a fully + qualified call to m:loop() and changes to current code. + Notice that m:loop/0 must be exported.

+

For code replacement of funs to work, use the syntax + fun Module:FunctionName/Arity.

- Running a function when a module is loaded + Running a Function When a Module is Loaded -

The on_load 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:

+

The on_load 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:

-

Doing external call in on_load to the module itself +

Doing external call in on_load to the module itself leads to deadlock.

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 on_load to finish. This can be very bad for applications with demands on realtime characteristics.

 -

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 +

At module upgrade, no rollback is done if the + on_load function fails. + The system is left in a bad limbo state without any working and reachable instance of the module.

 -

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.

+

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 on_load function has successfully returned.

 -

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

+

The -on_load() directive names a function that is to + be run automatically when a module is loaded.

+

Its syntax is as follows:

 -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 +

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

+ a warning error report is sent to the error logger.

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 not yet returned, is suspended until the on_load function has returned.

-

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 +

In embedded mode, first all modules are loaded. + Then all on_load functions are called. The system is + terminated unless all of the on_load functions return ok

. -

Example:

+

Example:

 -module(m).
@@ -174,7 +185,7 @@ load_my_nifs() ->
     erlang:load_nif(NifPath, Info).

If the call to erlang:load_nif/2 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.

-- cgit v1.2.3