Erlang模块gen_fsm翻译

模块摘要

    通用有限状态机行为。

 

描述

    用于实现有限状态机的行为模块。使用该模块实现的通用有限状态机进程（gen_fsm）将具有一组标准的接口函数，并包括用于跟踪和错误报告的功能。它也适用于OTP监督树。有关更多信息，请参阅OTP设计原则。

    gen_fsm假定所有特定部分都位于回调模块中，导出预定义的函数集。行为函数和回调函数之间的关系可以说明如下：

gen_fsm module Callback module

-------------- ---------------

gen_fsm:start_link -----> Module:init/1

 

gen_fsm:send_event -----> Module:StateName/2

 

gen_fsm:send_all_state_event -----> Module:handle_event/3

 

gen_fsm:sync_send_event -----> Module:StateName/3

 

gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4

 

- -----> Module:handle_info/3

 

- -----> Module:terminate/3

 

- -----> Module:code_change/4

    如果回调函数失败或返回错误值，gen_fsm将终止。

    gen_fsm处理系统消息，如sys(3)中所述。该SYS模块可用于调试gen_fsm。

    请注意，gen_fsm不会自动捕获退出信号，必须在回调模块中明确启动。

    除非另有说明，否则如果指定的gen_fsm不存在或者给出了错误的参数，则此模块中的所有函数都将失败。

    如果回调函数指定'hibernate'而不是超时值，gen_fsm进程可以进入休眠状态（参见erlang（3））。如果预计服务器长时间处于空闲状态，这可能很有用。但是，应谨慎使用此功能，因为休眠意味着至少有两个垃圾收集（在休眠时和唤醒后不久）,对于忙的状态机器并不想在每一次调用之间处理垃圾回收。

 

导出

start_link(Module, Args, Options) -> Result

start_link(FsmName, Module, Args, Options) -> Result

    Types:

        FsmName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}

         Name = atom()

         GlobalName = ViaName = term()

        Module = atom()

        Args = term()

        Options = [Option]

         Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}

         Dbgs = [Dbg]

         Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}

         SOpts = [SOpt]

         SOpt - 见erlang:spawn_opt/2,3,4,5

        Result = {ok,Pid} | ignore | {error,Error}

         Pid = pid()

         Error = {already_started,Pid} | term()

    创建gen_fsm进程作为监督树的一部分。该功能应由监督树直接或间接调用。除其他外，它将确保gen_fsm链接到监督树。

    gen_fsm进程调用Module:init/1进行初始化。为确保同步启动过程，在Module:init/1返回之前，start_link/3,4不会返回。

    如果FsmName = {local，Name}，则gen_fsm使用register/2在本地注册为Name。如果FsmName = {global，GlobalName}，则gen_fsm使用global:register_name/2全局注册为GlobalName。如果EventMgrName={via，Module，ViaName}，则事件管理器注册用Module表示的注册表。所述模块的回调应该导出的函数register_name/2，unregister_name/1，whereis_name/1和send/2，其行为应与global中的相应函数相同。因此，{via，global，GlobalName}是有效的引用。

    如果未提供名称，则不会注册gen_fsm。

    Module是回调模块的名称。

    Args是一个任意项，它作为参数传递给Module:init/1。

    如果选项{timeout，Time}存在，则允许gen_fsm花费Time毫秒初始化，或者它将被终止，启动函数将返回 {error，timeout}。

    如果存在选项{debug，Dbgs}，则将为Dbgs中的每个项调用相应的sys函数。见sys（3）。

    如果选项{spawn_opt，SOpts}存在，则SOpts将作为选项列表传递给spawn_opt BIF，后者用于生成gen_fsm进程。见erlang（3）。

    注意

        目前不允许使用spawn选项monitor，但会导致函数失败，原因为badarg。

    如果gen_fsm成功创建并初始化，则函数返回{ok，Pid}，其中Pid是gen_fsm的pid。如果已存在具有指定FsmName的进程，则该函数返回 {error，{already_started，Pid}}，其中Pid是该进程的pid。

    如果Module:init/1因Reason而失败，则函数返回{error，Reason}。如果Module:init/1返回{stop，Reason}或ignore，则进程终止，函数分别返回{error，Reason}或ignore。

 

start(Module, Args, Options) -> Result

start(FsmName, Module, Args, Options) -> Result

    Types:

        FsmName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}

         Name = atom()

         GlobalName = ViaName = term()

        Module = atom()

        Args = term()

        Options = [Option]

         Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}

         Dbgs = [Dbg]

         Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}

         SOpts = [term()]

        Result = {ok,Pid} | ignore | {error,Error}

         Pid = pid()

         Error = {already_started,Pid} | term()

    创建一个独立的gen_fsm进程，即gen_fsm，它不是监督树的一部分，因此没有监督者。

    有关参数和返回值的说明，请参见start_link/3,4。

 

send_event(FsmRef, Event) -> ok

    Types:

        FsmRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()

         Name = Node = atom()

         GlobalName = ViaName = term()

        Event = term()

    将事件异步发送到gen_fsm FsmRef并立即返回ok。gen_fsm将调用Module:StateName/2来处理事件，其中StateName是gen_fsm的当前状态的名称。

    FsmRef可以是：

    pid，

    Name，如果gen_fsm在本地注册，

    {Name，Node}，如果gen_fsm在另一个节点本地注册，或者

    {global，GlobalName}，如果gen_fsm是全局注册的，

    {via，Module，ViaName}，如果事件管理器是通过可选进程注册表注册的,

    Event是一个任意项，作为Module:StateName/2的参数之一传递。

 

send_all_state_event(FsmRef, Event) -> ok

    Types:

        FsmRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()

         Name = Node = atom()

         GlobalName = ViaName = term()

        Event = term()

    将事件异步发送到gen_fsm FsmRef并立即返回ok。gen_fsm将调用Module:handle_event/3来处理事件。

    有关参数的说明，请参阅send_event/2。

    send_event和send_all_state_event之间的区别在于使用哪个回调函数来处理事件。在每个状态下发送事件以相同方式被处理，此函数很有用，因为在每个状态名称函数中只需要一个handle_event子句来处理事件而不是每个状态名函数一个子句。

 

sync_send_event(FsmRef, Event) -> Reply

sync_send_event(FsmRef, Event, Timeout) -> Reply

    Types:

        FsmRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()

         Name = Node = atom()

         GlobalName = ViaName = term()

        Event = term()

        Timeout = int()>0 | infinity

        Reply = term()

    将事件发送到gen_fsm FsmRef并等待，直到回复到达或发生超时。gen_fsm将调用Module:StateName/3来处理事件，其中 StateName是gen_fsm的当前状态的名称。

    有关FsmRef和Event 的说明，请参阅send_event/2。

    Timeout是一个大于零的整数，它指定等待回复的毫秒数，或无限期等待的原子infinity。默认值为5000.如果在指定时间内未收到回复，则函数调用失败。

    返回值Reply在Module:StateName/3的返回值中定义。

    在OTP R12B/Erlang 5.6中删除了在连接到客户端时，如果服务器在调用期间挂了，有时会消耗服务器退出消息的古老行为。

 

sync_send_all_state_event(FsmRef, Event) -> Reply

sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply

    Types:

        FsmRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()

         Name = Node = atom()

         GlobalName = ViaName = term()

        Event = term()

        Timeout = int()>0 | infinity

        Reply = term()

    将事件发送到gen_fsm FsmRef并等待，直到回复到达或发生超时。gen_fsm将调用Module:handle_sync_event/4来处理事件。

    有关FsmRef和Event的说明，请参阅send_event/2。有关Timeout和Reply的说明，请参阅sync_send_event/3。

    见send_all_state_event/2，讨论sync_send_event和sync_send_all_state_event的区别。

 

reply(Caller, Reply) -> true

    Types:

        Caller - 见下面

        Reply = term()

    当无法在Module:State/3或Module:handle_sync_event/4的返回值中定义回复时，gen_fsm可以使用此函数向客户端进程显式发送回复，当调用sync_send_event/2,3或sync_send_all_state_event/2,3。 

    Caller必须是提供给回调函数的From参数。Reply是一个任意项，它将作为sync_send_event/2,3或sync_send_all_state_event/2,3的返回值返回给客户端。

 

send_event_after(Time, Event) -> Ref

    Types:

        Time = integer()

        Event = term()

        Ref = reference()

    在gen_fsm内部发送延迟事件，在time ms后调用此函数。使用cancel_timer/1可用于取消延迟发送的引用，立即返回。

    gen_fsm将调用Module:StateName/2来处理事件，其中StateName是传递延迟事件时gen_fsm的当前状态的名称。

    Event是一个任意项，作为Module:StateName/2的参数之一传递。

 

start_timer(Time, Msg) -> Ref

    Types:

        Time = integer()

        Msg = term()

        Ref = reference()

    在gen_fsm内部发送超时事件，在Time ms后调用此函数。立即返回可用于使用cancel_timer/1取消计时器的引用。

    gen_fsm将调用Module:StateName/2来处理事件，其中StateName是传递超时消息时gen_fsm的当前状态的名称。

    Msg是一个任意的术语，它在超时消息{timeout，Ref，Msg}中传递，作为Module:StateName/2的参数之一。

 

cancel_timer(Ref) -> RemainingTime | false

    Types:

        Ref = reference()

        RemainingTime = integer()

    取消gen_fsm中Ref引用的内部计时器。

    Ref是从send_event_after/2 或 start_timer/2返回的引用。

    如果计时器已经超时，但事件尚未发送，则会被取消，就好像它没有超时一样，因此从此函数返回后将没有错误的计时器事件。

    如果Ref引用活动计时器，则返回以毫秒为单位的剩余时间，直到计时器到期为止，否则返回false。

 

enter_loop(Module, Options, StateName, StateData)

enter_loop(Module, Options, StateName, StateData, FsmName)

enter_loop(Module, Options, StateName, StateData, Timeout)

enter_loop(Module, Options, StateName, StateData, FsmName, Timeout)

    Types:

        Module = atom()

        Options = [Option]

         Option = {debug,Dbgs}

          Dbgs = [Dbg]

           Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}

        StateName = atom()

        StateData = term()

        FsmName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}

         Name = atom()

         GlobalName = ViaName = term()

        Timeout = int() | infinity

    将现有进程转换为gen_fsm。不返回，而是调用进程将进入gen_fsm接收receive循环并成为gen_fsm进程。该进程必须使用proc_lib中的启动函数被启动，参看proc_lib(3)。用户对进程初始化负责，包括注册名字。

    当需要比gen_fsm行为提供的更复杂的初始化过程时，此函数很有用。

    Module，Options和FsmName与调用start[_link]/3,4时的含义相同。但是，如果指定了FsmName，则必须在调用此函数之前相应地注册该进程。

    StateName，StateData和Timeout与Module:init/1的返回值具有相同的含义 。此外，回调模块Module不需要导出init/1功能。

    失败：如果调用进程未由proc_lib启动函数启动，或者未根据FsmName注册。

 

回调函数

    应从gen_fsm回调模块导出以下函数。

    在描述中，表达式state name用于表示状态机的状态。state data用于表示实现状态机的Erlang进程的内部状态。

 

导出

Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} | {error,Reason}

    Types:

        InitArgs = Args | {Args,Term}

        Args = Term = term()

        State = term()

        Reason = term()

    每当将新事件处理程序添加到事件管理器时，都会调用此函数来初始化事件处理程序。

    如果添加了事件处理程序，由于调用gen_event:add_handler/3或gen_event:add_sup_handler/3，则InitArgs是这些函数的Args参数。

    如果事件处理程序由于调用gen_event:swap_handler/3或gen_event:swap_sup_handler/3而替换另一个事件处理程序，或者由于来自其他一个回调函数的交换返回元组，则InitArgs是一个元组{Args，Term} 其中Args是函数call/return元组中提供的参数，Term是终止旧事件处理程序的结果，请参阅gen_event:swap_handler/3。

    如果成功，该函数应返回{ok，State}或{ok，State，hibernate}，其中State是事件处理程序的初始内部状态。

    如果返回{ok，State，hibernate}，则事件管理器将进入休眠状态（通过调用proc_lib:hibernate/3），等待下一个事件发生。 

 

Module:StateName(Event, StateData) -> Result

    Types:

        Event = timeout | term()

        StateData = term()

        Result = {next_state,NextStateName,NewStateData} 

    | {next_state,NextStateName,NewStateData,Timeout}

    | {next_state,NextStateName,NewStateData,hibernate}

    | {stop,Reason,NewStateData}

         NextStateName = atom()

         NewStateData = term()

         Timeout = int()>0 | infinity

         Reason = term()

    每个可能的状态名称应该有一个此函数的实例。每当gen_fsm接收到使用gen_fsm:send_event/2发送的事件时，将调用与当前状态名称StateName同名的此函数的实例来处理该事件。 如果发生超时，也会调用它。

    事件是原子timeout，如果发生超时，Event提供参数给send_event/2。

    StateData是gen_fsm的状态数据。

    如果函数返回{next_state，NextStateName，NewStateData}，{next_state，NextStateName，NewStateData，Timeout}或{next_state，NextStateName，NewStateData，hibernate}，gen_fsm将继续执行，当前状态名称设置为NextStateName并且可能更新状态数据NewStateData。 有关Timeout和hibernate的说明，请参阅Module:init/1。

    如果函数返回{stop，Reason，NewStateData}，gen_fsm将调用Module:terminate(Reason，NewStateData)并终止。      

 

Module:handle_event(Event, StateName, StateData) -> Result

    Types:

        Event = term()

        StateName = atom()

        StateData = term()

        Result = {next_state,NextStateName,NewStateData} 

        | {next_state,NextStateName,NewStateData,Timeout}

        | {next_state,NextStateName,NewStateData,hibernate}

        | {stop,Reason,NewStateData}

        NextStateName = atom()

        NewStateData = term()

        Timeout = int()>0 | infinity

        Reason = term()   

    每当gen_fsm接收到使用gen_fsm:send_all_state_event/2发送的事件时，就会调用此函数来处理该事件。

    StateName是gen_fsm的当前状态名称。

    有关其他参数和可能的返回值的说明，请参阅Module:StateName/2。 

 

Module:StateName(Event, From, StateData) -> Result

    Types:

        Event = term()

        From = {pid(),Tag}

        StateData = term()

        Result = {reply,Reply,NextStateName,NewStateData}

        | {reply,Reply,NextStateName,NewStateData,Timeout}

        | {reply,Reply,NextStateName,NewStateData,hibernate}

        | {next_state,NextStateName,NewStateData}

        | {next_state,NextStateName,NewStateData,Timeout}

        | {next_state,NextStateName,NewStateData,hibernate}

        | {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}

        Reply = term()

        NextStateName = atom()

        NewStateData = term()

        Timeout = int()>0 | infinity

        Reason = normal | term()   

    每个可能的状态名称应该有一个此函数的实例。每当gen_fsm接收到使用gen_fsm:sync_send_event/2,3发送的事件时，将调用与当前状态名称StateName同名的此函数的实例来处理该事件。

    Event是提供给sync_send_event的Event参数。

    From是一个元组{Pid，Tag}，其中Pid是名为sync_send_event/2,3进程的pid，Tag是唯一标记。

    StateData是gen_fsm的状态数据。

    如果函数返回{reply，Reply，NextStateName，NewStateData}，{reply，Reply，NextStateName，NewStateData，Timeout}或{reply，Reply，NextStateName，NewStateData，hibernate}，则Reply将给回到From作为sync_send_event/2,3的返回值。然后gen_fsm继续执行，当前状态名称设置为NextStateName，并且可能更新状态数据NewStateData。有关Timeout和hibernate的说明，请参阅Module:init/1。

    如果函数返回{next_state，NextStateName，NewStateData}，{next_state，NextStateName，NewStateData，Timeout}或{next_state，NextStateName，NewStateData，hibernate}，gen_fsm将继续使用NewStateData在NextStateName中执行。必须使用gen_fsm:reply/2明确给出对From的任何回复。

    如果函数返回{stop，Reason，Reply，NewStateData}，则回复将返回From。如果函数返回{stop，Reason，NewStateData}，则必须使用gen_fsm:reply/2显式给出对From的任何回复。然后gen_fsm将调用Module:terminate(Reason，NewStateData)并终止。         

 

Module:handle_sync_event(Event, From, StateName, StateData) -> Result

    Types:

        Event = term()

        From = {pid(),Tag}

        StateName = atom()

        StateData = term()

        Result = {reply,Reply,NextStateName,NewStateData}

        | {reply,Reply,NextStateName,NewStateData,Timeout}

        | {reply,Reply,NextStateName,NewStateData,hibernate}

        | {next_state,NextStateName,NewStateData}

        | {next_state,NextStateName,NewStateData,Timeout}

        | {next_state,NextStateName,NewStateData,hibernate}

        | {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}

         Reply = term()

         NextStateName = atom()

         NewStateData = term()

         Timeout = int()>0 | infinity

         Reason = term()

    每当gen_fsm接收到使用gen_fsm:sync_send_all_state_event/2,3发送的事件时，将调用此函数来处理该事件。

    StateName是gen_fsm的当前状态名称。

    有关其他参数和可能的返回值的说明，请参阅Module:StateName/3。

 

Module:handle_info(Info, StateName, StateData) -> Result

    Types:

        Info = term()

        StateName = atom()

        StateData = term()

        Result = {next_state,NextStateName,NewStateData}

        | {next_state,NextStateName,NewStateData,Timeout}

        | {next_state,NextStateName,NewStateData,hibernate}

        | {stop,Reason,NewStateData}

        NextStateName = atom()

        NewStateData = term()

        Timeout = int()>0 | infinity

        Reason = normal | term()

    当gen_fsm接收到除同步或异步事件（或系统消息）之外的任何其他消息时，将调用此函数。

    Info是收到的消息。

    有关其他参数和可能的返回值的说明，请参阅Module:StateName/2。

 

Module:terminate(Reason, StateName, StateData)

    Types:

        Reason = normal | shutdown | {shutdown,term()} | term()

        StateName = atom()

        StateData = term()

    当gen_fsm即将终止时，该函数被gen_fsm调用。它应该与Module:init/1相反，并进行任何必要的清理。返回时，gen_fsm以Reason结束。返回值被忽略。

    Reason是表示停止原因的术语，StateName是当前状态名称，StateData是gen_fsm的状态数据。

    Reason取决于gen_fsm为何终止。如果是因为另一个回调函数返回了一个停止元组{stop，..}，则Reason将具有该元组中指定的值。如果是由于失败，则Reason是错误原因。

    如果gen_fsm是监督树的一部分并且由其主管命令终止，则如果满足以下条件，则将使用Reason = shutdown调用此函数：

    gen_fsm已被设置为捕获退出信号，并且监督者的子规范中定义的关闭策略是整数超时值，而不是brutal_kill。

    即使gen_fsm不是监督树的一部分，如果它从其父级接收到“EXIT”消息，也将调用该函数。Reason与“EXIT”消息中的原因相同。

    否则，gen_fsm将立即终止。

    请注意，除了正常，关闭或{shutdown，Term}之外的任何其他原因，假定gen_fsm由于错误而终止，并且使用error_logger:format/2发出错误报告。 

 

Module:code_change(OldVsn, StateName, StateData, Extra) -> {ok, NextStateName, NewStateData}

    Types:

        OldVsn = Vsn | {down, Vsn}

        Vsn = term()

        StateName = NextStateName = atom()

        StateData = NewStateData = term()

        Extra = term()

    当gen_fsm在发布升级/降级期间更新其内部状态数据时，即在appup文件中给出Change= {advanced，Extra}的指令{update，Module，Change，...}时，将调用此函数。 见OTP设计原则。

    在升级的情况下，OldVsn是Vsn，在降级的情况下，OldVsn是{down，Vsn}。 Vsn由旧版本的回调模块Module的vsn属性定义。 如果未定义此类属性，则版本是BEAM文件的校验和。

    StateName是当前状态名称，StateData是gen_fsm的内部状态数据。

    Extra从更新指令的{advanced，Extra}部分按原样传递。

    该函数应返回新的当前状态名称和更新的内部数据。

 

Module:format_status(Opt, [PDict, StateData]) -> Status

    Types:

        Opt = normal | terminate

        PDict = [{Key, Value}]

        StateData = term()

        Status = term()

    请注意，该回调可选，所以回调模块不需要导出它，这个回调模块提供一个默认实现，该函数返回回调模块状态。

 

    在以下情况下，gen_fsm进程会调用此函数：

    调用sys:get_status/1,2之一以获取gen_fsm状态。对于这种情况，Opt设置为原子normal。

    gen_fsm异常终止并记录错误。对于这种情况，选项设置为原子terminate。

    此函数可用于自定义这些情况的gen_fsm状态的形式和外观。希望自定义sys:get_status/1,2返回值以及其状态如何在终止错误日志中出现的回调模块导出format_status/2的实例，该实例返回描述gen_fsm当前状态的术语。

    PDict是gen_fsm的进程字典的当前值。

    StateData是gen_fsm的内部状态数据。

    该函数应返回Status，这是一个定制gen_fsm当前状态和状态详细信息的术语。状态可以采取的形式没有限制，但对于sys:get_status/1,2情况（当Opt是normal时），Status值的推荐形式为[{data，[{“StateData”，Term}]其中Term提供gen_fsm状态数据的相关详细信息。不需要遵循此建议，但这样做会使回调模块状态与sys:get_status/1,2返回值的其余部分保持一致。

    此函数的一个用途是返回紧凑的替代状态数据表示，以避免在日志文件中打印大的状态术语。