← Back to branch summary

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

« back to all changes in this revision

Viewing changes to system/doc/design_principles/included_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/included_applications.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</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>Included Applications</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>included_applications.xml</file>
 
30
  </header>
 
31
 
 
32
  <section>
 
33
    <title>Definition</title>
 
34
    <p>An application can <em>include</em> other applications.
 
35
      An <em>included application</em> has its own application directory
 
36
      and <c>.app</c> file, but it is started as part of the supervisor
 
37
      tree of another application.</p>
 
38
    <p>An application can only be included by one other application.</p>
 
39
    <p>An included application can include other applications.</p>
 
40
    <p>An application which is not included by any other application is 
 
41
      called a <em>primary application</em>.</p>
 
42
    <marker id="inclappls"></marker>
 
43
    <image file="../design_principles/inclappls.gif">
 
44
      <icaption>Primary Application and Included Applications.</icaption>
 
45
    </image>
 
46
    <p>The application controller will automatically load any included
 
47
      applications when loading a primary application, but not start
 
48
      them. Instead, the top supervisor of the included application
 
49
      must be started by a supervisor in the including application.</p>
 
50
    <p>This means that when running, an included application is in fact
 
51
      part of the primary application and a process in an included
 
52
      application will consider itself belonging to the primary
 
53
      application.</p>
 
54
  </section>
 
55
 
 
56
  <section>
 
57
    <title>Specifying Included Applications</title>
 
58
    <p>Which applications to include is defined by
 
59
      the <c>included_applications</c> key in the <c>.app</c> file.</p>
 
60
    <pre>
 
61
{application, prim_app,
 
62
 [{description, "Tree application"},
 
63
  {vsn, "1"},
 
64
  {modules, [prim_app_cb, prim_app_sup, prim_app_server]},
 
65
  {registered, [prim_app_server]},
 
66
  {included_applications, [incl_app]},
 
67
  {applications, [kernel, stdlib, sasl]},
 
68
  {mod, {prim_app_cb,[]}},
 
69
  {env, [{file, "/usr/local/log"}]}
 
70
 ]}.</pre>
 
71
  </section>
 
72
 
 
73
  <section>
 
74
    <title>Synchronizing Processes During Startup</title>
 
75
    <p>The supervisor tree of an included application is started as
 
76
      part of the supervisor tree of the including application.
 
77
      If there is a need for synchronization between processes in
 
78
      the including and included applications, this can be achieved
 
79
      by using <em>start phases</em>.</p>
 
80
    <p>Start phases are defined by the <c>start_phases</c> key in
 
81
      the <c>.app</c> file as a list of tuples <c>{Phase,PhaseArgs}</c>,
 
82
      where <c>Phase</c> is an atom and <c>PhaseArgs</c> is a term.
 
83
      Also, the value of the <c>mod</c> key of the including application
 
84
      must be set to <c>{application_starter,[Module,StartArgs]}</c>,
 
85
      where <c>Module</c> as usual is the application callback module
 
86
      and <c>StartArgs</c> a term provided as argument to the callback
 
87
      function <c>Module:start/2</c>.</p>
 
88
    <code type="none">
 
89
{application, prim_app,
 
90
 [{description, "Tree application"},
 
91
  {vsn, "1"},
 
92
  {modules, [prim_app_cb, prim_app_sup, prim_app_server]},
 
93
  {registered, [prim_app_server]},
 
94
  {included_applications, [incl_app]},
 
95
  {start_phases, [{init,[]}, {go,[]}]},
 
96
  {applications, [kernel, stdlib, sasl]},
 
97
  {mod, {application_starter,[prim_app_cb,[]]}},
 
98
  {env, [{file, "/usr/local/log"}]}
 
99
 ]}.
 
100
 
 
101
{application, incl_app,
 
102
 [{description, "Included application"},
 
103
  {vsn, "1"},
 
104
  {modules, [incl_app_cb, incl_app_sup, incl_app_server]},
 
105
  {registered, []},
 
106
  {start_phases, [{go,[]}]},
 
107
  {applications, [kernel, stdlib, sasl]},
 
108
  {mod, {incl_app_cb,[]}}
 
109
 ]}.</code>
 
110
    <p>When starting a primary application with included applications,
 
111
      the primary application is started the normal way:
 
112
      The application controller creates an application master for
 
113
      the application, and the application master calls
 
114
      <c>Module:start(normal, StartArgs)</c> to start the top
 
115
      supervisor.</p>
 
116
    <p>Then, for the primary application and each included application
 
117
      in top-down, left-to-right order, the application master calls
 
118
      <c>Module:start_phase(Phase, Type, PhaseArgs)</c> for each phase
 
119
      defined for for the primary application, in that order.
 
120
      Note that if a phase is not defined for an included application,
 
121
      the function is not called for this phase and application.</p>
 
122
    <p>The following requirements apply to the <c>.app</c> file for
 
123
      an included application:</p>
 
124
    <list type="bulleted">
 
125
      <item>The <c>{mod, {Module,StartArgs}}</c> option must be
 
126
       included. This option is used to find the callback module
 
127
      <c>Module</c> of the application. <c>StartArgs</c> is ignored,
 
128
       as <c>Module:start/2</c> is called only for the primary
 
129
       application.</item>
 
130
      <item>If the included application itself contains included
 
131
       applications, instead the option
 
132
      <c>{mod, {application_starter, [Module,StartArgs]}}</c> must be
 
133
       included.</item>
 
134
      <item>The <c>{start_phases, [{Phase,PhaseArgs}]}</c> option must
 
135
       be included, and the set of specified phases must be a subset
 
136
       of the set of phases specified for the primary application.</item>
 
137
    </list>
 
138
    <p>When starting <c>prim_app</c> as defined above, the application
 
139
      controller will call the following callback functions, before
 
140
      <c>application:start(prim_app)</c> returns a value:</p>
 
141
    <code type="none">
 
142
application:start(prim_app)
 
143
 => prim_app_cb:start(normal, [])
 
144
 => prim_app_cb:start_phase(init, normal, [])
 
145
 => prim_app_cb:start_phase(go, normal, [])
 
146
 => incl_app_cb:start_phase(go, normal, [])
 
147
ok</code>
 
148
  </section>
 
149
</chapter>
 
150