diff options
Diffstat (limited to 'lib/kernel/doc/src/application.xml')
| -rw-r--r-- | lib/kernel/doc/src/application.xml | 457 |
1 files changed, 238 insertions, 219 deletions
diff --git a/lib/kernel/doc/src/application.xml b/lib/kernel/doc/src/application.xml index 4d8e6ce94b..16de17c901 100644 --- a/lib/kernel/doc/src/application.xml +++ b/lib/kernel/doc/src/application.xml @@ -33,23 +33,25 @@ <description> <p>In OTP, <em>application</em> denotes a component implementing some specific functionality, that can be started and stopped as a - unit, and which can be re-used in other systems as well. This - module interfaces the <em>application controller</em>, a process - started at every Erlang runtime system, and contains functions - for controlling applications (for example starting and stopping + unit, and that can be reused in other systems. This + module interacts with <em>application controller</em>, a process + started at every Erlang runtime system. This module contains functions + for controlling applications (for example, starting and stopping applications), and functions to access information about - applications (for example configuration parameters).</p> - <p>An application is defined by an <em>application specification</em>. The specification is normally located in an - <em>application resource file</em> called <c>Application.app</c>, - where <c>Application</c> is the name of the application. Refer to - <seealso marker="app">app(4)</seealso> for more information about - the application specification.</p> + applications (for example, configuration parameters).</p> + <p>An application is defined by an <em>application specification</em>. + The specification is normally located in an + <em>application resource file</em> named <c>Application.app</c>, + where <c>Application</c> is the application name. For details + about the application specification, see + <seealso marker="app"><c>app(4)</c></seealso>.</p> <p>This module can also be viewed as a behaviour for an application implemented according to the OTP design principles as a supervision tree. The definition of how to start and stop - the tree should be located in an <em>application callback module</em> exporting a pre-defined set of functions.</p> - <p>Refer to <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso> for more information about - applications and behaviours.</p> + the tree is to be located in an <em>application callback module</em>, + exporting a predefined set of functions.</p> + <p>For details about applications and behaviours, see + <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso>.</p> </description> <datatypes> <datatype> @@ -59,7 +61,6 @@ <name name="restart_type"/> </datatype> <datatype> - <!-- Parameterized opaque types are NYI: --> <name>tuple_of(T)</name> <desc><p><marker id="type-tuple_of"/> A tuple where the elements are of type <c>T</c>.</p></desc> @@ -67,9 +68,37 @@ </datatypes> <funcs> <func> + <name name="ensure_all_started" arity="1"/> + <name name="ensure_all_started" arity="2"/> + <fsummary>Load and start an application and its dependencies, recursively.</fsummary> + <desc> + <p>Equivalent to calling + <seealso marker="#start/1"><c>start/1,2</c></seealso> + repeatedly on all dependencies that are not yet started for an application.</p> + <p>Returns <c>{ok, AppNames}</c> for a successful start or for an already started + application (which is, however, omitted from the <c>AppNames</c> list).</p> + <p>The function reports <c>{error, {AppName,Reason}}</c> for errors, where + <c>Reason</c> is any possible reason returned by + <seealso marker="#start/1"><c>start/1,2</c></seealso> + when starting a specific dependency.</p> + <p>If an error occurs, the applications started by the function are stopped + to bring the set of running applications back to its initial state.</p> + </desc> + </func> + <func> + <name name="ensure_started" arity="1"/> + <name name="ensure_started" arity="2"/> + <fsummary>Load and start an application.</fsummary> + <desc> + <p>Equivalent to + <seealso marker="#start/1"><c>start/1,2</c></seealso> + except it returns <c>ok</c> for already started applications.</p> + </desc> + </func> + <func> <name name="get_all_env" arity="0"/> <name name="get_all_env" arity="1"/> - <fsummary>Get the configuration parameters for an application</fsummary> + <fsummary>Get the configuration parameters for an application.</fsummary> <desc> <p>Returns the configuration parameters and their values for <c><anno>Application</anno></c>. If the argument is omitted, it defaults to @@ -82,7 +111,7 @@ <func> <name name="get_all_key" arity="0"/> <name name="get_all_key" arity="1"/> - <fsummary>Get the application specification keys</fsummary> + <fsummary>Get the application specification keys.</fsummary> <desc> <p>Returns the application specification keys and their values for <c><anno>Application</anno></c>. If the argument is omitted, it @@ -96,7 +125,7 @@ <func> <name name="get_application" arity="0"/> <name name="get_application" arity="1"/> - <fsummary>Get the name of an application containing a certain process or module</fsummary> + <fsummary>Get the name of an application containing a certain process or module.</fsummary> <desc> <p>Returns the name of the application to which the process <c><anno>Pid</anno></c> or the module <c><anno>Module</anno></c> belongs. Providing no @@ -110,222 +139,212 @@ <func> <name name="get_env" arity="1"/> <name name="get_env" arity="2"/> - <fsummary>Get the value of a configuration parameter</fsummary> + <fsummary>Get the value of a configuration parameter.</fsummary> <desc> - <p>Returns the value of the configuration parameter <c><anno>Par</anno></c> + <p>Returns the value of configuration parameter <c><anno>Par</anno></c> for <c><anno>Application</anno></c>. If the application argument is omitted, it defaults to the application of the calling process.</p> - <p>If the specified application is not loaded, or - the configuration parameter does not exist, or if the process - executing the call does not belong to any application, - the function returns <c>undefined</c>.</p> + <p>Returns <c>undefined</c> if any of the following applies:</p> + <list type="bulleted"> + <item>The specified application is not loaded.</item> + <item>The configuration parameter does not exist.</item> + <item>The process executing the call does not belong to any application.</item> + </list> </desc> </func> <func> <name name="get_env" arity="3"/> - <fsummary>Get the value of a configuration parameter using a default</fsummary> + <fsummary>Get the value of a configuration parameter using a default.</fsummary> <desc> - <p>Works like <seealso marker="#get_env/2">get_env/2</seealso> but returns - <c><anno>Def</anno></c> value when configuration parameter + <p>Works like <seealso marker="#get_env/2"><c>get_env/2</c></seealso> but returns + value <c><anno>Def</anno></c> when configuration parameter <c><anno>Par</anno></c> does not exist.</p> </desc> </func> <func> <name name="get_key" arity="1"/> <name name="get_key" arity="2"/> - <fsummary>Get the value of an application specification key</fsummary> + <fsummary>Get the value of an application specification key.</fsummary> <desc> <p>Returns the value of the application specification key <c><anno>Key</anno></c> for <c><anno>Application</anno></c>. If the application argument is omitted, it defaults to the application of the calling process.</p> - <p>If the specified application is not loaded, or - the specification key does not exist, or if the process - executing the call does not belong to any application, - the function returns <c>undefined</c>.</p> + <p>Returns <c>undefined</c> if any of the following applies:</p> + <list type="bulleted"> + <item>The specified application is not loaded.</item> + <item>The specification key does not exist.</item> + <item>The process executing the call does not belong to any application.</item> + </list> + </desc> </func> <func> <name name="load" arity="1"/> <name name="load" arity="2"/> - <fsummary>Load an application</fsummary> + <fsummary>Load an application.</fsummary> <type name="application_spec"/> <type name="application_opt"/> <desc> <p>Loads the application specification for an application into - the application controller. It will also load the application - specifications for any included applications. Note that - the function does not load the actual Erlang object code.</p> - <p>The application can be given by its name <c><anno>Application</anno></c>. - In this case the application controller will search the code + the application controller. It also loads the application + specifications for any included applications. Notice that + the function does not load the Erlang object code.</p> + <p>The application can be specified by its name <c><anno>Application</anno></c>. + In this case, the application controller searches the code path for the application resource file <c><anno>Application</anno>.app</c> - and load the specification it contains.</p> - <p>The application specification can also be given directly as a - tuple <c><anno>AppSpec</anno></c>. This tuple should have the format and - contents as described in <c>app(4)</c>.</p> + and loads the specification it contains.</p> + <p>The application specification can also be specified directly as a + tuple <c><anno>AppSpec</anno></c>, having the format and + contents as described in + <seealso marker="app"><c>app(4)</c></seealso>.</p> <p>If <c><anno>Distributed</anno> == {<anno>Application</anno>,[<anno>Time</anno>,]<anno>Nodes</anno>}</c>, - the application will be distributed. The argument overrides - the value for the application in the Kernel configuration + the application becomes distributed. The argument overrides + the value for the application in the <c>Kernel</c> configuration parameter <c>distributed</c>. <c><anno>Application</anno></c> must be - the name of the application (same as in the first argument). - If a node crashes and <c><anno>Time</anno></c> has been specified, then - the application controller will wait for <c><anno>Time</anno></c> + the application name (same as in the first argument). + If a node crashes and <c><anno>Time</anno></c> is specified, + the application controller waits for <c><anno>Time</anno></c> milliseconds before attempting to restart the application on - another node. If <c><anno>Time</anno></c> is not specified, it will - default to 0 and the application will be restarted + another node. If <c><anno>Time</anno></c> is not specified, it + defaults to <c>0</c> and the application is restarted immediately.</p> <p><c><anno>Nodes</anno></c> is a list of node names where the application - may run, in priority from left to right. Node names can be + can run, in priority from left to right. Node names can be grouped using tuples to indicate that they have the same - priority. Example:</p> + priority.</p> + <p><em>Example:</em></p> <code type="none"> Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code> - <p>This means that the application should preferably be started + <p>This means that the application is preferably to be started at <c>cp1@cave</c>. If <c>cp1@cave</c> is down, - the application should be started at either <c>cp2@cave</c> + the application is to be started at <c>cp2@cave</c> or <c>cp3@cave</c>.</p> <p>If <c>Distributed == default</c>, the value for - the application in the Kernel configuration parameter - <c>distributed</c> will be used.</p> + the application in the <c>Kernel</c> configuration parameter + <c>distributed</c> is used.</p> </desc> </func> <func> <name name="loaded_applications" arity="0"/> - <fsummary>Get the currently loaded applications</fsummary> + <fsummary>Get the currently loaded applications.</fsummary> <desc> - <p>Returns a list with information about the applications which - have been loaded using <c>load/1,2</c>, also included - applications. <c><anno>Application</anno></c> is the application name. - <c><anno>Description</anno></c> and <c><anno>Vsn</anno></c> are the values of its - <c>description</c> and <c>vsn</c> application specification + <p>Returns a list with information about the applications, and included + applications, which are loaded using <c>load/1,2</c>. + <c><anno>Application</anno></c> is the application name. + <c><anno>Description</anno></c> and <c><anno>Vsn</anno></c> are the values + of their <c>description</c> and <c>vsn</c> application specification keys, respectively.</p> </desc> </func> <func> <name name="permit" arity="2"/> - <fsummary>Change an application's permission to run on a node.</fsummary> + <fsummary>Change the permission for an application to run at a node.</fsummary> <desc> <p>Changes the permission for <c><anno>Application</anno></c> to run at - the current node. The application must have been loaded using + the current node. The application must be loaded using <c>load/1,2</c> for the function to have effect.</p> <p>If the permission of a loaded, but not started, application - is set to <c>false</c>, <c>start</c> will return <c>ok</c> but - the application will not be started until the permission is + is set to <c>false</c>, <c>start</c> returns <c>ok</c> but + the application is not started until the permission is set to <c>true</c>.</p> <p>If the permission of a running application is set to - <c>false</c>, the application will be stopped. If - the permission later is set to <c>true</c>, it will be + <c>false</c>, the application is stopped. If + the permission later is set to <c>true</c>, it is restarted.</p> <p>If the application is distributed, setting the permission to <c>false</c> means that the application will be started at, or moved to, another node according to how its distribution is - configured (see <c>load/2</c> above).</p> + configured + (see <seealso marker="#load/2"><c>load/2</c></seealso>).</p> <p>The function does not return until the application is - started, stopped or successfully moved to another node. - However, in some cases where permission is set to <c>true</c> - the function may return <c>ok</c> even though the application - itself has not started. This is true when an application - cannot start because it has dependencies to other - applications which have not yet been started. When they have - been started, <c>Application</c> will be started as well.</p> + started, stopped, or successfully moved to another node. + However, in some cases where permission is set to <c>true</c>, + the function returns <c>ok</c> even though the application + is not started. This is true when an application + cannot start because of dependencies to other + applications that are not yet started. When they are + started, <c>Application</c> is started as well.</p> <p>By default, all applications are loaded with permission - <c>true</c> on all nodes. The permission is configurable by - using the Kernel configuration parameter <c>permissions</c>.</p> + <c>true</c> on all nodes. The permission can be configured + using the <c>Kernel</c> configuration parameter <c>permissions</c>.</p> </desc> </func> <func> <name name="set_env" arity="3"/> <name name="set_env" arity="4"/> - <fsummary>Set the value of a configuration parameter</fsummary> + <fsummary>Set the value of a configuration parameter.</fsummary> <desc> - <p>Sets the value of the configuration parameter <c><anno>Par</anno></c> for + <p>Sets the value of configuration parameter <c><anno>Par</anno></c> for <c><anno>Application</anno></c>.</p> - <p><c>set_env/4</c> uses the standard <c>gen_server</c> timeout - value (5000 ms). The <c>timeout</c> option can be provided - if another timeout value is useful, for example, in situations + <p><c>set_env/4</c> uses the standard <c>gen_server</c> time-out + value (5000 ms). Option <c>timeout</c> can be specified + if another time-out value is useful, for example, in situations where the application controller is heavily loaded.</p> <p>If <c>set_env/4</c> is called before the application is loaded, - the application environment values specified in the <c>Application.app</c> - file will override the ones previously set. This is also true for application + the application environment values specified in file <c>Application.app</c> + override the ones previously set. This is also true for application reloads.</p> - <p>The <c>persistent</c> option can be set to <c>true</c> - when there is a need to guarantee parameters set with <c>set_env/4</c> - will not be overridden by the ones defined in the application resource - file on load. This means persistent values will stick after the application + <p>Option <c>persistent</c> can be set to <c>true</c> + to guarantee that parameters set with <c>set_env/4</c> + are not overridden by those defined in the application resource + file on load. This means that persistent values will stick after the application is loaded and also on application reload.</p> <warning> - <p>Use this function only if you know what you are doing, - that is, on your own applications. It is very application - and configuration parameter dependent when and how often - the value is read by the application, and careless use - of this function may put the application in a - weird, inconsistent, and malfunctioning state. </p> + <p>Use this function only if you know what you are doing, + that is, on your own applications. It is very + application-dependent and + configuration parameter-dependent when and how often + the value is read by the application. Careless use + of this function can put the application in a + weird, inconsistent, and malfunctioning state.</p> </warning> </desc> </func> <func> - <name name="ensure_started" arity="1"/> - <name name="ensure_started" arity="2"/> - <fsummary>Load and start an application</fsummary> - <desc> - <p>Equivalent to <seealso marker="#start/2"><c>application:start/1,2</c></seealso> except - it returns <c>ok</c> for already started applications.</p> - </desc> - </func> - <func> - <name name="ensure_all_started" arity="1"/> - <name name="ensure_all_started" arity="2"/> - <fsummary>Load and start an application and its dependencies, recursively</fsummary> - <desc> - <p>Equivalent to calling <seealso marker="#start/2"><c>application:start/1,2</c></seealso> - repeatedly on all dependencies that have not yet been started for an application. - The function returns <c>{ok, AppNames}</c> for a successful start or for an already started - application (which are however omitted from the <c>AppNames</c> list), and reports - <c>{error, {AppName,Reason}}</c> for errors, where <c>Reason</c> is any possible reason - returned by <seealso marker="#start/2"><c>application:start/1,2</c></seealso> when starting a - specific dependency. In case of an error, the applications that were started by the - function are stopped to bring the set of running applications back to its initial state.</p> - </desc> - </func> - <func> <name name="start" arity="1"/> <name name="start" arity="2"/> - <fsummary>Load and start an application</fsummary> - <desc> + <fsummary>Load and start an application.</fsummary> + <desc> <p>Starts <c><anno>Application</anno></c>. If it is not loaded, - the application controller will first load it using - <c>load/1</c>. It will make sure any included applications - are loaded, but will not start them. That is assumed to be + the application controller first loads it using + <c>load/1</c>. It ensures that any included applications + are loaded, but does not start them. That is assumed to be taken care of in the code for <c><anno>Application</anno></c>.</p> <p>The application controller checks the value of the application specification key <c>applications</c>, to - ensure that all applications that should be started before - this application are running. If not, + ensure that all applications needed to be started before + this application are running. Otherwise, <c>{error,{not_started,App}}</c> is returned, where <c>App</c> is the name of the missing application.</p> - <p>The application controller then creates an <em>application master</em> for the application. The application master is + <p>The application controller then creates an <em>application master</em> + for the application. The application master is the group leader of all the processes in the application. The application master starts the application by calling the application callback function <c>Module:start/2</c> as defined by the application specification key <c>mod</c>.</p> - <p>The <c><anno>Type</anno></c> argument specifies the type of + <p>Argument <c><anno>Type</anno></c> specifies the type of the application. If omitted, it defaults to <c>temporary</c>.</p> <list type="bulleted"> <item>If a permanent application terminates, all other applications and the entire Erlang node are also terminated.</item> - <item>If a transient application terminates with <c>Reason == normal</c>, this is reported but no other applications are - terminated. If a transient application terminates - abnormally, all other applications and the entire Erlang - node are also terminated.</item> + <item> + <list type="bulleted"> + <item>If a transient application terminates with <c>Reason == normal</c>, + this is reported but no other applications are terminated.</item> + <item>If a transient application terminates abnormally, all other + applications and the entire Erlang node are also terminated.</item> + </list> + </item> <item>If a temporary application terminates, this is reported but no other applications are terminated.</item> </list> - <p>Note that it is always possible to stop an application + <p>Notice that an application can always be stopped explicitly by calling <c>stop/1</c>. Regardless of the type of - the application, no other applications will be affected.</p> - <p>Note also that the transient type is of little practical use, - since when a supervision tree terminates, the reason is set to + the application, no other applications are affected.</p> + <p>Notice also that the transient type is of little practical use, + because when a supervision tree terminates, the reason is set to <c>shutdown</c>, not <c>normal</c>.</p> </desc> </func> @@ -334,13 +353,13 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code> <fsummary>Get the start type of an ongoing application startup.</fsummary> <desc> <p>This function is intended to be called by a process belonging - to an application, when the application is being started, to - determine the start type which is either <c><anno>StartType</anno></c> or + to an application, when the application is started, to + determine the start type, which is <c><anno>StartType</anno></c> or <c>local</c>.</p> - <p>See <seealso marker="#start_type"><c>Module:start/2</c></seealso> for a description of - <c><anno>StartType</anno></c>.</p> - <p><c>local</c> is returned if only parts of the application is - being restarted (by a supervisor), or if the function is + <p>For a description of <c><anno>StartType</anno></c>, see + <seealso marker="#start_type"><c>Module:start/2</c></seealso>.</p> + <p><c>local</c> is returned if only parts of the application are + restarted (by a supervisor), or if the function is called outside a startup.</p> <p>If the process executing the call does not belong to any application, the function returns <c>undefined</c>.</p> @@ -348,103 +367,106 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code> </func> <func> <name name="stop" arity="1"/> - <fsummary>Stop an application</fsummary> + <fsummary>Stop an application.</fsummary> <desc> <p>Stops <c><anno>Application</anno></c>. The application master calls <c>Module:prep_stop/1</c>, if such a function is defined, and - then tells the top supervisor of the application to shutdown - (see <c>supervisor(3)</c>). This means that the entire + then tells the top supervisor of the application to shut down + (see <seealso marker="stdlib:supervisor"><c>supervisor(3)</c></seealso>). + This means that the entire supervision tree, including included applications, is terminated in reversed start order. After the shutdown, the application master calls <c>Module:stop/1</c>. <c>Module</c> is the callback module as defined by the application specification key <c>mod</c>.</p> - <p>Last, the application master itself terminates. Note that all - processes with the application master as group leader, i.e. + <p>Last, the application master terminates. Notice that all + processes with the application master as group leader, that is, processes spawned from a process belonging to the application, - thus are terminated as well.</p> + are also terminated.</p> <p>When stopped, the application is still loaded.</p> - <p>In order to stop a distributed application, <c>stop/1</c> - has to be called on all nodes where it can execute (that is, + <p>To stop a distributed application, <c>stop/1</c> + must be called on all nodes where it can execute (that is, on all nodes where it has been started). The call to <c>stop/1</c> on the node where the application currently - executes will stop its execution. The application will not be - moved between nodes due to <c>stop/1</c> being called on + executes stops its execution. The application is not + moved between nodes, as <c>stop/1</c> is called on the node where the application currently executes before <c>stop/1</c> is called on the other nodes.</p> </desc> </func> <func> <name name="takeover" arity="2"/> - <fsummary>Take over a distributed application</fsummary> + <fsummary>Take over a distributed application.</fsummary> <desc> - <p>Performs a takeover of the distributed application + <p>Takes over the distributed application <c><anno>Application</anno></c>, which executes at another node <c>Node</c>. At the current node, the application is restarted by calling <c>Module:start({takeover,Node},StartArgs)</c>. <c>Module</c> and <c>StartArgs</c> are retrieved from the loaded application specification. The application at the other node is not - stopped until the startup is completed, i.e. when + stopped until the startup is completed, that is, when <c>Module:start/2</c> and any calls to <c>Module:start_phase/3</c> have returned.</p> - <p>Thus two instances of the application will run simultaneously - during the takeover, which makes it possible to transfer data - from the old to the new instance. If this is not acceptable - behavior, parts of the old instance may be shut down when - the new instance is started. Note that the application may - not be stopped entirely however, at least the top supervisor + <p>Thus, two instances of the application run simultaneously + during the takeover, so that data can be transferred + from the old to the new instance. If this is not an acceptable + behavior, parts of the old instance can be shut down when + the new instance is started. However, the application cannot + be stopped entirely, at least the top supervisor must remain alive.</p> - <p>See <c>start/1,2</c> for a description of <c>Type</c>.</p> + <p>For a description of <c>Type</c>, see + <seealso marker="#start/1"><c>start/1,2</c></seealso>.</p> </desc> </func> <func> <name name="unload" arity="1"/> - <fsummary>Unload an application</fsummary> + <fsummary>Unload an application.</fsummary> <desc> <p>Unloads the application specification for <c><anno>Application</anno></c> - from the application controller. It will also unload + from the application controller. It also unloads the application specifications for any included applications. - Note that the function does not purge the actual Erlang + Notice that the function does not purge the Erlang object code.</p> </desc> </func> <func> <name name="unset_env" arity="2"/> <name name="unset_env" arity="3"/> - <fsummary>Unset the value of a configuration parameter</fsummary> + <fsummary>Unset the value of a configuration parameter.</fsummary> <desc> <p>Removes the configuration parameter <c><anno>Par</anno></c> and its value for <c><anno>Application</anno></c>.</p> <p><c>unset_env/2</c> uses the standard <c>gen_server</c> - timeout value (5000 ms). The <c>timeout</c> option can be - provided if another timeout value is useful, for example, in + time-out value (5000 ms). Option <c>timeout</c> can be + specified if another time-out value is useful, for example, in situations where the application controller is heavily loaded.</p> <p><c>unset_env/3</c> also allows the persistent option to be passed - (see <c>set_env/4</c> above).</p> - <warning> - <p>Use this function only if you know what you are doing, - that is, on your own applications. It is very application - and configuration parameter dependent when and how often - the value is read by the application, and careless use - of this function may put the application in a - weird, inconsistent, and malfunctioning state. </p> + (see <seealso marker="#set_env/4"><c>set_env/4</c></seealso>).</p> + <warning> + <p>Use this function only if you know what you are doing, + that is, on your own applications. It is very + application-dependent and configuration + parameter-dependent when and how often + the value is read by the application. Careless use + of this function can put the application in a + weird, inconsistent, and malfunctioning state.</p> </warning> </desc> </func> <func> <name name="which_applications" arity="0"/> <name name="which_applications" arity="1"/> - <fsummary>Get the currently running applications</fsummary> + <fsummary>Get the currently running applications.</fsummary> <desc> - <p>Returns a list with information about the applications which + <p>Returns a list with information about the applications that are currently running. <c><anno>Application</anno></c> is the application - name. <c><anno>Description</anno></c> and <c><anno>Vsn</anno></c> are the values of its - <c>description</c> and <c>vsn</c> application specification + name. <c><anno>Description</anno></c> and <c><anno>Vsn</anno></c> are the + values of their <c>description</c> and <c>vsn</c> application specification keys, respectively.</p> <p><c>which_applications/0</c> uses the standard - <c>gen_server</c> timeout value (5000 ms). A <c><anno>Timeout</anno></c> - argument can be provided if another timeout value is useful, + <c>gen_server</c> time-out value (5000 ms). A <c><anno>Timeout</anno></c> + argument can be specified if another time-out value is useful, for example, in situations where the application controller is heavily loaded.</p> </desc> @@ -452,81 +474,81 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code> </funcs> <section> - <title>CALLBACK MODULE</title> - <p>The following functions should be exported from an + <title>Callback Module</title> + <p>The following functions are to be exported from an <c>application</c> callback module.</p> </section> <funcs> <func> <name>Module:start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State} | {error, Reason}</name> - <fsummary>Start an application</fsummary> + <fsummary>Start an application.</fsummary> <type> - <v>StartType = <seealso marker="#type-start_type">start_type()</seealso></v> + <v>StartType = <seealso marker="#type-start_type"><c>start_type()</c></seealso></v> <v>StartArgs = term()</v> <v>Pid = pid()</v> <v>State = term()</v> </type> <desc> <p>This function is called whenever an application is started - using <c>application:start/1,2</c>, and should start + using <c>start/1,2</c>, and is to start the processes of the application. If the application is structured according to the OTP design principles as a supervision tree, this means starting the top supervisor of the tree.</p> <p><marker id="start_type"/><c>StartType</c> defines the type of start:</p> <list type="bulleted"> - <item><c>normal</c> if it's a normal startup.</item> + <item><c>normal</c> if it is a normal startup.</item> <item><c>normal</c> also if the application is distributed and - started at the current node due to a failover from another + started at the current node because of a failover from another node, and the application specification key <c>start_phases == undefined</c>.</item> <item><c>{takeover,Node}</c> if the application is - distributed and started at the current node due to a + distributed and started at the current node because of a takeover from <c>Node</c>, either because - <c>application:takeover/2</c> has been called or because + <c>takeover/2</c> has been called or because the current node has higher priority than <c>Node</c>.</item> <item><c>{failover,Node}</c> if the application is - distributed and started at the current node due to a + distributed and started at the current node because of a failover from <c>Node</c>, and the application specification key <c>start_phases /= undefined</c>.</item> </list> <p><c>StartArgs</c> is the <c>StartArgs</c> argument defined by the application specification key <c>mod</c>.</p> - <p>The function should return <c>{ok,Pid}</c> or - <c>{ok,Pid,State}</c> where <c>Pid</c> is the pid of the top + <p>The function is to return <c>{ok,Pid}</c> or + <c>{ok,Pid,State}</c>, where <c>Pid</c> is the pid of the top supervisor and <c>State</c> is any term. If omitted, - <c>State</c> defaults to <c>[]</c>. If later the application - is stopped, <c>State</c> is passed to + <c>State</c> defaults to <c>[]</c>. If the application + is stopped later, <c>State</c> is passed to <c>Module:prep_stop/1</c>.</p> </desc> </func> <func> <name>Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}</name> - <fsummary>Extended start of an application</fsummary> + <fsummary>Extended start of an application.</fsummary> <type> <v>Phase = atom()</v> - <v>StartType = <seealso marker="#type-start_type">start_type()</seealso></v> + <v>StartType = <seealso marker="#type-start_type"><c>start_type()</c></seealso></v> <v>PhaseArgs = term()</v> <v>Pid = pid()</v> <v>State = state()</v> </type> <desc> - <p>This function is used to start an application with included - applications, when there is a need for synchronization between + <p>Starts an application with included + applications, when synchronization is needed between processes in the different applications during startup.</p> - <p>The start phases is defined by the application specification + <p>The start phases are defined by the application specification key <c>start_phases == [{Phase,PhaseArgs}]</c>. For included applications, the set of phases must be a subset of the set of phases defined for the including application.</p> <p>The function is called for each start phase (as defined for the primary application) for the primary application and all included applications, for which the start phase is defined.</p> - <p>See <c>Module:start/2</c> for a description of - <c>StartType</c>.</p> + <p>For a description of <c>StartType</c>, see + <seealso marker="Module:start/2"><c>Module:start/2</c></seealso>.</p> </desc> </func> <func> <name>Module:prep_stop(State) -> NewState</name> - <fsummary>Prepare an application for termination</fsummary> + <fsummary>Prepare an application for termination.</fsummary> <type> <v>State = NewState = term()</v> </type> @@ -536,28 +558,26 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code> the application.</p> <p><c>State</c> is the state returned from <c>Module:start/2</c>, or <c>[]</c> if no state was returned. - <c>NewState</c> is any term and will be passed to + <c>NewState</c> is any term and is passed to <c>Module:stop/1</c>.</p> <p>The function is optional. If it is not defined, the processes - will be terminated and then <c>Module:stop(State)</c> is - called.</p> + are terminated and then <c>Module:stop(State)</c> is called.</p> </desc> </func> <func> <name>Module:stop(State)</name> - <fsummary>Clean up after termination of an application</fsummary> + <fsummary>Clean up after termination of an application.</fsummary> <type> <v>State = term()</v> </type> <desc> <p>This function is called whenever an application has stopped. It is intended to be the opposite of <c>Module:start/2</c> - and should do any necessary cleaning up. The return value is + and is to do any necessary cleaning up. The return value is ignored.</p> - <p><c>State</c> is the return value of - <c>Module:prep_stop/1</c>, if such a function exists. - Otherwise <c>State</c> is taken from the return value of - <c>Module:start/2</c>.</p> + <p><c>State</c> is the return value of <c>Module:prep_stop/1</c>, + if such a function exists. Otherwise <c>State</c> is taken from + the return value of <c>Module:start/2</c>.</p> </desc> </func> <func> @@ -572,19 +592,18 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code> </type> <desc> <p>This function is called by an application after a code - replacement, if there are any changes to the configuration - parameters.</p> - <p><c>Changed</c> is a list of parameter-value tuples with all - configuration parameters with changed values, <c>New</c> is - a list of parameter-value tuples with all configuration - parameters that have been added, and <c>Removed</c> is a list - of all parameters that have been removed.</p> + replacement, if the configuration parameters have changed.</p> + <p><c>Changed</c> is a list of parameter-value tuples including all + configuration parameters with changed values.</p> + <p><c>New</c> is a list of parameter-value tuples including all + added configuration parameters.</p> + <p><c>Removed</c> is a list of all removed parameters.</p> </desc> </func> </funcs> <section> - <title>SEE ALSO</title> + <title>See Also</title> <p><seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso>, <seealso marker="kernel_app">kernel(6)</seealso>, <seealso marker="app">app(4)</seealso></p> |