← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/design_principles/applications.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/design_principles/applications.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1997</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Applications</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>applications.xml</file>
 
30
  </header>
 
31
  <marker id="appl"></marker>
 
32
  <p>This chapter should be read in conjunction with <c>app(4)</c> and
 
33
    <c>application(3)</c>.</p>
 
34
 
 
35
  <section>
 
36
    <title>Application Concept</title>
 
37
    <p>When we have written code implementing some specific
 
38
      functionality, we might want to make the code into an
 
39
      <em>application</em>, that is a component that can be started and
 
40
      stopped as a unit, and which can be re-used in other systems as
 
41
      well.</p>
 
42
    <p>To do this, we create an
 
43
      <seealso marker="#callback_module">application callback module</seealso>, where we describe how the application should
 
44
      be started and stopped.</p>
 
45
    <p>Then, an <em>application specification</em> is needed, which is
 
46
      put in an <seealso marker="#appl_res_file">application resource file</seealso>. Among other things, we specify which
 
47
      modules the application consists of and the name of the callback
 
48
      module.</p>
 
49
    <p>If we use <c>systools</c>, the Erlang/OTP tools for packaging code
 
50
      (see <seealso marker="release_structure">Releases</seealso>),
 
51
      the code for each application is placed in a separate directory
 
52
      following a pre-defined <seealso marker="#app_dir">directory structure</seealso>.</p>
 
53
  </section>
 
54
 
 
55
  <section>
 
56
    <marker id="callback_module"></marker>
 
57
    <title>Application Callback Module</title>
 
58
    <p>How to start and stop the code for the application, i.e.
 
59
      the supervision tree, is described by two callback functions:</p>
 
60
    <code type="none">
 
61
start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State}
 
62
stop(State)</code>
 
63
    <p><c>start</c> is called when starting the application and should
 
64
      create the supervision tree by starting the top supervisor.
 
65
      It is expected to return the pid of the top supervisor and an
 
66
      optional term <c>State</c>, which defaults to []. This term is
 
67
      passed as-is to <c>stop</c>.</p>
 
68
    <p><c>StartType</c> is usually the atom <c>normal</c>. It has other
 
69
      values only in the case of a takeover or failover, see
 
70
      <seealso marker="distributed_applications">Distributed Applications</seealso>. <c>StartArgs</c> is defined by the key
 
71
      <c>mod</c> in the <seealso marker="#appl_res_file">application resource file</seealso> file.</p>
 
72
    <p><c>stop/1</c> is called <em>after</em> the application has been
 
73
      stopped and should do any necessary cleaning up. Note that
 
74
      the actual stopping of the application, that is the shutdown of
 
75
      the supervision tree, is handled automatically as described in
 
76
      <seealso marker="#stopping">Starting and Stopping Applications</seealso>.</p>
 
77
    <marker id="ch_app"></marker>
 
78
    <p>Example of an application callback module for packaging
 
79
      the supervision tree from
 
80
      the <seealso marker="sup_princ#ex">Supervisor</seealso> chapter:</p>
 
81
    <code type="none">
 
82
-module(ch_app).
 
83
-behaviour(application).
 
84
 
 
85
-export([start/2, stop/1]).
 
86
 
 
87
start(_Type, _Args) ->
 
88
    ch_sup:start_link().
 
89
 
 
90
stop(_State) ->
 
91
    ok.</code>
 
92
    <p>A library application, which can not be started or stopped,
 
93
      does not need any application callback module.</p>
 
94
  </section>
 
95
 
 
96
  <section>
 
97
    <marker id="appl_res_file"></marker>
 
98
    <title>Application Resource File</title>
 
99
    <p>To define an application, we create an <em>application specification</em> which is put in an <em>application resource file</em>, or in short <c>.app</c> file:</p>
 
100
    <code type="none">
 
101
{application, Application, [Opt1,...,OptN]}.</code>
 
102
    <p><c>Application</c>, an atom, is the name of the application.
 
103
      The file must be named <c>Application.app</c>.</p>
 
104
    <p>Each <c>Opt</c> is a tuple <c>{Key, Value}</c> which define a
 
105
      certain property of the application. All keys are optional.
 
106
      Default values are used for any omitted keys.</p>
 
107
    <p>The contents of a minimal <c>.app</c> file for a library
 
108
      application <c>libapp</c> looks like this:</p>
 
109
    <code type="none">
 
110
{application, libapp, []}.</code>
 
111
    <p>The contents of a minimal <c>.app</c> file <c>ch_app.app</c> for
 
112
      a supervision tree application like <c>ch_app</c> looks like this:</p>
 
113
    <code type="none">
 
114
{application, ch_app,
 
115
 [{mod, {ch_app,[]}}]}.</code>
 
116
    <p>The key <c>mod</c> defines the callback module and start
 
117
      argument of the application, in this case <c>ch_app</c> and
 
118
      [], respectively. This means that</p>
 
119
    <code type="none">
 
120
ch_app:start(normal, [])</code>
 
121
    <p>will be called when the application should be started and</p>
 
122
    <code type="none">
 
123
ch_app:stop([])</code>
 
124
    <p>will be called when the application has been stopped.</p>
 
125
    <p>When using <c>systools</c>, the Erlang/OTP tools for packaging
 
126
      code (see <seealso marker="release_structure">Releases</seealso>),
 
127
      the keys <c>description</c>, <c>vsn</c>, <c>modules</c>,
 
128
      <c>registered</c> and <c>applications</c> should also be
 
129
      specified:</p>
 
130
    <code type="none">
 
131
{application, ch_app,
 
132
 [{description, "Channel allocator"},
 
133
  {vsn, "1"},
 
134
  {modules, [ch_app, ch_sup, ch3]},
 
135
  {registered, [ch3]},
 
136
  {applications, [kernel, stdlib, sasl]},
 
137
  {mod, {ch_app,[]}}
 
138
 ]}.</code>
 
139
    <taglist>
 
140
      <tag><c>description</c></tag>
 
141
      <item>A short description, a string. Defaults to "".</item>
 
142
      <tag><c>vsn</c></tag>
 
143
      <item>Version number, a string. Defaults to "".</item>
 
144
      <tag><c>modules</c></tag>
 
145
      <item>All modules <em>introduced</em> by this application.
 
146
      <c>systools</c> uses this list when generating boot scripts and
 
147
       tar files. A module must be defined in one and only one
 
148
       application. Defaults to [].</item>
 
149
      <tag><c>registered</c></tag>
 
150
      <item>All names of registered processes in the application.
 
151
      <c>systools</c> uses this list to detect name clashes
 
152
       between applications. Defaults to [].</item>
 
153
      <tag><c>applications</c></tag>
 
154
      <item>All applications which must be started before this
 
155
       application is started. <c>systools</c> uses this list to
 
156
       generate correct boot scripts. Defaults to [], but note that
 
157
       all applications have dependencies to at least <c>kernel</c>
 
158
       and <c>stdlib</c>.</item>
 
159
    </taglist>
 
160
    <p>The syntax and contents of of the application resource file
 
161
      are described in detail in <c>app(4)</c>.</p>
 
162
  </section>
 
163
 
 
164
  <section>
 
165
    <marker id="app_dir"></marker>
 
166
    <title>Directory Structure</title>
 
167
    <p>When packaging code using <c>systools</c>, the code for each
 
168
      application is placed in a separate directory
 
169
      <c>lib/Application-Vsn</c>, where <c>Vsn</c> is the version number.</p>
 
170
    <p>This may be useful to know, even if <c>systools</c> is not used,
 
171
      since Erlang/OTP itself is packaged according to the OTP principles
 
172
      and thus comes with this directory structure. The code server
 
173
      (see <c>code(3)</c>) will automatically use code from
 
174
      the directory with the highest version number, if there are
 
175
      more than one version of an application present.</p>
 
176
    <p>The application directory structure can of course be used in
 
177
      the development environment as well. The version number may then
 
178
      be omitted from the name.</p>
 
179
    <p>The application directory have the following sub-directories:</p>
 
180
    <list type="bulleted">
 
181
      <item><c>src</c></item>
 
182
      <item><c>ebin</c></item>
 
183
      <item><c>priv</c></item>
 
184
      <item><c>include</c></item>
 
185
    </list>
 
186
    <taglist>
 
187
      <tag><c>src</c></tag>
 
188
      <item>Contains the Erlang source code.</item>
 
189
      <tag><c>ebin</c></tag>
 
190
      <item>Contains the Erlang object code, the <c>beam</c> files.
 
191
       The <c>.app</c> file is also placed here.</item>
 
192
      <tag><c>priv</c></tag>
 
193
      <item>Used for application specific files. For example, C
 
194
       executables are placed here. The function <c>code:priv_dir/1</c>
 
195
       should be used to access this directory.</item>
 
196
      <tag><c>include</c></tag>
 
197
      <item>Used for include files.</item>
 
198
    </taglist>
 
199
  </section>
 
200
 
 
201
  <section>
 
202
    <marker id="application_controller"></marker>
 
203
    <title>Application Controller</title>
 
204
    <p>When an Erlang runtime system is started, a number of processes
 
205
      are started as part of the Kernel application. One of these
 
206
      processes is the <em>application controller</em> process,
 
207
      registered as <c>application_controller</c>.</p>
 
208
    <p>All operations on applications are coordinated by the application
 
209
      controller. It is interfaced through the functions in
 
210
      the module <c>application</c>, see <c>application(3)</c>.
 
211
      In particular, applications can be loaded, unloaded, started and
 
212
      stopped.</p>
 
213
  </section>
 
214
 
 
215
  <section>
 
216
    <title>Loading and Unloading Applications</title>
 
217
    <p>Before an application can be started, it must be <em>loaded</em>.
 
218
      The application controller reads and stores the information from
 
219
      the <c>.app</c> file.</p>
 
220
    <pre>
 
221
1> <input>application:load(ch_app).</input>
 
222
ok
 
223
2> <input>application:loaded_applications().</input>
 
224
[{kernel,"ERTS  CXC 138 10","2.8.1.3"},
 
225
 {stdlib,"ERTS  CXC 138 10","1.11.4.3"},
 
226
 {ch_app,"Channel allocator","1"}]</pre>
 
227
    <p>An application that has been stopped, or has never been started,
 
228
      can be unloaded. The information about the application is
 
229
      erased from the internal database of the application controller.</p>
 
230
    <pre>
 
231
3> <input>application:unload(ch_app).</input>
 
232
ok
 
233
4> <input>application:loaded_applications().</input>
 
234
[{kernel,"ERTS  CXC 138 10","2.8.1.3"},
 
235
 {stdlib,"ERTS  CXC 138 10","1.11.4.3"}]</pre>
 
236
    <note>
 
237
      <p>Loading/unloading an application does not load/unload the code
 
238
        used by the application. Code loading is done the usual way.</p>
 
239
    </note>
 
240
  </section>
 
241
 
 
242
  <section>
 
243
    <marker id="stopping"></marker>
 
244
    <title>Starting and Stopping Applications</title>
 
245
    <p>An application is started by calling:</p>
 
246
    <pre>
 
247
5> <input>application:start(ch_app).</input>
 
248
ok
 
249
6> <input>application:which_applications().</input>
 
250
[{kernel,"ERTS  CXC 138 10","2.8.1.3"},
 
251
 {stdlib,"ERTS  CXC 138 10","1.11.4.3"},
 
252
 {ch_app,"Channel allocator","1"}]</pre>
 
253
    <p>If the application is not already loaded, the application
 
254
      controller will first load it using <c>application:load/1</c>. It
 
255
      will check the value of the <c>applications</c> key, to ensure
 
256
      that all applications that should be started before this
 
257
      application are running.</p>
 
258
    <marker id="application_master"></marker>
 
259
    <p>The application controller then creates an <em>application master</em> for the application. The application master is
 
260
      the group leader of all the processes in the application.
 
261
      The application master starts the application by calling
 
262
      the application callback function <c>start/2</c> in the module,
 
263
      and with the start argument, defined by the <c>mod</c> key in
 
264
      the <c>.app</c> file.</p>
 
265
    <p>An application is stopped, but not unloaded, by calling:</p>
 
266
    <pre>
 
267
7> <input>application:stop(ch_app).</input>
 
268
ok</pre>
 
269
    <p>The application master stops the application by telling the top
 
270
      supervisor to shutdown. The top supervisor tells all its child
 
271
      processes to shutdown etc. and the entire tree is terminated in
 
272
      reversed start order. The application master then calls
 
273
      the application callback function <c>stop/1</c> in the module
 
274
      defined by the <c>mod</c> key.</p>
 
275
  </section>
 
276
 
 
277
  <section>
 
278
    <title>Configuring an Application</title>
 
279
    <p>An application can be configured using <em>configuration parameters</em>. These are a list of <c>{Par, Val}</c> tuples
 
280
      specified by a key <c>env</c> in the <c>.app</c> file.</p>
 
281
    <code type="none">
 
282
{application, ch_app,
 
283
 [{description, "Channel allocator"},
 
284
  {vsn, "1"},
 
285
  {modules, [ch_app, ch_sup, ch3]},
 
286
  {registered, [ch3]},
 
287
  {applications, [kernel, stdlib, sasl]},
 
288
  {mod, {ch_app,[]}},
 
289
  {env, [{file, "/usr/local/log"}]}
 
290
 ]}.</code>
 
291
    <p><c>Par</c> should be an atom, <c>Val</c> is any term.
 
292
      The application can retrieve the value of a configuration
 
293
      parameter by calling <c>application:get_env(App, Par)</c> or a
 
294
      number of similar functions, see <c>application(3)</c>.</p>
 
295
    <p>Example:</p>
 
296
    <pre>
 
297
% <input>erl</input>
 
298
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
 
299
 
 
300
Eshell V5.2.3.6  (abort with ^G)
 
301
1> <input>application:start(ch_app).</input>
 
302
ok
 
303
2> <input>application:get_env(ch_app, file).</input>
 
304
{ok,"/usr/local/log"}</pre>
 
305
    <p>The values in the <c>.app</c> file can be overridden by values
 
306
      in a <em>system configuration file</em>. This is a file which
 
307
      contains configuration parameters for relevant applications:</p>
 
308
    <code type="none">
 
309
[{Application1, [{Par11,Val11},...]},
 
310
 ...,
 
311
 {ApplicationN, [{ParN1,ValN1},...]}].</code>
 
312
    <p>The system configuration should be called <c>Name.config</c> and
 
313
      Erlang should be started with the command line argument
 
314
      <c>-config Name</c>. See <c>config(4)</c> for more information.</p>
 
315
    <p>Example: A file <c>test.config</c> is created with the following
 
316
      contents:</p>
 
317
    <code type="none">
 
318
[{ch_app, [{file, "testlog"}]}].</code>
 
319
    <p>The value of <c>file</c> will override the value of <c>file</c>
 
320
      as defined in the <c>.app</c> file:</p>
 
321
    <pre>
 
322
% <input>erl -config test</input>
 
323
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
 
324
 
 
325
Eshell V5.2.3.6  (abort with ^G)
 
326
1> <input>application:start(ch_app).</input>
 
327
ok
 
328
2> <input>application:get_env(ch_app, file).</input>
 
329
{ok,"testlog"}</pre>
 
330
    <p>If
 
331
      <seealso marker="release_handling#sys">release handling</seealso>
 
332
      is used, exactly one system configuration file should be used and
 
333
      that file should be called <c>sys.config</c></p>
 
334
    <p>The values in the <c>.app</c> file, as well as the values in a
 
335
      system configuration file, can be overridden directly from
 
336
      the command line:</p>
 
337
    <pre>
 
338
% <input>erl -ApplName Par1 Val1 ... ParN ValN</input></pre>
 
339
    <p>Example:</p>
 
340
    <pre>
 
341
% <input>erl -ch_app file '"testlog"'</input>
 
342
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
 
343
 
 
344
Eshell V5.2.3.6  (abort with ^G)
 
345
1> <input>application:start(ch_app).</input>
 
346
ok
 
347
2> <input>application:get_env(ch_app, file).</input>
 
348
{ok,"testlog"}</pre>
 
349
  </section>
 
350
 
 
351
  <section>
 
352
    <title>Application Start Types</title>
 
353
    <p>A <em>start type</em> is defined when starting the application:</p>
 
354
    <code type="none">
 
355
application:start(Application, Type)</code>
 
356
    <p><c>application:start(Application)</c> is the same as calling
 
357
      <c>application:start(Application, temporary)</c>. The type can
 
358
      also be <c>permanent</c> or <c>transient</c>:</p>
 
359
    <list type="bulleted">
 
360
      <item>If a permanent application terminates, all other
 
361
       applications and the runtime system are also terminated.</item>
 
362
      <item>If a transient application terminates with reason
 
363
      <c>normal</c>, this is reported but no other applications are
 
364
       terminated. If a transient application terminates abnormally,
 
365
       that is with any other reason than <c>normal</c>, all other
 
366
       applications and the runtime system are also terminated.</item>
 
367
      <item>If a temporary application terminates, this is reported but
 
368
       no other applications are terminated.</item>
 
369
    </list>
 
370
    <p>It is always possible to stop an application explicitly by
 
371
      calling <c>application:stop/1</c>. Regardless of the mode, no
 
372
      other applications will be affected.</p>
 
373
    <p>Note that transient mode is of little practical use, since when
 
374
      a supervision tree terminates, the reason is set to
 
375
      <c>shutdown</c>, not <c>normal</c>.</p>
 
376
  </section>
 
377
</chapter>
 
378