application

MODULE

application

MODULE SUMMARY

Functions for controlling applications

DESCRIPTION

This module contains functions for controlling applications (eg. starting and stopping applications), and functions to access information about any application, (eg. configuration parameters)

All applications are started by the application_controller process. Each application has an application_master process. This process monitors the application and reports to the application controller if the application terminates.

An application can be started locally or distributed. A distributed application is started on one of several nodes while a local application is always started on the current node.

The local applications are controlled by the application controller. The distributed applications are controlled by another process, called the distributed application controller (dist_ac). The distributed application controller on different nodes monitor each other. Therefore, if a node goes down, the distributed applications on that node will be automatically re-started on one of the remaining nodes.

The distributed application controller is not started by default. Systems that use distributed applications must set the configuration parameter start_dist_ac in kernel.

EXPORTS

get_all_env()
get_all_env(Application) -> Env

Types:
Application = atom()
Env = [{Key, Value}]
Key = atom()
Value = term()

Retrieves the values of the application's configuration parameters. If Application is not specified, then the configuration parameters for the application which executes the call are returned.

get_all_key()
get_all_key(Application) -> {ok, Keys} | undefined

Types:
Application = atom()
Keys = [{Key, Value}]
Key = atom()
Value = term()

Retrieves all the keys from the application's resource file, Application.app. If Application is not specified, then the keys for the application which executes the call are returned.

get_application()
get_application(Pid | Module) -> {ok, Application} | undefined

Types:
Pid = pid()
Module = atom()
Application = atom()

Retrieves the name of the application where the process Pid executes. If Pid is not specified, self() is used. If an atom is given the name of the application which contains the module will be returned, or undefined.

get_env(Key)
get_env(Application, Key) -> {ok, Value} | undefined

Types:
Application = atom()
Key = atom()
Value = term()

Retrieves the value of an application's configuration parameter. If Application is not specified, the parameter for the application which executes the call is retrieved.

get_key(Key)
get_key(Application, Key) -> {ok, Value} | undefined

Types:
Application = atom()
Key = atom()
Value = term()

Retrieves the key from the application's resource file, Application.app. If Application is not specified, then the key for the application which executes the call is returned.

If Key is a valid key (see app(4)) for which no value is defined, {ok, undefined} is return. If Key is not a valid key, undefined is always returned.

load(Application)
load(Application, DistNodes) -> ok | {error, Reason}

Types:
Application = atom() | appl_descr()
DistNodes = {Name, Nodes} | {Name, Time, Nodes} | default
appl_descr() = {application, Name, [appl_opt()]}
Name = atom()
Time = integer() > 0
Nodes = [node() | {node(), ..., node()}]
appl_opt() = {description, string()} | {vsn, vsn()} | {modules, [{atom(), vsn()}]} | {registered, [atom()]} | {applications, [atom()]} | {env, [{atom(), term()}]} |{mod, {Mod, StartArgs}}
vsn() = string()

If the name of the application is given, the application controller searches the current path (the same as the code path) for a file called Application.app.
Note: This file must contain the appl_descr() (written in plain text, with a dot and space after the term).

description and version - Contains information about an application that can be retrieved by calling application:loaded_applications/0.

modules - Lists the modules that this application introduces.

registered is a list of the registered names that this application uses for its own processes.

applications - Lists of other applications that must be started before this one.

env is a list of configuration parameters. Note: The definitions in this list may be altered by definitions in the system configuration file, specified by the command line argument -config. They can also be altered directly from the command line, by giving -Name Par Value.

mod is the application call back module. Mod:start(StartType, StartArgs) is called when the application is started. Refer to the call back function start/2.

The DistNodes parameter will override the value of the application in the Kernel configuration parameter distributed. The data structure specifies a list of nodes where the application Name may execute. If the nodes are specified in a tuple, the order of where to start the application will be undefined. If a node crashes and Time has been specified, then the application controller will wait for Time milliseconds before attempting to restart the application on another node. If Time is not specified, it will default to 0. If a node goes down, the application will be restarted immediately on another node. If DistNodes is default, the value in the configuration parameter distributed will be used.

loaded_applications() -> [{Name, Description, Version}]

Types:
Name = atom()
Description = string()
Version = string()

This function returns a list of applications which are loaded in the system. Description and Version are as defined in the application specification.

permit(Application, Bool) -> ok | {error, Reason}

Types:
Name = atom()
Bool = bool()

This function changes an application's permission to run on the node, or vice versa. If the permission of a locally running application is set to false, the application will be stopped. When the permission is set to true, the local application will be started. If the permission of a running, distributed application is set to false, the application will be moved to another node where it may run, if a node is available.

The application must be loaded before the permit function can be called.

This function does not return until the application is either started, stopped or successfully moved to another node. However, in some cases where permission is set to true the function may return ok even though the application itself has not started. This is true when an application cannot start because it has dependencies on applications which have not yet been started. When these applications are started the dependent application will also be started.

By default, all applications are loaded with permission true on all nodes. The permission is configurable with the parameter permissions in kernel.

start(Application)
start(Application, Type) -> ok | {error, Reason}

Types:
Application = atom()
Type = permanent | transient | temporary

This function starts and application. If the application is not loaded, the application controller will first try to load it, as if application:load(Application) was called.

The Type specifies what happens if the application dies.

• If a permanent application dies, all other applications are also terminated.


• If a transient application dies normally, this is reported and no other applications are terminated. If a transient application dies abnormally, all other applications are also terminated.


• If a temporary application dies this is reported and no other applications are terminated. In this way, an application can run in test mode, without disturbing the other applications.



Default value for Type is temporary.

start_type() -> normal | local | {takeover, node()} | {failover, node()}

This function returns the type of application start which is executing.

normal is returned when an application is starting and the below circumstances have not occurred.

local is returned if a supervised process restarts due to abnormal exit or if no start is running at the time of request.

{takeover, Node} is returned if the application is requested to move to another node either due to a call to takeover/2 or when a node with higher priority to run the application is restarted.

{failover, Node} is returned if the application is restarted due to the Node crashing where the application was previously executing.

stop(Application) -> ok

Types:
Application = atom()

This function stops a running application. If the application was distributed, no other node will restart it. All processes in the application tree are terminated, and also all processes with the same group leader as the application.

takeover(Application, Type) -> {ok, Pid} | {error, Reason}

Types:
Application = atom()
Type = permanent | transient | temporary

This function moves a distributed application which executes on another node Node to the current node. The application is started by calling Mod:start({takeover, Node}, StartArgs) before the application is stopped on the other node. This makes it possible to transfer application specific data from a currently running application to a new node. When the application start function returns, the application on a Node is stopped. This means that two instances of the application may be running on two different nodes at one time. If this is not acceptable, parts of the application on the old node (Node) may be shut down when the new node starts the application. Note: that the old application must not be stopped entirely (i.e. application:stop/1 must not be called on the old node). The main supervisor, must still be alive.

which_applications() -> [{Name, Description, Version}]

Types:
Name = atom()
Description = string()
Version = string()

Returns a list of the applications which are running in the system. Description and Version are as defined in the application specification.

Call back Module

The following functions are exported from an application call back module.

EXPORTS

Module:config_change(Changed, New, Removed) -> ok

Types:
Changed = [{Parameter, NewValue}]
New = [{Parameter, Value}]
Removed = [Parameter]
Parameter = atom()
NewValue = term()
Value = term()

After an installation of a new release all started applications on a node are notified of the changed, new and removed configuration parameters. The unchanged configuration parameters are not affected and therefore the function is not evaluated for applications which have unchanged configuration parameters between the old and new releases.

Module:start(Type, ModuleStartArgs) -> {ok, Pid} | {ok, Pid, State} | {error, Reason}

Types:
Type = normal | {takeover, node()} | {failover, node()}
ModuleStartArgs = term()
Pid = pid()
State = state()

This function starts a primary application. Normally, this function starts the main supervisor of the primary application.

If Type is {takeover, Node}, it is a distributed application which is running on the Node. If the application does not have the start-phases key defined in the application's resource file, the application will be stopped by the application controller after this call returns (see start-phase/3) This makes it possible to transfer the internal state from the running application to the one to be started. This function must not stop the application on Node, but it may shut down parts of it. For example, instead of stopping the application, the main supervisor may terminate all its children.

If Type is {failover, Node}, the application will be restarted due to a crash of the node where the application was previously executing.
{failover, node()} is valid only if the start_phases key is defined in the applications resource file. Otherwise the type is set to normal at failover.

The ModuleStartArgs parameter is specified in the application resource file (.app), as {mod, {Module, ModuleStartArgs}}.

State is any term. It is passed to Module:prep_stop/1. If no State is returned, [] is used.

Module:start_phase(Phase, Type, PhaseStartArgs) -> ok | {error, Reason}

Types:
Phase = atom()
Type = normal | {takeover, node()} | {failover, node()}
PhaseStartArgs = term()
Pid = pid()
State = state()

This function starts a application in the phase Phase. It is called by default only for a primary application and not for the included applications, refer to User's Guide chapter 'Design Principles' regarding incorporating included applications.

The PhaseStartArgs parameter is specified in the application's resource file (.app), as {start_phases, [{Phase, PhaseStartArgs}]}, the Module as {mod, {Module, ModuleStartArgs}}.

This call back function is only valid for applications with a defined start_phases key. This function will be called once per Phase.

If Type is {takeover, Node}, it is a distributed application which runs on the Node. When this call returns for the last start phase, the application on Node will be stopped by the application controller. This makes it possible to transfer the internal state from the running application. When designing the start phase function it is imperative that the application is not allowed to terminate the application on node. However, it possible to partially shut it down for eg. the main supervisor may terminate all the application's children.

If Type is {failover, Node}, due to a crash of the node where the application was previously executing, the application will restart.

Module:prep_stop(State) -> NewState

Types:
State = state()
NewState = state()

See Module:stop/1. This function is called when the application is about to be stopped, before shutting down the processes of the application.

State is the state that was returned from Mod:start/2, or [] if no state was returned. NewState will be passed to Module:stop/1.

If Module:prep_stop/1 isn't defined, NewState will be identical to State.

Module:stop(State) -> void()

Types:
State = state()

This function is called when the application has stopped, either because it crashed, or because someone called application:stop. It cleans up after the Module:start/2 function.

Before Mod:stop/1 is called, Mod:prep_stop/1 will have been called. State is the state that was returned from Mod:prep_stop/1.

See Also

kernel(3)

AUTHORS

Martin Björklund - support@erlang.ericsson.se
Esko Vierumäki - support@erlang.ericsson.se