The R13B03 release.OTP_R13B03

1 files changed, 622 insertions, 0 deletions

diff --git a/lib/kernel/doc/src/application.xml b/lib/kernel/doc/src/application.xml
new file mode 100644
index 0000000000..08ef0b1e52
--- /dev/null
+++ b/lib/kernel/doc/src/application.xml
@@ -0,0 +1,622 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1996</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>application</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>application</module>
+  <modulesummary>Generic OTP application functions</modulesummary>
+  <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
+      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>
+    <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>
+  </description>
+  <funcs>
+    <func>
+      <name>get_all_env() -> Env</name>
+      <name>get_all_env(Application) -> Env</name>
+      <fsummary>Get the configuration parameters for an application</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Env = [{Par,Val}]</v>
+        <v>&nbsp;Par = atom()</v>
+        <v>&nbsp;Val = term()</v>
+      </type>
+      <desc>
+        <p>Returns the configuration parameters and their values for
+          <c>Application</c>. If the argument is omitted, it defaults to
+          the application of the calling process.</p>
+        <p>If the specified application is not loaded, or if the process
+          executing the call does not belong to any application,
+          the function returns <c>[]</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>get_all_key() -> {ok, Keys} | []</name>
+      <name>get_all_key(Application) -> {ok, Keys} | undefined </name>
+      <fsummary>Get the application specification keys</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Keys = [{Key,Val}]</v>
+        <v>&nbsp;Key = atom()</v>
+        <v>&nbsp;Val = term()</v>
+      </type>
+      <desc>
+        <p>Returns the application specification keys and their values
+          for <c>Application</c>. If the argument is omitted, it
+          defaults to the application of the calling process.</p>
+        <p>If the specified application is not loaded, the function
+          returns <c>undefined</c>. If the process executing the call
+          does not belong to any application, the function returns
+          <c>[]</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>get_application() -> {ok, Application} | undefined</name>
+      <name>get_application(Pid | Module) -> {ok, Application} | undefined</name>
+      <fsummary>Get the name of an application containing a certain process or module</fsummary>
+      <type>
+        <v>Pid = pid()</v>
+        <v>Module = atom()</v>
+        <v>Application = atom()</v>
+      </type>
+      <desc>
+        <p>Returns the name of the application to which the process
+          <c>Pid</c> or the module <c>Module</c> belongs. Providing no
+          argument is the same as calling
+          <c>get_application(self())</c>.</p>
+        <p>If the specified process does not belong to any application,
+          or if the specified process or module does not exist,
+          the function returns <c>undefined</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>get_env(Par) -> {ok, Val} | undefined</name>
+      <name>get_env(Application, Par) -> {ok, Val} | undefined</name>
+      <fsummary>Get the value of a configuration parameter</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Par = atom()</v>
+        <v>Val = term()</v>
+      </type>
+      <desc>
+        <p>Returns the value of the configuration parameter <c>Par</c>
+          for <c>Application</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>
+      </desc>
+    </func>
+    <func>
+      <name>get_key(Key) -> {ok, Val} | undefined</name>
+      <name>get_key(Application, Key) -> {ok, Val} | undefined</name>
+      <fsummary>Get the value of an application specification key</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Key = atom()</v>
+        <v>Val = term()</v>
+      </type>
+      <desc>
+        <p>Returns the value of the application specification key
+          <c>Key</c> for <c>Application</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>
+      </desc>
+    </func>
+    <func>
+      <name>load(AppDescr) -> ok | {error, Reason}</name>
+      <name>load(AppDescr, Distributed) -> ok | {error, Reason}</name>
+      <fsummary>Load an application</fsummary>
+      <type>
+        <v>AppDescr = Application | AppSpec</v>
+        <v>&nbsp;Application = atom()</v>
+        <v>&nbsp;AppSpec = {application,Application,AppSpecKeys}</v>
+        <v>&nbsp;&nbsp;AppSpec = [{Key,Val}]</v>
+        <v>&nbsp;&nbsp;&nbsp;Key = atom()</v>
+        <v>&nbsp;&nbsp;&nbsp;Val = term()</v>
+        <v>Distributed = {Application,Nodes} | {Application,Time,Nodes} | default</v>
+        <v>&nbsp;Nodes = [node() | {node(),..,node()}]</v>
+        <v>&nbsp;Time = integer() > 0</v>
+        <v>Reason = term()</v>
+      </type>
+      <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>Application</c>.
+          In this case the application controller will search the code
+          path for the application resource file <c>Application.app</c>
+          and load the specification it contains.</p>
+        <p>The application specification can also be given directly as a
+          tuple <c>AppSpec</c>. This tuple should have the format and
+          contents as described in <c>app(4)</c>.</p>
+        <p>If <c>Distributed == {Application,[Time,]Nodes}</c>,
+          the application will be distributed. The argument overrides
+          the value for the application in the Kernel configuration
+          parameter <c>distributed</c>. <c>Application</c> must be
+          the name of the application (same as in the first argument).
+          If a node crashes and <c>Time</c> has been specified, then
+          the application controller will wait for <c>Time</c>
+          milliseconds before attempting to restart the application on
+          another node. If <c>Time</c> is not specified, it will
+          default to 0 and the application will be restarted
+          immediately.</p>
+        <p><c>Nodes</c> is a list of node names where the application
+          may run, in priority from left to right. Node names can be
+          grouped using tuples to indicate that they have the same
+          priority. Example:</p>
+        <code type="none">
+Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code>
+        <p>This means that the application should preferably 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>
+          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>
+      </desc>
+    </func>
+    <func>
+      <name>loaded_applications() -> [{Application, Description, Vsn}]</name>
+      <fsummary>Get the currently loaded applications</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Description = string()</v>
+        <v>Vsn = string()</v>
+      </type>
+      <desc>
+        <p>Returns a list with information about the applications which
+          have been loaded using <c>load/1,2</c>, also included
+          applications. <c>Application</c> is the application name.
+          <c>Description</c> and <c>Vsn</c> are the values of its
+          <c>description</c> and <c>vsn</c> application specification
+          keys, respectively.</p>
+      </desc>
+    </func>
+    <func>
+      <name>permit(Application, Bool) -> ok | {error, Reason}</name>
+      <fsummary>Change an application's permission to run on a node.</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Bool = bool()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Changes the permission for <c>Application</c> to run at
+          the current node. The application must have been 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
+          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
+          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>
+        <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>
+        <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>
+      </desc>
+    </func>
+    <func>
+      <name>set_env(Application, Par, Val) -> ok</name>
+      <name>set_env(Application, Par, Val, Timeout) -> ok</name>
+      <fsummary>Set the value of a configuration parameter</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Par = atom()</v>
+        <v>Val = term()</v>
+        <v>Timeout = int() | infinity</v>
+      </type>
+      <desc>
+        <p>Sets the value of the configuration parameter <c>Par</c> for
+          <c>Application</c>.</p>
+        <p><c>set_env/3</c> uses the standard <c>gen_server</c> timeout
+          value (5000 ms). A <c>Timeout</c> argument can be provided
+          if another timeout value is useful, for example, in situations
+          where the application controller is heavily loaded.</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>
+        </warning>
+      </desc>
+    </func>
+    <func>
+      <name>start(Application) -> ok | {error, Reason}</name>
+      <name>start(Application, Type) -> ok | {error, Reason}</name>
+      <fsummary>Load and start an application</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Type = permanent | transient | temporary</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Starts <c>Application</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
+          taken care of in the code for <c>Application</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,
+          <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
+          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>Type</c> argument 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>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
+          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
+          <c>shutdown</c>, not <c>normal</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>start_type() -> StartType | local | undefined</name>
+      <fsummary>Get the start type of an ongoing application startup.</fsummary>
+      <type>
+        <v>StartType = normal | {takeover,Node} | {failover,Node}</v>
+        <v>&nbsp;Node = node()</v>
+      </type>
+      <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>StartType</c> or
+          <c>local</c>.</p>
+        <p>See <c>Module:start/2</c> for a description of
+          <c>StartType</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
+          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>
+      </desc>
+    </func>
+    <func>
+      <name>stop(Application) -> ok | {error, Reason}</name>
+      <fsummary>Stop an application</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Stops <c>Application</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
+          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.
+          processes spawned from a process belonging to the application,
+          thus are terminated as well.</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,
+          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
+          the node where the application currently executes before
+          <c>stop/1</c> is called on the other nodes.</p>
+      </desc>
+    </func>
+    <func>
+      <name>takeover(Application, Type) -> ok | {error, Reason}</name>
+      <fsummary>Take over a distributed application</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Type = permanent | transient | temporary</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Performs a takeover of the distributed application
+          <c>Application</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
+          <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
+          must remain alive.</p>
+        <p>See <c>start/1,2</c> for a description of <c>Type</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>unload(Application) -> ok | {error, Reason}</name>
+      <fsummary>Unload an application</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Unloads the application specification for <c>Application</c>
+          from the application controller. It will also unload
+          the application specifications for any included applications.
+          Note that the function does not purge the actual Erlang
+          object code.</p>
+      </desc>
+    </func>
+    <func>
+      <name>unset_env(Application, Par) -> ok</name>
+      <name>unset_env(Application, Par, Timeout) -> ok</name>
+      <fsummary>Unset the value of a configuration parameter</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Par = atom()</v>
+        <v>Timeout = int() | infinity</v>
+      </type>
+      <desc>
+        <p>Removes the configuration parameter <c>Par</c> and its value
+          for <c>Application</c>.</p>
+        <p><c>unset_env/2</c> uses the standard <c>gen_server</c>
+          timeout value (5000 ms). A <c>Timeout</c> argument can be
+          provided if another timeout value is useful, for example, in
+          situations where the application controller is heavily loaded.</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>
+        </warning>
+      </desc>
+    </func>
+    <func>
+      <name>which_applications() -> [{Application, Description, Vsn}]</name>
+      <name>which_applications(Timeout) -> [{Application, Description, Vsn}]</name>
+      <fsummary>Get the currently running applications</fsummary>
+      <type>
+        <v>Application = atom()</v>
+        <v>Description = string()</v>
+        <v>Vsn = string()</v>
+        <v>Timeout = int() | infinity</v>
+      </type>
+      <desc>
+        <p>Returns a list with information about the applications which
+          are currently running. <c>Application</c> is the application
+          name. <c>Description</c> and <c>Vsn</c> are the values of its
+          <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>Timeout</c>
+          argument can be provided if another timeout value is useful,
+          for example, in situations where the application controller
+          is heavily loaded.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>CALLBACK MODULE</title>
+    <p>The following functions should 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>
+      <type>
+        <v>StartType = normal | {takeover,Node} | {failover,Node}</v>
+        <v>&nbsp;Node = node()</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
+          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><c>StartType</c> defines the type of start:</p>
+        <list type="bulleted">
+          <item><c>normal</c> if its 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
+           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
+           takeover from <c>Node</c>, either because
+          <c>application: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
+           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
+          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>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>
+      <type>
+        <v>Phase = atom()</v>
+        <v>StartType = normal | {takeover,Node} | {failover,Node}</v>
+        <v>&nbsp;Node = node()</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
+          processes in the different applications during startup.</p>
+        <p>The start phases is 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>
+      </desc>
+    </func>
+    <func>
+      <name>Module:prep_stop(State) -> NewState</name>
+      <fsummary>Prepare an application for termination</fsummary>
+      <type>
+        <v>State = NewState = term()</v>
+      </type>
+      <desc>
+        <p>This function is called when an application is about to be
+          stopped, before shutting down the processes of
+          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>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>
+      </desc>
+    </func>
+    <func>
+      <name>Module:stop(State)</name>
+      <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
+          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>
+      </desc>
+    </func>
+    <func>
+      <name>Module:config_change(Changed, New, Removed) -> ok</name>
+      <fsummary>Update the configuration parameters for an application.</fsummary>
+      <type>
+        <v>Changed = [{Par,Val}]</v>
+        <v>New = [{Par,Val}]</v>
+        <v>Removed = [Par]</v>
+        <v>&nbsp;Par = atom()</v>
+        <v>&nbsp;Val = term()</v>
+      </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>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <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>
+  </section>
+</erlref>
+