diff options
Diffstat (limited to 'system/doc/design_principles/included_applications.xml')
| -rw-r--r-- | system/doc/design_principles/included_applications.xml | 88 |
1 files changed, 46 insertions, 42 deletions
diff --git a/system/doc/design_principles/included_applications.xml b/system/doc/design_principles/included_applications.xml index 3aa43fd595..3257795e5f 100644 --- a/system/doc/design_principles/included_applications.xml +++ b/system/doc/design_principles/included_applications.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -28,35 +29,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 +73,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 +81,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 +110,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, []) |