应用 | application

模

应用

模块摘要

通用OTP应用程序功能

描述

在OTP中，应用程序表示实现某些特定功能的组件，可以作为一个单元启动和停止，并且可以在其他系统中重用。该模块与应用程序控制器交互，每个Erlang运行时系统都启动一个进程。此模块包含用于控制应用程序（例如，启动和停止应用程序）的函数以及用于访问应用程序信息（例如配置参数）的函数。

应用程序由应用程序规范定义。规范通常位于名为的应用程序资源文件中Application.app，其中Application是应用程序名称。有关应用程序规范的详细信息，请参阅app(4)。

根据OTP设计原则，该模块也可以视为一种应用程序的行为，作为监督树。如何启动和停止树的定义位于应用程序回调模块中，导出一组预定义的函数。

有关应用程序和行为的详情，请参阅OTP Design Principles。

数据类型

start_type() =

    normal |

    {takeover, Node :: node()} |

    {failover, Node :: node()}

restart_type() = permanent | transient | temporary

tuple_of(T)

元素是类型的元组T。

出口

ensure_all_started(Application) -> {ok, Started} | {error, Reason}

ensure_all_started(Application, Type) ->

{ok, Started} | {error, Reason}

类型

相当于对start/1,2应用程序尚未启动的所有依赖关系重复调用。

返回{ok, AppNames}成功启动或已启动的应用程序（但是，从AppNames列表中省略）。

该函数报告{error, {AppName,Reason}}错误，其中Reason是start/1,2启动特定依赖关系时返回的任何可能的原因。

如果发生错误，则停止由该函数启动的应用程序，以使正在运行的应用程序回到其初始状态。

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

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

类型

等同于start/1,2除ok已为已启动的应用程序返回外。

get_all_env() -> Env

get_all_env(Application) -> Env

类型

返回配置参数及其值Application。如果参数被忽略，它将默认为调用进程的应用程序。

如果指定的应用程序未加载，或者执行调用的进程不属于任何应用程序，则该函数返回[]。

get_all_key() -> [] | {ok, Keys}

get_all_key(Application) -> undefined | Keys

类型

返回应用程序规范键及其值Application。如果参数被忽略，它将默认为调用进程的应用程序。

如果指定的应用程序未加载，则函数返回undefined。如果执行调用的进程不属于任何应用程序，则该函数返回[]。

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

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

类型

返回进程Pid或模块Module所属的应用程序的名称。不提供参数与调用相同get_application(self())。

如果指定的进程不属于任何应用程序，或者指定的进程或模块不存在，则函数返回undefined。

get_env(Par) -> undefined | {ok, Val}

get_env(Application, Par) -> undefined | {ok, Val}

类型

返回配置参数的值Par的Application。如果应用程序参数被忽略，它将默认为调用进程的应用程序。

undefined如果有以下任何一种情况，则返回：

• 指定的应用程序未加载。
• 配置参数不存在。
• 执行呼叫的进程不属于任何应用程序。

get_env(Application, Par, Def) -> Val

类型

像配置参数不存在时get_env/2返回值那样工作。DefPar

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

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

类型

返回应用规范键值Key对Application。如果应用程序参数被忽略，它将默认为调用进程的应用程序。

如果有以下任何一种情况，则返回：undefined

• 指定的应用程序未加载。
• 规范键不存在。
• 执行呼叫的进程不属于任何应用程序。

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

load(AppDescr, Distributed) -> ok | {error, Reason}

类型

将应用程序的应用程序规范加载到应用程序控制器中。它还加载任何包含的应用程序的应用程序规范。请注意，该函数不会加载Erlang对象代码。

应用程序可以通过其名称来指定Application。在这种情况下，应用程序控制器将搜索应用程序资源文件的代码路径Application.app并加载其包含的规范。

应用程序规范也可以直接指定为一个元组AppSpec，其格式和内容如下所述app(4)。

如果Distributed == {Application,[Time,]Nodes}，应用程序变得分发。该参数在内核配置参数中覆盖该应用程序的值distributed。Application必须是应用程序名称（与第一个参数相同）。如果节点崩溃并被Time指定，则应用程序控制器会等待Time几毫秒，然后再尝试在另一个节点上重新启动应用程序。如果Time未指定，则默认为0，并且应用程序立即重新启动。

Nodes是应用程序可以运行的节点名称列表，优先级从左到右。节点名称可以使用元组分组来表明它们具有相同的优先级。

例：

Nodes = [cp1@cave, {cp2@cave, cp3@cave}]

这意味着应用程序最好是从cp1@cave。如果发生cp1@cave故障，应用程序将在cp2@cave或开始cp3@cave。

如果使用Distributed == default内核配置参数中的应用程序的值distributed。

loaded_applications() -> {Application, Description, Vsn}

类型

返回列表，其中包含有关应用程序的信息以及使用的加载应用程序load/1,2。Application是应用程序名称。Description并Vsn分别是它们description和vsn应用程序规范键的值。

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

类型

更改Application在当前节点上运行的权限。应用程序必须加载使用load/1,2的功能有效。

如果已加载但未启动的应用程序的权限设置为false，则start返回，ok但应用程序在权限设置为之前不会启动true。

如果正在运行的应用程序的权限设置为false，应用程序将停止。如果稍后权限设置为true，则重新启动。

如果应用程序已分发，则将权限设置为false意味着应用程序将根据其分发的配置方式在另一个节点上启动或移动到另一个节点（请参阅参考资料load/2）。

直到应用程序启动，停止或成功移动到另一个节点时，函数才会返回。但是，在权限设置为的某些情况下，即使应用程序未启动true，函数ok也会返回。当应用程序由于依赖于其他尚未启动的应用程序而无法启动时，情况就是如此。当他们开始时，Application也开始。

默认情况下，所有应用程序都true在所有节点上加载权限。该权限可以使用内核配置参数进行配置permissions。

set_env(Application, Par, Val) -> ok

set_env(Application, Par, Val, Opts) -> ok

类型

设置配置参数的值Par的Application。

set_env/4使用标准gen_server的超时值（5000毫秒）。timeout如果另一个超时值有用，例如在应用程序控制器负载过重的情况下，可以指定选项。

如果set_env/4在应用程序加载之前调用，则文件中指定的应用程序环境值Application.app会覆盖先前设置的应用程序环境值。这对于应用程序重新加载也是如此。

选项persistent可以设置为true保证设置的参数set_env/4不会被加载时应用程序资源文件中定义的参数覆盖。这意味着在加载应用程序以及应用程序重新加载之后，持久值将保持不变。

警告

只有在您知道自己在做什么时才使用此功能，即在您自己的应用程序上。这是非常依赖于应用程序和配置参数的时间和应用程序读取值的频率。不小心使用此功能可能会使应用程序处于奇怪，不一致和故障状态。

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

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

类型

开始Application。如果未加载，则应用程序控制器首先使用它加载它load/1。它确保所有包含的应用程序都已加载，但不会启动它们。这被假定在代码中负责Application。

应用程序控制器检查应用程序规范密钥的值applications，以确保在此应用程序运行之前需要启动所有应用程序。否则，{error,{not_started,App}}返回，App缺失应用程序的名称在哪里。

应用程序控制器然后为应用程序创建一个应用程序主控。应用程序主数据是应用程序中所有进程的组长。应用程序主机通过调用Module:start/2由应用程序规范键定义的应用程序回调函数来启动应用程序mod。

参数Type指定应用程序的类型。如果省略，则默认为temporary。

• 如果永久应用程序终止，则所有其他应用程序和整个Erlang节点也终止。
  • 如果临时应用程序终止Reason == normal，则会报告此事件，但不会终止其他应用程序。
  • 如果临时应用程序异常终止，则所有其他应用程序和整个Erlang节点也会终止。
• 如果临时应用程序终止，则会报告此事件，但不会终止其他应用程序。

请注意，应用程序始终可以通过调用明确停止stop/1。无论应用程序的类型如何，都不会影响其他应用程序。

还要注意，暂态类型几乎没有实际用途，因为当监督树终止时，原因被设置为shutdown，而不是normal。

start_type() -> StartType | undefined | local

类型

当应用程序启动时，此函数旨在由属于应用程序的进程调用，以确定启动类型，它是StartType或local。

有关说明StartType，请参阅Module:start/2。

local 如果只有部分应用程序重新启动（由主管），或者如果该功能在启动时被调用，则返回。

如果执行调用的进程不属于任何应用程序，则该函数返回undefined。

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

类型

停止Application。应用程序主调用Module:prep_stop/1，如果定义了这样的功能，然后通知应用程序的最高管理者关闭（请参阅参考资料supervisor(3)）。这意味着整个监督树（包括包含的应用程序）以反向启动顺序终止。关机后，应用程序主设备调用Module:stop/1。Module是由应用程序规范键定义的回调模块mod。

最后，应用程序主机终止。请注意，应用程序主机作为组长的所有进程，即属于应用程序的进程产生的进程也会终止。

停止时，应用程序仍然被加载。

要停止分布式应用程序，stop/1必须在其可以执行的所有节点上（即，在其所有已启动节点上）调用。stop/1在应用程序当前执行的节点上调用将停止执行。应用程序不在节点之间移动，就像在其他节点上调用stop/1应用程序当前执行的节点上所stop/1调用的那样。

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

类型

接管Application在另一个节点上执行的分布式应用程序Node。在当前节点，应用程序通过调用重新启动Module:start({takeover,Node},StartArgs)。Module并StartArgs从加载的应用程序规范中检索。在其他节点的应用程序不会停止，直到启动完成，即何时Module:start/2和任何呼叫Module:start_phase/3已返回。

因此，在接管过程中应用程序的两个实例同时运行，以便可以将数据从旧传输到新实例。如果这不是一个可以接受的行为，则可以在新实例启动时关闭旧实例的某些部分。然而，申请不能完全停止，至少最高主管必须保持活力。

有关说明Type，请参阅start/1,2。

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

类型

Application从应用程序控制器卸载应用程序规范。它还卸载任何包含的应用程序的应用程序规范。请注意，该函数不会清除Erlang对象代码。

unset_env(Application, Par) -> ok

unset_env(Application, Par, Opts) -> ok

类型

删除配置参数Par及其值Application。

unset_env/2使用标准gen_server的超时值（5000毫秒）。timeout如果另一个超时值有用，例如在应用程序控制器负载过重的情况下，可以指定选项。

unset_env/3还允许传递持久选项（请参阅参考资料set_env/4）。

警告

只有在您知道自己在做什么时才使用此功能，即在您自己的应用程序上。这是非常依赖于应用程序和配置参数的时间和应用程序读取值的频率。不小心使用此功能可能会使应用程序处于奇怪，不一致和故障状态。

which_applications() -> {Application, Description, Vsn}

which_applications(Timeout) -> {Application, Description, Vsn}

类型

返回包含当前正在运行的应用程序的信息的列表。Application是应用程序名称。Description并Vsn分别是它们description和vsn应用程序规范键的值。

which_applications/0使用标准gen_server的超时值（5000毫秒）。甲Timeout如果另一个超时值是有用的，例如，在应用控制器负载过重的情况下的参数可以被指定。

回叫模块

以下函数将从application回调模块中导出。

出口

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

类型

这个函数在应用程序开始使用时被调用start/1,2，并且启动应用程序的进程。如果应用程序根据OTP设计原则构建为监督树，则意味着启动树的最高管理者。

StartType 定义启动的类型：

• normal 如果这是一个正常的启动。
• normal同样，如果应用程序由于来自另一个节点的故障转移而在当前节点上分发和启动，以及应用程序规范密钥start_phases == undefined。
• {takeover,Node}如果应用程序是由于接管来自当前节点而分发和启动的Node，则可能是因为takeover/2已被调用，或者因为当前节点的优先级高于Node。
• {failover,Node}如果应用程序由于故障转移而从当前节点分发和启动Node，并且应用程序规范密钥start_phases /= undefined。

StartArgs是StartArgs由应用程序规范键定义的参数mod。

该职能是返回{ok,Pid}或{ok,Pid,State}，Pid最高管理者的pid 在哪里，并且State是任何任期。如果省略，则State默认为[]。如果应用程序稍后停止，State则传递给Module:prep_stop/1。

Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}

类型

在启动期间需要在不同应用程序中的进程之间进行同步时，启动包含应用程序的应用程序。

开始阶段由应用程序规范键定义start_phases == [{Phase,PhaseArgs}]。对于包含的应用程序，阶段集合必须是为包含应用程序定义的阶段集的子集。

该函数针对主应用程序的每个启动阶段（为主应用程序定义）和所有包含的应用程序（为其定义启动阶段）调用。

有关说明StartType，请参阅Module:start/2。

Module:prep_stop(State) -> NewState

类型

在关闭应用程序的进程之前，即将停止应用程序时调用此函数。

State是返回的国家Module:start/2，还是[]没有返回国家。NewState是任何术语，并传递给Module:stop/1。

该功能是可选的。如果未定义，则进程终止并被Module:stop(State)调用。

Module:stop(State)

类型

这个函数在应用程序停止时调用。它的目的Module:start/2是做和任何必要的清理相反的工作。返回值被忽略。

State是Module:prep_stop/1如果存在这样的函数的返回值。否则State取自返回值Module:start/2。

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

类型

如果配置参数已更改，则该代码将在代码更换后由应用程序调用。

Changed 是参数值元组的列表，包括所有具有更改值的配置参数。

New 是包含所有添加的配置参数的参数值元组列表。

Removed 是所有移除参数的列表。