File: applications.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (521 lines) | stat: -rw-r--r-- 16,077 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>Applications</TITLE>
  <SCRIPT type="text/javascript" src="../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="7"><!-- Empty --></A>
<H2>7 Applications</H2>
<A NAME="appl"><!-- Empty --></A>
<P>This chapter should be read in conjunction with <CODE>app(4)</CODE> and
<CODE>application(3)</CODE>.<A NAME="7.1"><!-- Empty --></A>
<H3>7.1 Application Concept</H3>

<P>When we have written code implementing some specific
functionality, we might want to make the code into an
<STRONG>application</STRONG>, that is a component that can be started and
stopped as a unit, and which can be re-used in other systems as
well.
<P>To do this, we create an
<A HREF="#callback_module">application callback
        module</A>, where we describe how the application should
be started and stopped.
<P>Then, an <STRONG>application specification</STRONG> is needed, which is
put in an <A HREF="#appl_res_file">application resource
        file</A>. Among other things, we specify which
modules the application consists of and the name of the callback
module.
<P>If we use <CODE>systools</CODE>, the Erlang/OTP tools for packaging code
(see <A HREF="release_structure.html">Releases</A>),
the code for each application is placed in a separate directory
following a pre-defined <A HREF="#app_dir">directory
        structure</A>.<A NAME="callback_module"><!-- Empty --></A><A NAME="7.2"><!-- Empty --></A>
<H3>7.2 Application Callback Module</H3>

<P>How to start and stop the code for the application, i.e.
the supervision tree, is described by two callback functions:
<PRE>
start(StartType, StartArgs) -&#62; {ok, Pid} | {ok, Pid, State}
stop(State)
    
</PRE>

<P><CODE>start</CODE> 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 <CODE>State</CODE>, which defaults to []. This term is
passed as-is to <CODE>stop</CODE>.
<P><CODE>StartType</CODE> is usually the atom <CODE>normal</CODE>. It has other
values only in the case of a takeover or failover, see
<A HREF="distributed_applications.html">Distributed
        Applications</A>. <CODE>StartArgs</CODE> is defined by the key
<CODE>mod</CODE> in the <A HREF="#appl_res_file">application
        resource file</A> file.
<P><CODE>stop/1</CODE> is called <STRONG>after</STRONG> 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
<A HREF="#stopping">Starting and Stopping
        Applications</A>.<A NAME="ch_app"><!-- Empty --></A>
<P>Example of an application callback module for packaging
the supervision tree from
the <A HREF="sup_princ.html#ex">Supervisor</A> chapter:

<PRE>
-module(ch_app).
-behaviour(application).

-export([start/2, stop/1]).

start(_Type, _Args) -&#62;
    ch_sup:start_link().

stop(_State) -&#62;
    ok.
    
</PRE>

<P>A library application, which can not be started or stopped,
does not need any application callback module.<A NAME="appl_res_file"><!-- Empty --></A><A NAME="7.3"><!-- Empty --></A>
<H3>7.3 Application Resource File</H3>

<P>To define an application, we create an <STRONG>application
        specification</STRONG> which is put in an <STRONG>application
        resource file</STRONG>, or in short <CODE>.app</CODE> file:
<PRE>
{application, Application, [Opt1,...,OptN]}.
    
</PRE>

<P><CODE>Application</CODE>, an atom, is the name of the application.
The file must be named <CODE>Application.app</CODE>.
<P>Each <CODE>Opt</CODE> is a tuple <CODE>{Key, Value}</CODE> which define a
certain property of the application. All keys are optional.
Default values are used for any omitted keys.
<P>The contents of a minimal <CODE>.app</CODE> file for a library
application <CODE>libapp</CODE> looks like this:
<PRE>
{application, libapp, []}.
    
</PRE>

<P>The contents of a minimal <CODE>.app</CODE> file <CODE>ch_app.app</CODE> for
a supervision tree application like <CODE>ch_app</CODE> looks like this:

<PRE>
{application, ch_app,
 [{mod, {ch_app,[]}}]}.
    
</PRE>

<P>The key <CODE>mod</CODE> defines the callback module and start
argument of the application, in this case <CODE>ch_app</CODE> and
[], respectively. This means that
<PRE>
ch_app:start(normal, [])
    
</PRE>

<P>will be called when the application should be started and
<PRE>
ch_app:stop([])
    
</PRE>

<P>will be called when the application has been stopped.
<P>When using <CODE>systools</CODE>, the Erlang/OTP tools for packaging
code (see <A HREF="release_structure.html">Releases</A>),
the keys <CODE>description</CODE>, <CODE>vsn</CODE>, <CODE>modules</CODE>,
<CODE>registered</CODE> and <CODE>applications</CODE> should also be
specified:
<PRE>
{application, ch_app,
 [{description, &#34;Channel allocator&#34;},
  {vsn, &#34;1&#34;},
  {modules, [ch_app, ch_sup, ch3]},
  {registered, [ch3]},
  {applications, [kernel, stdlib, sasl]},
  {mod, {ch_app,[]}}
 ]}.
    
</PRE>

<P>
<DL>

<DT>
<CODE>description</CODE>
</DT>

<DD>
A short description, a string. Defaults to &#34;&#34;.
</DD>

<DT>
<CODE>vsn</CODE>
</DT>

<DD>
Version number, a string. Defaults to &#34;&#34;.
</DD>

<DT>
<CODE>modules</CODE>
</DT>

<DD>
All modules <STRONG>introduced</STRONG> by this application.
        <CODE>systools</CODE> uses this list when generating boot scripts and
        tar files. A module must be defined in one and only one
        application. Defaults to [].
</DD>

<DT>
<CODE>registered</CODE>
</DT>

<DD>
All names of registered processes in the application.
        <CODE>systools</CODE> uses this list to detect name clashes
        between applications. Defaults to [].
</DD>

<DT>
<CODE>applications</CODE>
</DT>

<DD>
All applications which must be started before this
        application is started. <CODE>systools</CODE> uses this list to
        generate correct boot scripts. Defaults to [], but note that
        all applications have dependencies to at least <CODE>kernel</CODE>
        and <CODE>stdlib</CODE>.
</DD>

</DL>

<P>The syntax and contents of of the application resource file
are described in detail in <CODE>app(4)</CODE>.<A NAME="app_dir"><!-- Empty --></A><A NAME="7.4"><!-- Empty --></A>
<H3>7.4 Directory Structure</H3>

<P>When packaging code using <CODE>systools</CODE>, the code for each
application is placed in a separate directory
<CODE>lib/Application-Vsn</CODE>, where <CODE>Vsn</CODE> is the version number.

<P>This may be useful to know, even if <CODE>systools</CODE> 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>code(3)</CODE>) will automatically use code from
the directory with the highest version number, if there are
more than one version of an application present.
<P>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.
<P>The application directory have the following sub-directories:
<P>
<UL>

<LI>
<CODE>src</CODE>
</LI>


<LI>
<CODE>ebin</CODE>
</LI>


<LI>
<CODE>priv</CODE>
</LI>


<LI>
<CODE>include</CODE>
</LI>


</UL>

<P>
<DL>

<DT>
<CODE>src</CODE>
</DT>

<DD>
Contains the Erlang source code.
</DD>

<DT>
<CODE>ebin</CODE>
</DT>

<DD>
Contains the Erlang object code, the <CODE>beam</CODE> files.
        The <CODE>.app</CODE> file is also placed here.
</DD>

<DT>
<CODE>priv</CODE>
</DT>

<DD>
Used for application specific files. For example, C
        executables are placed here. The function <CODE>code:priv_dir/1</CODE>
        should be used to access this directory.
</DD>

<DT>
<CODE>include</CODE>
</DT>

<DD>
Used for include files.
</DD>

</DL>
<A NAME="application_controller"><!-- Empty --></A><A NAME="7.5"><!-- Empty --></A>
<H3>7.5 Application Controller</H3>

<P>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 <STRONG>application controller</STRONG> process,
registered as <CODE>application_controller</CODE>.
<P>All operations on applications are coordinated by the application
controller. It is interfaced through the functions in
the module <CODE>application</CODE>, see <CODE>application(3)</CODE>.
In particular, applications can be loaded, unloaded, started and
stopped.<A NAME="7.6"><!-- Empty --></A>
<H3>7.6 Loading and Unloading Applications</H3>

<P>Before an application can be started, it must be <STRONG>loaded</STRONG>.
The application controller reads and stores the information from
the <CODE>.app</CODE> file.
<PRE>
1&#62; <STRONG>application:load(ch_app).</STRONG>
ok
2&#62; <STRONG>application:loaded_applications().</STRONG>
[{kernel,&#34;ERTS  CXC 138 10&#34;,&#34;2.8.1.3&#34;},
 {stdlib,&#34;ERTS  CXC 138 10&#34;,&#34;1.11.4.3&#34;},
 {ch_app,&#34;Channel allocator&#34;,&#34;1&#34;}]
    
</PRE>

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

<PRE>
3&#62; <STRONG>application:unload(ch_app).</STRONG>
ok
4&#62; <STRONG>application:loaded_applications().</STRONG>
[{kernel,&#34;ERTS  CXC 138 10&#34;,&#34;2.8.1.3&#34;},
 {stdlib,&#34;ERTS  CXC 138 10&#34;,&#34;1.11.4.3&#34;}]
    
</PRE>

<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>Loading/unloading an application does not load/unload the code
        used by the application. Code loading is done the usual way.    </TD>
  </TR>
</TABLE>
<A NAME="stopping"><!-- Empty --></A><A NAME="7.7"><!-- Empty --></A>
<H3>7.7 Starting and Stopping Applications</H3>

<P>An application is started by calling:
<PRE>
5&#62; <STRONG>application:start(ch_app).</STRONG>
ok
6&#62; <STRONG>application:which_applications().</STRONG>
[{kernel,&#34;ERTS  CXC 138 10&#34;,&#34;2.8.1.3&#34;},
 {stdlib,&#34;ERTS  CXC 138 10&#34;,&#34;1.11.4.3&#34;},
 {ch_app,&#34;Channel allocator&#34;,&#34;1&#34;}]
    
</PRE>

<P>If the application is not already loaded, the application
controller will first load it using <CODE>application:load/1</CODE>. It
will check the value of the <CODE>applications</CODE> key, to ensure
that all applications that should be started before this
application are running.<A NAME="application_master"><!-- Empty --></A>
<P>The application controller then creates an <STRONG>application
        master</STRONG> 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 <CODE>start/2</CODE> in the module,
and with the start argument, defined by the <CODE>mod</CODE> key in
the <CODE>.app</CODE> file.
<P>An application is stopped, but not unloaded, by calling:
<PRE>
7&#62; <STRONG>application:stop(ch_app).</STRONG>
ok
    
</PRE>

<P>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 <CODE>stop/1</CODE> in the module
defined by the <CODE>mod</CODE> key.<A NAME="7.8"><!-- Empty --></A>
<H3>7.8 Configuring an Application</H3>

<P>An application can be configured using <STRONG>configuration
        parameters</STRONG>. These are a list of <CODE>{Par, Val}</CODE> tuples
specified by a key <CODE>env</CODE> in the <CODE>.app</CODE> file.
<PRE>
{application, ch_app,
 [{description, &#34;Channel allocator&#34;},
  {vsn, &#34;1&#34;},
  {modules, [ch_app, ch_sup, ch3]},
  {registered, [ch3]},
  {applications, [kernel, stdlib, sasl]},
  {mod, {ch_app,[]}},
  {env, [{file, &#34;/usr/local/log&#34;}]}
 ]}.
    
</PRE>

<P><CODE>Par</CODE> should be an atom, <CODE>Val</CODE> is any term.
The application can retrieve the value of a configuration
parameter by calling <CODE>application:get_env(App, Par)</CODE> or a
number of similar functions, see <CODE>application(3)</CODE>.
<P>Example:
<PRE>
% <STRONG>erl</STRONG>
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]

Eshell V5.2.3.6  (abort with ^G)
1&#62; <STRONG>application:start(ch_app).</STRONG>
ok
2&#62; <STRONG>application:get_env(ch_app, file).</STRONG>
{ok,&#34;/usr/local/log&#34;}
    
</PRE>

<P>The values in the <CODE>.app</CODE> file can be overridden by values
in a <STRONG>system configuration file</STRONG>. This is a file which
contains configuration parameters for relevant applications:
<PRE>
[{Application1, [{Par11,Val11},...]},
 ...,
 {ApplicationN, [{ParN1,ValN1},...]}].
    
</PRE>

<P>The system configuration should be called <CODE>Name.config</CODE> and
Erlang should be started with the command line argument
<CODE>-config Name</CODE>. See <CODE>config(4)</CODE> for more information.

<P>Example: A file <CODE>test.config</CODE> is created with the following
contents:
<PRE>
[{ch_app, [{file, &#34;testlog&#34;}]}].
    
</PRE>

<P>The value of <CODE>file</CODE> will override the value of <CODE>file</CODE>
as defined in the <CODE>.app</CODE> file:
<PRE>
% <STRONG>erl -config test</STRONG>
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]

Eshell V5.2.3.6  (abort with ^G)
1&#62; <STRONG>application:start(ch_app).</STRONG>
ok
2&#62; <STRONG>application:get_env(ch_app, file).</STRONG>
{ok,&#34;testlog&#34;}
    
</PRE>

<P>If
<A HREF="release_handling.html#sys">release handling</A>
is used, exactly one system configuration file should be used and
that file should be called <CODE>sys.config</CODE>
<P>The values in the <CODE>.app</CODE> file, as well as the values in a
system configuration file, can be overridden directly from
the command line:
<PRE>
% <STRONG>erl -ApplName Par1 Val1 ... ParN ValN</STRONG>
    
</PRE>

<P>Example:
<PRE>
% <STRONG>erl -ch_app file '&#34;testlog&#34;'</STRONG>
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]

Eshell V5.2.3.6  (abort with ^G)
1&#62; <STRONG>application:start(ch_app).</STRONG>
ok
2&#62; <STRONG>application:get_env(ch_app, file).</STRONG>
{ok,&#34;testlog&#34;}
    
</PRE>
<A NAME="7.9"><!-- Empty --></A>
<H3>7.9 Application Start Types</H3>

<P>A <STRONG>start type</STRONG> is defined when starting the application:

<PRE>
application:start(Application, Type)
    
</PRE>

<P><CODE>application:start(Application)</CODE> is the same as calling
<CODE>application:start(Application, temporary)</CODE>. The type can
also be <CODE>permanent</CODE> or <CODE>transient</CODE>:
<P>
<UL>

<LI>
If a permanent application terminates, all other
        applications and the runtime system are also terminated.
</LI>


<LI>
If a transient application terminates with reason
        <CODE>normal</CODE>, this is reported but no other applications are
        terminated. If a transient application terminates abnormally,
        that is with any other reason than <CODE>normal</CODE>, all other
        applications and the runtime system are also terminated.
</LI>


<LI>
If a temporary application terminates, this is reported but
        no other applications are terminated.
</LI>


</UL>

<P>It is always possible to stop an application explicitly by
calling <CODE>application:stop/1</CODE>. Regardless of the mode, no
other applications will be affected.
<P>Note that transient mode is of little practical use, since when
a supervision tree terminates, the reason is set to
<CODE>shutdown</CODE>, not <CODE>normal</CODE>.<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>