aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/design_principles/included_applications.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/design_principles/included_applications.xml')
-rw-r--r--system/doc/design_principles/included_applications.xml67
1 files changed, 35 insertions, 32 deletions
diff --git a/system/doc/design_principles/included_applications.xml b/system/doc/design_principles/included_applications.xml
index 3aa43fd595..7f139edf76 100644
--- a/system/doc/design_principles/included_applications.xml
+++ b/system/doc/design_principles/included_applications.xml
@@ -28,35 +28,36 @@
<rev></rev>
<file>included_applications.xml</file>
</header>
+ <marker id="included appl"></marker>
<section>
- <title>Definition</title>
+ <title>Introduction</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
+ <p>An application that 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>
+ <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
+ <p>The application controller automatically loads any included
+ applications when loading a primary application, but does 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
+ part of the primary application, and a process in an included
+ application considers 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>
+ the <c>included_applications</c> key in the <c>.app</c> file:</p>
<pre>
{application, prim_app,
[{description, "Tree application"},
@@ -71,7 +72,7 @@
</section>
<section>
- <title>Synchronizing Processes During Startup</title>
+ <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
@@ -79,12 +80,12 @@
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
+ where <c>Phase</c> is an atom and <c>PhaseArgs</c> is a term.</p>
+ <p>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>
+ where <c>Module</c> as usual is the application callback module.
+ <c>StartArgs</c> is a term provided as argument to the callback
+ function <c>Module:start/2</c>:</p>
<code type="none">
{application, prim_app,
[{description, "Tree application"},
@@ -108,36 +109,38 @@
{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
+ the primary application is started the normal way, that is:</p>
+ <list type="bulleted">
+ <item>The application controller creates an application master for
+ the application</item>
+ <item>The application master calls
<c>Module:start(normal, StartArgs)</c> to start the top
- supervisor.</p>
+ supervisor.</item>
+ </list>
<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,
+ defined for the primary application, in that order. 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>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>
+ applications, instead the
+ <c>{mod, {application_starter, [Module,StartArgs]}}</c> option
+ 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>
+ 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>
+ controller calls 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, [])