diff options
Diffstat (limited to 'system/doc/design_principles/included_applications.xml')
| -rw-r--r-- | system/doc/design_principles/included_applications.xml | 150 |
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> + |