aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/design_principles/included_applications.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /system/doc/design_principles/included_applications.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'system/doc/design_principles/included_applications.xml')
-rw-r--r--system/doc/design_principles/included_applications.xml150
1 files changed, 150 insertions, 0 deletions
diff --git a/system/doc/design_principles/included_applications.xml b/system/doc/design_principles/included_applications.xml
new file mode 100644
index 0000000000..3adb27ea08
--- /dev/null
+++ b/system/doc/design_principles/included_applications.xml
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2003</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Included Applications</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>included_applications.xml</file>
+ </header>
+
+ <section>
+ <title>Definition</title>
+ <p>An application can <em>include</em> other applications.
+ An <em>included application</em> has its own application directory
+ and <c>.app</c> file, but it is started as part of the supervisor
+ tree of another application.</p>
+ <p>An application can only be included by one other application.</p>
+ <p>An included application can include other applications.</p>
+ <p>An application which is not included by any other application is
+ called a <em>primary application</em>.</p>
+ <marker id="inclappls"></marker>
+ <image file="../design_principles/inclappls.gif">
+ <icaption>Primary Application and Included Applications.</icaption>
+ </image>
+ <p>The application controller will automatically load any included
+ applications when loading a primary application, but not start
+ them. Instead, the top supervisor of the included application
+ must be started by a supervisor in the including application.</p>
+ <p>This means that when running, an included application is in fact
+ part of the primary application and a process in an included
+ application will consider itself belonging to the primary
+ application.</p>
+ </section>
+
+ <section>
+ <title>Specifying Included Applications</title>
+ <p>Which applications to include is defined by
+ the <c>included_applications</c> key in the <c>.app</c> file.</p>
+ <pre>
+{application, prim_app,
+ [{description, "Tree application"},
+ {vsn, "1"},
+ {modules, [prim_app_cb, prim_app_sup, prim_app_server]},
+ {registered, [prim_app_server]},
+ {included_applications, [incl_app]},
+ {applications, [kernel, stdlib, sasl]},
+ {mod, {prim_app_cb,[]}},
+ {env, [{file, "/usr/local/log"}]}
+ ]}.</pre>
+ </section>
+
+ <section>
+ <title>Synchronizing Processes During Startup</title>
+ <p>The supervisor tree of an included application is started as
+ part of the supervisor tree of the including application.
+ If there is a need for synchronization between processes in
+ the including and included applications, this can be achieved
+ by using <em>start phases</em>.</p>
+ <p>Start phases are defined by the <c>start_phases</c> key in
+ the <c>.app</c> file as a list of tuples <c>{Phase,PhaseArgs}</c>,
+ where <c>Phase</c> is an atom and <c>PhaseArgs</c> is a term.
+ Also, the value of the <c>mod</c> key of the including application
+ must be set to <c>{application_starter,[Module,StartArgs]}</c>,
+ where <c>Module</c> as usual is the application callback module
+ and <c>StartArgs</c> a term provided as argument to the callback
+ function <c>Module:start/2</c>.</p>
+ <code type="none">
+{application, prim_app,
+ [{description, "Tree application"},
+ {vsn, "1"},
+ {modules, [prim_app_cb, prim_app_sup, prim_app_server]},
+ {registered, [prim_app_server]},
+ {included_applications, [incl_app]},
+ {start_phases, [{init,[]}, {go,[]}]},
+ {applications, [kernel, stdlib, sasl]},
+ {mod, {application_starter,[prim_app_cb,[]]}},
+ {env, [{file, "/usr/local/log"}]}
+ ]}.
+
+{application, incl_app,
+ [{description, "Included application"},
+ {vsn, "1"},
+ {modules, [incl_app_cb, incl_app_sup, incl_app_server]},
+ {registered, []},
+ {start_phases, [{go,[]}]},
+ {applications, [kernel, stdlib, sasl]},
+ {mod, {incl_app_cb,[]}}
+ ]}.</code>
+ <p>When starting a primary application with included applications,
+ the primary application is started the normal way:
+ The application controller creates an application master for
+ the application, and the application master calls
+ <c>Module:start(normal, StartArgs)</c> to start the top
+ supervisor.</p>
+ <p>Then, for the primary application and each included application
+ in top-down, left-to-right order, the application master calls
+ <c>Module:start_phase(Phase, Type, PhaseArgs)</c> for each phase
+ defined for for the primary application, in that order.
+ Note that if a phase is not defined for an included application,
+ the function is not called for this phase and application.</p>
+ <p>The following requirements apply to the <c>.app</c> file for
+ an included application:</p>
+ <list type="bulleted">
+ <item>The <c>{mod, {Module,StartArgs}}</c> option must be
+ included. This option is used to find the callback module
+ <c>Module</c> of the application. <c>StartArgs</c> is ignored,
+ as <c>Module:start/2</c> is called only for the primary
+ application.</item>
+ <item>If the included application itself contains included
+ applications, instead the option
+ <c>{mod, {application_starter, [Module,StartArgs]}}</c> must be
+ included.</item>
+ <item>The <c>{start_phases, [{Phase,PhaseArgs}]}</c> option must
+ be included, and the set of specified phases must be a subset
+ of the set of phases specified for the primary application.</item>
+ </list>
+ <p>When starting <c>prim_app</c> as defined above, the application
+ controller will call the following callback functions, before
+ <c>application:start(prim_app)</c> returns a value:</p>
+ <code type="none">
+application:start(prim_app)
+ => prim_app_cb:start(normal, [])
+ => prim_app_cb:start_phase(init, normal, [])
+ => prim_app_cb:start_phase(go, normal, [])
+ => incl_app_cb:start_phase(go, normal, [])
+ok</code>
+ </section>
+</chapter>
+