sys

模块

sys

模块摘要

系统消息的功能接口。

描述

该模块包含用于发送程序使用的系统消息的功能，以及用于调试目的的消息。

预计用于执行进程的函数还可以理解系统消息，例如调试消息和代码更改。这些功能必须用于实现一个进程的系统消息的使用; 无论是直接的，还是通过标准的行为，比如gen_server。

除非另有说明，默认超时值为5000毫秒。 超时定义了等待进程响应请求的时间。 如果进程没有响应，则函数评估退出（{timeout，{M，F，A}}）。

函数引用调试结构。调试结构是dbg_opt()，它是函数使用的内部数据类型。handle_system_msg/6如果是空列表，则不执行调试。

系统消息

没有被实现为标准行为之一的进程仍然必须理解系统消息。必须理解以下三条消息：

• 普通系统消息。这些被收到{system, From, Msg}。该消息的内容和含义不被接收处理模块解释。当收到系统消息时，调用函数handle_system_msg/6来处理请求。

• 关闭消息。如果进程陷阱退出，它必须能够处理来自其父母 - 主管的关闭请求。{'EXIT', Parent, Reason}来自父母的消息是终止的命令。接收到该消息时，通常用相同的过程必须终止Reason如Parent。

• 如果用于实现流程的模块在运行时动态更改，则流程必须再理解一条消息。gen_event过程就是一个例子。消息是{_Label, {From, Ref}, get_modules}。对此消息的回复是From ! {Ref, Modules}，Modules该进程中当前活动模块的列表在哪里。释放处理程序使用此消息来查找执行某个模块的哪些进程。该进程稍后可能被挂起并命令为其模块之一执行代码更改。系统事件当使用此模块的功能调试进程时，进程会生成system_events，然后在调试功能中对其进行处理。例如，trace将系统事件格式化到终端。当进程接收或发送消息时使用三个预定义的系统事件。该过程还可以定义自己的系统事件。数据类型name() = pid() | atom() | {global, atom()} system_event() = {in, Msg :: term()} | {in, Msg :: term(), From :: term()} | {out, Msg :: term(), To :: term()} | term() dbg_opt()请参阅本手册页的介绍。dbg_fun() = fun((FuncState :: term(), Event :: system_event(), ProcState :: term()) -> done | (NewFuncState :: term())) format_fun() = fun((Device :: io:device() | file:io_device(), Event :: system_event(), Extra :: term()) -> any())Exportschange_code（Name，Module，OldVsn，Extra） - > ok | {error，Reason} change_code（Name，Module，OldVsn，Extra，Timeout） - > ok | {error，Reason} TypesTells更改代码的过程。该进程必须暂停以处理此消息。争论Extra是保留给每个进程使用作为自己的。函数Module:system_code_change/4被调用。OldVsn是旧版本的Module.get_state（Name） - > Stateget_state（Name，Timeout） - > StateTypes获取进程的状态。注意这些函数仅用于帮助进行调试。它们是为了方便而提供的，允许开发人员避免必须创建它们自己的状态提取功能，并且也避免必须从调试的返回值get_status/1或get_status/2调试时交互地提取状态。State对于不同类型的过程，值如下所示：

• 为了gen_server进程，返回的State回调模块的状态。

• 对于一个gen_statem进程，State是元组{CurrentState,CurrentData}。

• 对于一个gen_event进程，State是一个元组列表，其中每个元组对应于在进程中注册的一个事件处理程序并包含{Module, Id, HandlerState}如下：

Module事件处理程序的模块名。

Id处理程序的ID（如果它没有ID注册，则为false）。

HandlerState处理程序的状态。

如果回调模块导出一个函数system_get_state/1，它将在目标进程中调用以获取其状态。它的参数与Misc返回的值相同get_status/1,2，并且函数Module:system_get_state/1有望从中提取回调模块的状态。函数system_get_state/1必须返回{ok, State}，State回调模块的状态所在的位置。

如果回调模块没有导出system_get_state/1职能，get_state/1,2假设Misc值是回调模块的状态，并直接返回它。

如果回调模块的system_get_state/1函数崩溃或抛出异常，则调用程序将退出并返回错误{callback_failed, {Module, system_get_state}, {Class, Reason}}，其中Module是回调模块的名称，Class与Reason指示异常的详细信息。

函数system_get_state/1主要用于用户定义的行为和实现OTP的模块special processes。的gen_server，gen_statem和gen_eventOTP行为模块这些行为不需要提供自己的导出这个功能，所以回调模块。

有关进程的更多信息（包括其状态），请参阅get_status/1和get_status/2。

get_status(Name) -> Status

get_status(Name, Timeout) -> Status

类型

获取进程的状态。

Misc不同类型的流程的价值会有所不同，例如：

• 一个gen_server进程返回回调模块的状态。

• 一个gen_statem处理返回的信息，如它的当前状态的名称和状态数据。

• gen_event处理返回信息关于它的每一个注册handlers.Callback模块gen_server，gen_statem以及gen_event还可以改变的值Misc通过导出的函数format_status/2，这有助于特定于模块的信息。

有关详细信息，请参阅gen_server:format_status/2，gen_statem:format_status/2和gen_event:format_status/2.

.install(Name, FuncSpec) -> okinstall(Name, FuncSpec, Timeout) -> okTypesEnables

安装替代调试功能。这种功能的一个例子是一个触发器，一个等待某个特殊事件并在事件产生时执行一些操作的函数。例如，打开低级跟踪。Func每当系统事件产生时被调用。这个函数是返回的done，还是一个新的Func州。在第一种情况下，该功能被删除。如果函数失败，它也会被删除.

log（Name，Flag） - > ok | {ok，[ system_event()]} log（名称，标志，超时） - > ok | {ok，[ system_event()]} Types

打开或关闭系统事件的日志记录。如果打开，N则调试结构中将保留最多的事件（默认值为10）。如果Flag是get，则会返回所有记录的事件的列表。如果Flag是print，则将记录的事件打印到standard_io该事件。事件格式化为函数由生成事件的进程定义（通过调用handle_debug/4).

log_to_file（名称，标志） - > ok | {error，open_file} log_to_file（名称，标志，超时） - > ok | {error，open_file}

类型启用或禁用以文本格式将所有系统事件记录到文件。事件使用由生成事件的进程（通过调用handle_debug/4）定义的函数进行格式化。该文件用编码UTF-8.

no_debug（Name） - > okno_debug（Name，Timeout） - > okTypes

打开关闭进程的所有调试。这包括使用函数显式安装的函数install/2,3，例如，triggers.remove（Name，Func） - > okremove（Name，Func，Timeout） - > okTypes

从进程中移除已安装的调试功能。Func必须与先前的installed.replace_state（Name，StateFun）相同 - > NewStatereplace_state（Name，StateFun，Timeout） - > NewStateTypes替换进程的状态，并返回新的状态。注意这些函数仅用于帮助调试，不能从正常的代码中调用。它们是为了方便而提供的，允许开发人员避免必须创建他们自己的定制状态替换函数。函数StateFun为该过程提供了一个新的状态。对于不同类型的流程，参数State和NewState返回值StateFun会有所不同，如下所示：

• 为了gen_server过程，State是回调模块的状态，并且NewState是那个状态的一个新实例。

• 对于一个gen_statem进程，State是元组{CurrentState,CurrentData}，并且NewState是一个类似的元组，它可以包含新的当前状态，新的状态数据或两者。

• 对于一个gen_event过程，State元组{Module, Id, HandlerState}如下所示：

Module事件处理程序的模块名。

Id处理程序的ID（如果它没有ID注册，则为false）。

HandlerState处理程序的状态。

NewState是一个类似的元组，其中Module和Id的值与State中的值相同，但HandlerState的值可能不同。 返回一个NewState，其Module或Id的值与State的值不同，会使事件处理程序的状态保持不变。 对于gen_event进程，为gen_event进程中注册的每个事件处理程序调用StateFun一次。

如果StateFun函数决定不影响进程状态的任何更改，然后不管进程类型如何，它都可以返回其State争论。

如果StateFun函数崩溃或抛出异常，则gen_server和gen_statem进程的原始进程状态不变。 对于gen_event进程，崩溃或失败的StateFun函数意味着只有当它失败或崩溃时正在处理的特定事件处理程序的状态不变; 它仍然可以成功更改在同一gen_event进程中注册的其他事件处理程序的状态。

如果回调模块导出system_replace_state / 2函数，则在目标进程中调用它以使用StateFun替换其状态。 它的两个参数是StateFun和Misc，其中Misc与get_status / 1,2返回的杂项值相同。 system_replace_state / 2函数预计会返回{ok，NewState，NewMisc}，其中NewState是通过调用StateFun获得的回调模块的新状态，NewMisc是一个可能用于替换原始Misc的新值（作为Misc需要 通常包含其中的回调模块的状态）。

如果回调模块没有导出system_replace_state/2函数，则replace_state/2,3假定Misc回调模块的状态，将它传递给StateFun并使用返回值作为新状态和新值Misc。

如果回调模块的函数system_replace_state/2崩溃或抛出异常，则调用程序将退出并返回错误{callback_failed, {Module, system_replace_state}, {Class, Reason}}，其中Module是回调模块的名称，Class并Reason指示异常的详细信息。如果回调模块没有提供system_replace_state/2函数并StateFun崩溃或抛出异常，则调用程序将退出并出错{callback_failed, StateFun, {Class, Reason}}。

函数system_replace_state/2主要用于用户定义的行为和实现OTP的模块special processes。OTP行为模块gen_server，gen_statem与gen_event导出这个函数，所以这些行为的回调模块不需要自己提供。

resume(Name) -> ok

resume(Name, Timeout) -> ok

类型

恢复暂停的进程。

statistics(Name, Flag) -> ok | {ok, Statistics}

statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}

类型

启用或禁用统计信息的收集。如果Flag是get，则返回统计集合。

suspend(Name) -> ok

suspend(Name, Timeout) -> ok

类型

暂停这个过程。当进程被挂起时，它只响应其他系统消息，而不响应其他消息。

terminate(Name, Reason) -> ok

terminate(Name, Reason, Timeout) -> ok

类型

命令进程以指定的Reason终止是异步完成的，因此不能保证在函数返回时进程被终止。

trace(Name, Flag) -> ok

trace(Name, Flag, Timeout) -> ok

类型

打印所有系统事件standard_io。事件使用由生成事件的进程（通过调用handle_debug/4）定义的函数进行格式化。

过程实现功能

在实现特殊过程时使用以下功能。这是一个普通的过程，它不使用标准行为，而是一个了解标准系统消息的过程。

输出

debug_options(Options) -> [dbg_opt()]

类型

可以被从选项列表中启动调试结构的进程使用。参数的值Opt与相应的函数相同。

get_debug(Item, Debug, Default) -> term()

类型

获取与调试选项关联的数据。 如果找不到Item，则返回缺省值。 进程可以使用该进程在终止之前检索用于打印的调试数据。

handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]

类型

此函数由进程在生成系统事件时调用。FormFunc是一个格式化函数，称为FormFunc(Device, Event, Extra)若要打印事件，在激活跟踪时，这是必要的。Extra是进程在格式函数中需要的任何额外信息，例如进程名称。

handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->

no_return()

类型

该功能由进程模块用来处理系统消息。该过程接收一个{system, From, Msg}消息，并将Msg与From给此函数。

这个函数不会返回。它调用以下任一功能：

• Module:system_continue(Parent, NDebug, Misc)，其中进程继续执行。

• Module:system_terminate(Reason, Parent, Debug, Misc)，如果进程要终止。

Module必须输出以下内容：

• system_continue/3

• system_terminate/4

• system_code_change/4

• system_get_state/1

• system_replace_state/2

参数Misc可用于保存进程中的内部数据，例如其状态。它被发送到Module:system_continue/3或Module:system_terminate/4。

print_log(Debug) -> ok

类型

在调试结构中打印记录的系统事件，按照FormFunc调用时生成的事件定义handle_debug/4。

Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}

类型

从handle_system_msg/6进程执行代码更改时调用。当内部数据结构发生变化时使用代码更改。该函数将参数转换Misc为新的数据结构。OldVsn是旧版本的属性vsnModule。如果没有定义这样的属性，undefined则发送原子。

Module:system_continue(Parent, Debug, Misc) -> none()

类型

从handle_system_msg/6进程继续执行时调用（例如，在暂停之后）。这个函数不会返回。

Module:system_get_state(Misc) -> {ok, State}

类型

当过程要返回反映其当前状态的术语时，从handle_system_msg / 6调用。 State是get_state / 2返回的值。

Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}

类型

当进程要替换当前状态时，从handle_system_msg / 6调用。 NState是replace_state / 3返回的值。

Module:system_terminate(Reason, Parent, Debug, Misc) -> none()

类型

从handle_system_msg/6进程终止时调用。例如，当进程挂起并且其父命令关闭时，将调用此函数。它为流程提供了一个清理的机会。这个函数不会返回。