This chapter should be read in conjunction with app(4)
and
application(3)
.
When we have written code implementing some specific functionality, we might want to make the code into an application, that is a component that can be started and stopped as a unit, and which can be re-used in other systems as well.
To do this, we create an application callback module, where we describe how the application should be started and stopped.
Then, an application specification is needed, which is put in an application resource file. Among other things, we specify which modules the application consists of and the name of the callback module.
If we use systools
, the Erlang/OTP tools for packaging code
(see Releases),
the code for each application is placed in a separate directory
following a pre-defined directory
structure.
How to start and stop the code for the application, i.e. the supervision tree, is described by two callback functions:
start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State} stop(State)
start
is called when starting the application and should
create the supervision tree by starting the top supervisor.
It is expected to return the pid of the top supervisor and an
optional term State
, which defaults to []. This term is
passed as-is to stop
.
StartType
is usually the atom normal
. It has other
values only in the case of a takeover or failover, see
Distributed
Applications. StartArgs
is defined by the key
mod
in the application
resource file file.
stop/1
is called after the application has been
stopped and should do any necessary cleaning up. Note that
the actual stopping of the application, that is the shutdown of
the supervision tree, is handled automatically as described in
Starting and Stopping
Applications.
Example of an application callback module for packaging the supervision tree from the Supervisor chapter:
-module(ch_app). -behaviour(application). -export([start/2, stop/1]). start(_Type, _Args) -> ch_sup:start_link(). stop(_State) -> ok.
A library application, which can not be started or stopped, does not need any application callback module.
To define an application, we create an application
specification which is put in an application
resource file, or in short .app
file:
{application, Application, [Opt1,...,OptN]}.
Application
, an atom, is the name of the application.
The file must be named Application.app
.
Each Opt
is a tuple {Key, Value}
which define a
certain property of the application. All keys are optional.
Default values are used for any omitted keys.
The contents of a minimal .app
file for a library
application libapp
looks like this:
{application, libapp, []}.
The contents of a minimal .app
file ch_app.app
for
a supervision tree application like ch_app
looks like this:
{application, ch_app, [{mod, {ch_app,[]}}]}.
The key mod
defines the callback module and start
argument of the application, in this case ch_app
and
[], respectively. This means that
ch_app:start(normal, [])
will be called when the application should be started and
ch_app:stop([])
will be called when the application has been stopped.
When using systools
, the Erlang/OTP tools for packaging
code (see Releases),
the keys description
, vsn
, modules
,
registered
and applications
should also be
specified:
{application, ch_app, [{description, "Channel allocator"}, {vsn, "1"}, {modules, [ch_app, ch_sup, ch3]}, {registered, [ch3]}, {applications, [kernel, stdlib, sasl]}, {mod, {ch_app,[]}} ]}.
description
vsn
modules
systools
uses this list when generating boot scripts and
tar files. A module must be defined in one and only one
application. Defaults to [].
registered
systools
uses this list to detect name clashes
between applications. Defaults to [].
applications
systools
uses this list to
generate correct boot scripts. Defaults to [], but note that
all applications have dependencies to at least kernel
and stdlib
.
The syntax and contents of of the application resource file
are described in detail in app(4)
.
When packaging code using systools
, the code for each
application is placed in a separate directory
lib/Application-Vsn
, where Vsn
is the version number.
This may be useful to know, even if systools
is not used,
since Erlang/OTP itself is packaged according to the OTP principles
and thus comes with this directory structure. The code server
(see code(3)
) will automatically use code from
the directory with the highest version number, if there are
more than one version of an application present.
The application directory structure can of course be used in the development environment as well. The version number may then be omitted from the name.
The application directory have the following sub-directories:
src
ebin
priv
include
src
ebin
beam
files.
The .app
file is also placed here.
priv
code:priv_dir/1
should be used to access this directory.
include
When an Erlang runtime system is started, a number of processes
are started as part of the Kernel application. One of these
processes is the application controller process,
registered as application_controller
.
All operations on applications are coordinated by the application
controller. It is interfaced through the functions in
the module application
, see application(3)
.
In particular, applications can be loaded, unloaded, started and
stopped.
Before an application can be started, it must be loaded.
The application controller reads and stores the information from
the .app
file.
1> application:load(ch_app). ok 2> application:loaded_applications(). [{kernel,"ERTS CXC 138 10","2.8.1.3"}, {stdlib,"ERTS CXC 138 10","1.11.4.3"}, {ch_app,"Channel allocator","1"}]
An application that has been stopped, or has never been started, can be unloaded. The information about the application is erased from the internal database of the application controller.
3> application:unload(ch_app). ok 4> application:loaded_applications(). [{kernel,"ERTS CXC 138 10","2.8.1.3"}, {stdlib,"ERTS CXC 138 10","1.11.4.3"}]
![]() |
Loading/unloading an application does not load/unload the code used by the application. Code loading is done the usual way. |
An application is started by calling:
5> application:start(ch_app). ok 6> application:which_applications(). [{kernel,"ERTS CXC 138 10","2.8.1.3"}, {stdlib,"ERTS CXC 138 10","1.11.4.3"}, {ch_app,"Channel allocator","1"}]
If the application is not already loaded, the application
controller will first load it using application:load/1
. It
will check the value of the applications
key, to ensure
that all applications that should be started before this
application are running.
The application controller then creates an application
master for the application. The application master is
the group leader of all the processes in the application.
The application master starts the application by calling
the application callback function start/2
in the module,
and with the start argument, defined by the mod
key in
the .app
file.
An application is stopped, but not unloaded, by calling:
7> application:stop(ch_app). ok
The application master stops the application by telling the top
supervisor to shutdown. The top supervisor tells all its child
processes to shutdown etc. and the entire tree is terminated in
reversed start order. The application master then calls
the application callback function stop/1
in the module
defined by the mod
key.
An application can be configured using configuration
parameters. These are a list of {Par, Val}
tuples
specified by a key env
in the .app
file.
{application, ch_app, [{description, "Channel allocator"}, {vsn, "1"}, {modules, [ch_app, ch_sup, ch3]}, {registered, [ch3]}, {applications, [kernel, stdlib, sasl]}, {mod, {ch_app,[]}}, {env, [{file, "/usr/local/log"}]} ]}.
Par
should be an atom, Val
is any term.
The application can retrieve the value of a configuration
parameter by calling application:get_env(App, Par)
or a
number of similar functions, see application(3)
.
Example:
% erl Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0] Eshell V5.2.3.6 (abort with ^G) 1> application:start(ch_app). ok 2> application:get_env(ch_app, file). {ok,"/usr/local/log"}
The values in the .app
file can be overridden by values
in a system configuration file. This is a file which
contains configuration parameters for relevant applications:
[{Application1, [{Par11,Val11},...]}, ..., {ApplicationN, [{ParN1,ValN1},...]}].
The system configuration should be called Name.config
and
Erlang should be started with the command line argument
-config Name
. See config(4)
for more information.
Example: A file test.config
is created with the following
contents:
[{ch_app, [{file, "testlog"}]}].
The value of file
will override the value of file
as defined in the .app
file:
% erl -config test Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0] Eshell V5.2.3.6 (abort with ^G) 1> application:start(ch_app). ok 2> application:get_env(ch_app, file). {ok,"testlog"}
If
release handling
is used, exactly one system configuration file should be used and
that file should be called sys.config
The values in the .app
file, as well as the values in a
system configuration file, can be overridden directly from
the command line:
% erl -ApplName Par1 Val1 ... ParN ValN
Example:
% erl -ch_app file '"testlog"' Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0] Eshell V5.2.3.6 (abort with ^G) 1> application:start(ch_app). ok 2> application:get_env(ch_app, file). {ok,"testlog"}
A start type is defined when starting the application:
application:start(Application, Type)
application:start(Application)
is the same as calling
application:start(Application, temporary)
. The type can
also be permanent
or transient
:
normal
, this is reported but no other applications are
terminated. If a transient application terminates abnormally,
that is with any other reason than normal
, all other
applications and the runtime system are also terminated.
It is always possible to stop an application explicitly by
calling application:stop/1
. Regardless of the mode, no
other applications will be affected.
Note that transient mode is of little practical use, since when
a supervision tree terminates, the reason is set to
shutdown
, not normal
.