File 0624-Update-Kernel-documentation.patch of Package erlang
From 3d70cee4034e4da37d125679345aa2a10c58cb34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Tue, 14 Apr 2015 23:21:36 +0200
Subject: [PATCH] Update Kernel documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Language cleaned up by technical writers from Combitech.
Proofreading and corrections by Björn Gustavsson and
Hans Bolinder.
---
lib/kernel/doc/src/app.xml | 168 +-
lib/kernel/doc/src/application.xml | 457 ++---
lib/kernel/doc/src/auth.xml | 56 +-
lib/kernel/doc/src/code.xml | 573 ++++---
lib/kernel/doc/src/config.xml | 89 +-
lib/kernel/doc/src/disk_log.xml | 989 +++++------
lib/kernel/doc/src/erl_boot_server.xml | 67 +-
lib/kernel/doc/src/erl_ddll.xml | 1342 ++++++++-------
lib/kernel/doc/src/erl_prim_loader_stub.xml | 2 +-
lib/kernel/doc/src/erlang_stub.xml | 2 +-
lib/kernel/doc/src/error_handler.xml | 78 +-
lib/kernel/doc/src/error_logger.xml | 381 +++--
lib/kernel/doc/src/file.xml | 1493 +++++++++--------
lib/kernel/doc/src/gen_sctp.xml | 1468 ++++++++--------
lib/kernel/doc/src/gen_tcp.xml | 487 +++---
lib/kernel/doc/src/gen_udp.xml | 223 ++-
lib/kernel/doc/src/global.xml | 296 ++--
lib/kernel/doc/src/global_group.xml | 175 +-
lib/kernel/doc/src/heart.xml | 166 +-
lib/kernel/doc/src/inet.xml | 1659 +++++++++----------
lib/kernel/doc/src/inet_res.xml | 300 ++--
lib/kernel/doc/src/init_stub.xml | 14 +-
lib/kernel/doc/src/kernel_app.xml | 342 ++--
lib/kernel/doc/src/net_adm.xml | 85 +-
lib/kernel/doc/src/net_kernel.xml | 277 ++--
lib/kernel/doc/src/os.xml | 234 +--
lib/kernel/doc/src/pg2.xml | 123 +-
lib/kernel/doc/src/ref_man.xml | 6 +-
lib/kernel/doc/src/rpc.xml | 441 +++--
lib/kernel/doc/src/seq_trace.xml | 219 +--
lib/kernel/doc/src/user.xml | 6 +-
lib/kernel/doc/src/wrap_log_reader.xml | 154 +-
lib/kernel/doc/src/zlib_stub.xml | 14 +-
33 files changed, 6364 insertions(+), 6022 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,17 +61,44 @@
<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>
</datatype>
</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>
--
2.26.2
