diff options
Diffstat (limited to 'system/doc/design_principles/statem.xml')
| -rw-r--r-- | system/doc/design_principles/statem.xml | 882 |
1 files changed, 587 insertions, 295 deletions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index b63327291d..22b622ec5f 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2016</year> + <year>2016</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,11 +29,11 @@ <rev></rev> <file>statem.xml</file> </header> - <marker id="gen_statem behaviour"></marker> + <marker id="gen_statem Behaviour" /> <p> This section is to be read with the <seealso marker="stdlib:gen_statem"><c>gen_statem(3)</c></seealso> - manual page in <c>STDLIB</c>, where all interface functions and callback + manual page in STDLIB, where all interface functions and callback functions are described in detail. </p> <note> @@ -50,9 +50,10 @@ <!-- =================================================================== --> <section> + <marker id="Event-Driven State Machines" /> <title>Event-Driven State Machines</title> <p> - Established Automata theory does not deal much with + Established Automata Theory does not deal much with how a state transition is triggered, but assumes that the output is a function of the input (and the state) and that they are @@ -94,7 +95,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <!-- =================================================================== --> <section> - <marker id="callback_modes" /> + <marker id="Callback Modes" /> <title>Callback Modes</title> <p> The <c>gen_statem</c> behavior supports two callback modes: @@ -109,8 +110,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <pre> StateName(EventType, EventContent, Data) -> - .. code for actions here ... - {next_state, NewStateName, NewData}.</pre> + ... code for actions here ... + {next_state, NewStateName, NewData}. + </pre> + <p> + This form is used in most examples here for example in section + <seealso marker="#Example">Example</seealso>. + </p> </item> <item> <p> @@ -120,8 +126,14 @@ StateName(EventType, EventContent, Data) -> </p> <pre> handle_event(EventType, EventContent, State, Data) -> - .. code for actions here ... - {next_state, NewState, NewData}</pre> + ... code for actions here ... + {next_state, NewState, NewData} + </pre> + <p> + See section + <seealso marker="#One Event Handler">One Event Handler</seealso> + for an example. + </p> </item> </list> <p> @@ -134,10 +146,11 @@ handle_event(EventType, EventContent, State, Data) -> </p> <section> + <marker id="Choosing the Callback Mode" /> <title>Choosing the Callback Mode</title> <p> The two - <seealso marker="#callback_modes">callback modes</seealso> + <seealso marker="#Callback Modes">callback modes</seealso> give different possibilities and restrictions, but one goal remains: you want to handle all possible combinations of @@ -195,10 +208,195 @@ handle_event(EventType, EventContent, State, Data) -> <!-- =================================================================== --> <section> + <marker id="State Enter Calls" /> + <title>State Enter Calls</title> + <p> + The <c>gen_statem</c> behavior can regardless of callback mode + automatically + <seealso marker="stdlib:gen_statem#type-state_enter"> + call the state callback + </seealso> + with special arguments whenever the state changes + so you can write state entry actions + near the rest of the state transition rules. + It typically looks like this: + </p> + <pre> +StateName(enter, _OldState, Data) -> + ... code for state entry actions here ... + {keep_state, NewData}; +StateName(EventType, EventContent, Data) -> + ... code for actions here ... + {next_state, NewStateName, NewData}.</pre> + <p> + Depending on how your state machine is specified, + this can be a very useful feature, + but it forces you to handle the state enter calls in all states. + See also the + <seealso marker="#State Entry Actions"> + State Entry Actions + </seealso> + chapter. + </p> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Actions" /> + <title>Actions</title> + <p> + In the first section + <seealso marker="#Event-Driven State Machines"> + Event-Driven State Machines + </seealso> + actions were mentioned as a part of + the general state machine model. These general actions + are implemented with the code that callback module + <c>gen_statem</c> executes in an event-handling + callback function before returning + to the <c>gen_statem</c> engine. + </p> + <p> + There are more specific state-transition actions + that a callback function can order the <c>gen_statem</c> + engine to do after the callback function return. + These are ordered by returning a list of + <seealso marker="stdlib:gen_statem#type-action">actions</seealso> + in the + <seealso marker="stdlib:gen_statem#type-state_callback_result">return tuple</seealso> + from the + <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>. + These state transition actions affect the <c>gen_statem</c> + engine itself and can do the following: + </p> + <list type="bulleted"> + <item> + <seealso marker="stdlib:gen_statem#type-postpone"> + Postpone + </seealso> + the current event, see section + <seealso marker="#Postponing Events">Postponing Events</seealso> + </item> + <item> + <seealso marker="stdlib:gen_statem#type-hibernate"> + Hibernate + </seealso> + the <c>gen_statem</c>, treated in + <seealso marker="#Hibernation">Hibernation</seealso> + </item> + <item> + Start a + <seealso marker="stdlib:gen_statem#type-state_timeout"> + state time-out</seealso>, + read more in section + <seealso marker="#State Time-Outs">State Time-Outs</seealso> + </item> + <item> + Start an + <seealso marker="stdlib:gen_statem#type-event_timeout">event time-out</seealso>, + see more in section + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> + </item> + <item> + <seealso marker="stdlib:gen_statem#type-reply_action"> + Reply + </seealso> + to a caller, mentioned at the end of section + <seealso marker="#All State Events">All State Events</seealso> + </item> + <item> + Generate the + <seealso marker="stdlib:gen_statem#type-action"> + next event + </seealso> + to handle, see section + <seealso marker="#Self-Generated Events">Self-Generated Events</seealso> + </item> + </list> + <p> + For details, see the + <seealso marker="stdlib:gen_statem#type-action"> + <c>gen_statem(3)</c> + </seealso> + manual page. + You can, for example, reply to many callers + and generate multiple next events to handle. + </p> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Event Types" /> + <title>Event Types</title> + <p> + Events are categorized in different + <seealso marker="stdlib:gen_statem#type-event_type">event types</seealso>. + Events of all types are handled in the same callback function, + for a given state, and the function gets + <c>EventType</c> and <c>EventContent</c> as arguments. + </p> + <p> + The following is a complete list of event types and where + they come from: + </p> + <taglist> + <tag><c>cast</c></tag> + <item> + Generated by + <seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast</c></seealso>. + </item> + <tag><c>{call,From}</c></tag> + <item> + Generated by + <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>, + where <c>From</c> is the reply address to use + when replying either through the state transition action + <c>{reply,From,Msg}</c> or by calling + <seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>. + </item> + <tag><c>info</c></tag> + <item> + Generated by any regular process message sent to + the <c>gen_statem</c> process. + </item> + <tag><c>state_timeout</c></tag> + <item> + Generated by state transition action + <seealso marker="stdlib:gen_statem#type-state_timeout"> + <c>{state_timeout,Time,EventContent}</c> + </seealso> + state timer timing out. + </item> + <tag><c>timeout</c></tag> + <item> + Generated by state transition action + <seealso marker="stdlib:gen_statem#type-event_timeout"> + <c>{timeout,Time,EventContent}</c> + </seealso> + (or its short form <c>Time</c>) + event timer timing out. + </item> + <tag><c>internal</c></tag> + <item> + Generated by state transition + <seealso marker="stdlib:gen_statem#type-action">action</seealso> + <c>{next_event,internal,EventContent}</c>. + All event types above can also be generated using + <c>{next_event,EventType,EventContent}</c>. + </item> + </taglist> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Example" /> <title>Example</title> <p> This example starts off as equivalent to the example in section - <seealso marker="fsm"><c>gen_fsm</c> Behavior</seealso>. + <seealso marker="fsm"><c>gen_fsm</c> Behavior</seealso>. In later sections, additions and tweaks are made using features in <c>gen_statem</c> that <c>gen_fsm</c> does not have. The end of this chapter provides the example again @@ -221,16 +419,14 @@ handle_event(EventType, EventContent, State, Data) -> This code lock state machine can be implemented using <c>gen_statem</c> with the following callback module: </p> - <marker id="ex"></marker> <code type="erl"><![CDATA[ -module(code_lock). -behaviour(gen_statem). -define(NAME, code_lock). --define(CALLBACK_MODE, state_functions). -export([start_link/1]). -export([button/1]). --export([init/1,terminate/3,code_change/4]). +-export([init/1,callback_mode/0,terminate/3,code_change/4]). -export([locked/3,open/3]). start_link(Code) -> @@ -242,7 +438,10 @@ button(Digit) -> init(Code) -> do_lock(), Data = #{code => Code, remaining => Code}, - {?CALLBACK_MODE,locked,Data}. + {ok, locked, Data}. + +callback_mode() -> + state_functions. locked( cast, {button,Digit}, @@ -250,19 +449,19 @@ locked( case Remaining of [Digit] -> do_unlock(), - {next_state,open,Data#{remaining := Code},10000}; + {next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}]; [Digit|Rest] -> % Incomplete - {next_state,locked,Data#{remaining := Rest}}; + {next_state, locked, Data#{remaining := Rest}}; _Wrong -> - {next_state,locked,Data#{remaining := Code}} + {next_state, locked, Data#{remaining := Code}} end. -open(timeout, _, Data) -> +open(state_timeout, lock, Data) -> do_lock(), - {next_state,locked,Data}; + {next_state, locked, Data}; open(cast, {button,_}, Data) -> - do_lock(), - {next_state,locked,Data}. + {next_state, open, Data}. do_lock() -> io:format("Lock~n", []). @@ -273,7 +472,7 @@ terminate(_Reason, State, _Data) -> State =/= locked andalso do_lock(), ok. code_change(_Vsn, State, Data, _Extra) -> - {?CALLBACK_MODE,State,Data}. + {ok, State, Data}. ]]></code> <p>The code is explained in the next sections.</p> </section> @@ -281,6 +480,7 @@ code_change(_Vsn, State, Data, _Extra) -> <!-- =================================================================== --> <section> + <marker id="Starting gen_statem" /> <title>Starting gen_statem</title> <p> In the example in the previous section, <c>gen_statem</c> is @@ -308,7 +508,7 @@ start_link(Code) -> as <c>{global,Name}</c>, then the <c>gen_statem</c> is registered using <seealso marker="kernel:global#register_name/2"><c>global:register_name/2</c></seealso> - in <c>Kernel</c>. + in Kernel. </p> </item> <item> @@ -343,14 +543,8 @@ start_link(Code) -> <p> If name registration succeeds, the new <c>gen_statem</c> process calls callback function <c>code_lock:init(Code)</c>. - This function is expected to return <c>{CallbackMode,State,Data}</c>, - where - <seealso marker="#callback_modes"><c>CallbackMode</c></seealso> - selects callback module state function mode, in this case - <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso> - through macro <c>?CALLBACK_MODE</c>. That is, each state - has got its own handler function. - <c>State</c> is the initial state of the <c>gen_statem</c>, + This function is expected to return <c>{ok, State, Data}</c>, + where <c>State</c> is the initial state of the <c>gen_statem</c>, in this case <c>locked</c>; assuming that the door is locked to begin with. <c>Data</c> is the internal server data of the <c>gen_statem</c>. Here the server data is a <seealso marker="stdlib:maps">map</seealso> @@ -359,11 +553,12 @@ start_link(Code) -> that stores the remaining correct button sequence (the same as the <c>code</c> to begin with). </p> + <code type="erl"><![CDATA[ init(Code) -> do_lock(), Data = #{code => Code, remaining => Code}, - {?CALLBACK_MODE,locked,Data}. + {ok,locked,Data}. ]]></code> <p>Function <seealso marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link</c></seealso> @@ -380,11 +575,27 @@ init(Code) -> can be used to start a standalone <c>gen_statem</c>, that is, a <c>gen_statem</c> that is not part of a supervision tree. </p> + + <code type="erl"><![CDATA[ +callback_mode() -> + state_functions. + ]]></code> + <p> + Function + <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + selects the + <seealso marker="#Callback Modes"><c>CallbackMode</c></seealso> + for the callback module, in this case + <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso>. + That is, each state has got its own handler function. + </p> + </section> <!-- =================================================================== --> <section> + <marker id="Handling Events" /> <title>Handling Events</title> <p>The function notifying the code lock about a button event is implemented using @@ -404,11 +615,13 @@ button(Digit) -> The event is made into a message and sent to the <c>gen_statem</c>. When the event is received, the <c>gen_statem</c> calls <c>StateName(cast, Event, Data)</c>, which is expected to - return a tuple <c>{next_state,NewStateName,NewData}</c>. + return a tuple <c>{next_state, NewStateName, NewData}</c>, + or <c>{next_state, NewStateName, NewData, Actions}</c>. <c>StateName</c> is the name of the current state and <c>NewStateName</c> is the name of the next state to go to. <c>NewData</c> is a new value for the server data of - the <c>gen_statem</c>. + the <c>gen_statem</c>, and <c>Actions</c> is a list of + actions on the <c>gen_statem</c> engine. </p> <code type="erl"><![CDATA[ locked( @@ -417,19 +630,19 @@ locked( case Remaining of [Digit] -> % Complete do_unlock(), - {next_state,open,Data#{remaining := Code},10000}; + {next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}]}; [Digit|Rest] -> % Incomplete - {next_state,locked,Data#{remaining := Rest}}; + {next_state, locked, Data#{remaining := Rest}}; [_|_] -> % Wrong - {next_state,locked,Data#{remaining := Code}} + {next_state, locked, Data#{remaining := Code}} end. -open(timeout, _, Data) -> +open(state_timeout, lock, Data) -> do_lock(), - {next_state,locked,Data}; + {next_state, locked, Data}; open(cast, {button,_}, Data) -> - do_lock(), - {next_state,locked,Data}. + {next_state, open, Data}. ]]></code> <p> If the door is locked and a button is pressed, the pressed @@ -443,38 +656,55 @@ open(cast, {button,_}, Data) -> restarts from the start of the code sequence. </p> <p> - In state <c>open</c>, any button locks the door, as - any event cancels the event timer, so no - time-out event occurs after a button event. + If the whole code is correct, the server changes states + to <c>open</c>. + </p> + <p> + In state <c>open</c>, a button event is ignored + by staying in the same state. This can also be done + by returning <c>{keep_state, Data}</c> or in this case + since <c>Data</c> unchanged even by returning + <c>keep_state_and_data</c>. </p> </section> <section> - <title>Event Time-Outs</title> + <marker id="State Time-Outs" /> + <title>State Time-Outs</title> <p> When a correct code has been given, the door is unlocked and the following tuple is returned from <c>locked/2</c>: </p> <code type="erl"><![CDATA[ -{next_state,open,Data#{remaining := Code},10000}; +{next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}]}; ]]></code> <p> 10,000 is a time-out value in milliseconds. After this time (10 seconds), a time-out occurs. - Then, <c>StateName(timeout, 10000, Data)</c> is called. + Then, <c>StateName(state_timeout, lock, Data)</c> is called. The time-out occurs when the door has been in state <c>open</c> for 10 seconds. After that the door is locked again: </p> <code type="erl"><![CDATA[ -open(timeout, _, Data) -> +open(state_timeout, lock, Data) -> do_lock(), - {next_state,locked,Data}; + {next_state, locked, Data}; ]]></code> + <p> + The timer for a state time-out is automatically cancelled + when the state machine changes states. You can restart + a state time-out by setting it to a new time, which cancels + the running timer and starts a new. This implies that + you can cancel a state time-out by restarting it with + time <c>infinity</c>. + </p> </section> <!-- =================================================================== --> <section> + <marker id="All State Events" /> <title>All State Events</title> <p> Sometimes events can arrive in any state of the <c>gen_statem</c>. @@ -507,21 +737,24 @@ open(EventType, EventContent, Data) -> handle_event(EventType, EventContent, Data). handle_event({call,From}, code_length, #{code := Code} = Data) -> - {keep_state,Data,[{reply,From,length(Code)}]}. + {keep_state, Data, [{reply,From,length(Code)}]}. ]]></code> <p> This example uses <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call/2</c></seealso>, which waits for a reply from the server. The reply is sent with a <c>{reply,From,Reply}</c> tuple - in an action list in the <c>{keep_state,...}</c> tuple - that retains the current state. + in an action list in the <c>{keep_state, ...}</c> tuple + that retains the current state. This return form is convenient + when you want to stay in the current state but do not know or + care about what it is. </p> </section> <!-- =================================================================== --> <section> + <marker id="One Event Handler" /> <title>One Event Handler</title> <p> If mode <c>handle_event_function</c> is used, @@ -533,12 +766,11 @@ handle_event({call,From}, code_length, #{code := Code} = Data) -> </p> <code type="erl"><![CDATA[ ... --define(CALLBACK_MODE, handle_event_function). - -... -export([handle_event/4]). ... +callback_mode() -> + handle_event_function. handle_event(cast, {button,Digit}, State, #{code := Code} = Data) -> case State of @@ -546,19 +778,19 @@ handle_event(cast, {button,Digit}, State, #{code := Code} = Data) -> case maps:get(remaining, Data) of [Digit] -> % Complete do_unlock(), - {next_state,open,Data#{remaining := Code},10000}; + {next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}}; + {keep_state, Data#{remaining := Rest}}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}} + {keep_state, Data#{remaining := Code}} end; open -> - do_lock(), - {next_state,locked,Data} + keep_state_and_data end; -handle_event(timeout, _, open, Data) -> +handle_event(state_timeout, lock, open, Data) -> do_lock(), - {next_state,locked,Data}. + {next_state, locked, Data}. ... ]]></code> @@ -567,9 +799,11 @@ handle_event(timeout, _, open, Data) -> <!-- =================================================================== --> <section> + <marker id="Stopping" /> <title>Stopping</title> <section> + <marker id="In a Supervision Tree" /> <title>In a Supervision Tree</title> <p> If the <c>gen_statem</c> is part of a supervision tree, @@ -597,7 +831,7 @@ init(Args) -> callback function <c>terminate(shutdown, State, Data)</c>. </p> <p> - In the following example, function <c>terminate/3</c> + In this example, function <c>terminate/3</c> locks the door if it is open, so we do not accidentally leave the door open when the supervision tree terminates: </p> @@ -609,6 +843,7 @@ terminate(_Reason, State, _Data) -> </section> <section> + <marker id="Standalone gen_statem" /> <title>Standalone gen_statem</title> <p> If the <c>gen_statem</c> is not part of a supervision tree, @@ -635,127 +870,77 @@ stop() -> <!-- =================================================================== --> <section> - <title>Actions</title> + <marker id="Event Time-Outs" /> + <title>Event Time-Outs</title> <p> - In the first sections actions were mentioned as a part of - the general state machine model. These general actions - are implemented with the code that callback module - <c>gen_statem</c> executes in an event-handling - callback function before returning - to the <c>gen_statem</c> engine. + A timeout feature inherited from <c>gen_statem</c>'s predecessor + <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso>, + is an event time-out, that is, + if an event arrives the timer is cancelled. + You get either an event or a time-out, but not both. </p> <p> - There are more specific state-transition actions - that a callback function can order the <c>gen_statem</c> - engine to do after the callback function return. - These are ordered by returning a list of - <seealso marker="stdlib:gen_statem#type-action">actions</seealso> - in the - <seealso marker="stdlib:gen_statem#type-state_function_result">return tuple</seealso> - from the - <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>. - These state transition actions affect the <c>gen_statem</c> - engine itself and can do the following: + It is ordered by the state transition action + <c>{timeout,Time,EventContent}</c>, or just <c>Time</c>, + or even just <c>Time</c> instead of an action list + (the latter is a form inherited from <c>gen_fsm</c>. </p> - <list type="bulleted"> - <item>Postpone the current event</item> - <item>Hibernate the <c>gen_statem</c></item> - <item>Start an event time-out</item> - <item>Reply to a caller</item> - <item>Generate the next event to handle</item> - </list> <p> - In the example earlier was mentioned the event time-out - and replying to a caller. - An example of event postponing is included later in this chapter. - For details, see the - <seealso marker="stdlib:gen_statem#type-action"><c>gen_statem(3)</c></seealso> - manual page. - You can, for example, reply to many callers - and generate multiple next events to handle. + This type of time-out is useful to for example act on inactivity. + Let us restart the code sequence + if no button is pressed for say 30 seconds: </p> - </section> - -<!-- =================================================================== --> + <code type="erl"><![CDATA[ +... - <section> - <title>Event Types</title> +locked( + timeout, _, + #{code := Code, remaining := Remaining} = Data) -> + {next_state, locked, Data#{remaining := Code}}; +locked( + cast, {button,Digit}, + #{code := Code, remaining := Remaining} = Data) -> +... + [Digit|Rest] -> % Incomplete + {next_state, locked, Data#{remaining := Rest}, 30000}; +... + ]]></code> <p> - The previous sections mentioned a few - <seealso marker="stdlib:gen_statem#type-event_type">event types</seealso>. - Events of all types are handled in the same callback function, - for a given state, and the function gets - <c>EventType</c> and <c>EventContent</c> as arguments. + Whenever we receive a button event we start an event timeout + of 30 seconds, and if we get an event type <c>timeout</c> + we reset the remaining code sequence. </p> <p> - The following is a complete list of event types and where - they come from: + An event timeout is cancelled by any other event so you either + get some other event or the timeout event. It is therefore + not possible nor needed to cancel or restart an event timeout. + Whatever event you act on has already cancelled + the event timeout... </p> - <taglist> - <tag><c>cast</c></tag> - <item> - Generated by - <seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast</c></seealso>. - </item> - <tag><c>{call,From}</c></tag> - <item> - Generated by - <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>, - where <c>From</c> is the reply address to use - when replying either through the state transition action - <c>{reply,From,Msg}</c> or by calling - <seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>. - </item> - <tag><c>info</c></tag> - <item> - Generated by any regular process message sent to - the <c>gen_statem</c> process. - </item> - <tag><c>timeout</c></tag> - <item> - Generated by state transition action - <c>{timeout,Time,EventContent}</c> (or its short form <c>Time</c>) - timer timing out. - </item> - <tag><c>internal</c></tag> - <item> - Generated by state transition action - <c>{next_event,internal,EventContent}</c>. - All event types above can also be generated using - <c>{next_event,EventType,EventContent}</c>. - </item> - </taglist> </section> <!-- =================================================================== --> <section> - <title>State Time-Outs</title> - <p> - The time-out event generated by state transition action - <c>{timeout,Time,EventContent}</c> is an event time-out, - that is, if an event arrives the timer is cancelled. - You get either an event or a time-out, but not both. - </p> + <marker id="Erlang Timers" /> + <title>Erlang Timers</title> <p> - Often you want a timer not to be cancelled by any event - or you want to start a timer in one state and respond - to the time-out in another. This can be accomplished - with a regular Erlang timer: - <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer</c></seealso>. + The previous example of state time-outs only work if + the state machine stays in the same state during the + time-out time. And event time-outs only work if no + disturbing unrelated events occur. </p> <p> - For the example so far in this chapter: using the - <c>gen_statem</c> event timer has the consequence that - if a button event is generated while in the <c>open</c> state, - the time-out is cancelled and the button event is delivered. - So, we choose to lock the door if this occurred. + You may want to start a timer in one state and respond + to the time-out in another, maybe cancel the time-out + without changing states, or perhaps run multiple + time-outs in parallel. All this can be accomplished + with Erlang Timers: + <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer3,4</c></seealso>. </p> <p> - Suppose that we do not want a button to lock the door, - instead we want to ignore button events in the <c>open</c> state. - Then we start a timer when entering the <c>open</c> state - and waits for it to expire while ignoring button events: + Here is how to accomplish the state time-out + in the previous example by insted using an Erlang Timer: </p> <code type="erl"><![CDATA[ ... @@ -766,25 +951,37 @@ locked( [Digit] -> do_unlock(), Tref = erlang:start_timer(10000, self(), lock), - {next_state,open,Data#{remaining := Code, timer := Tref}}; + {next_state, open, Data#{remaining := Code, timer => Tref}}; ... open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) -> do_lock(), - {next_state,locked,Data}; + {next_state,locked,maps:remove(timer, Data)}; open(cast, {button,_}, Data) -> {keep_state,Data}; ... ]]></code> <p> + Removing the <c>timer</c> key from the map when we + change to state <c>locked</c> is not strictly + necessary since we can only get into state <c>open</c> + with an updated <c>timer</c> map value. But it can be nice + to not have outdated values in the state <c>Data</c>! + </p> + <p> If you need to cancel a timer because of some other event, you can use <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>. - Notice that a time-out message cannot arrive after this, - unless you have postponed it (see the next section) before, + Note that a time-out message cannot arrive after this, + unless you have postponed it before (see the next section), so ensure that you do not accidentally postpone such messages. + Also note that a time-out message may have arrived + just before you cancelling it, so you may have to read out + such a message from the process mailbox depending on + the return value from + <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>. </p> <p> - Another way to cancel a timer is not to cancel it, + Another way to handle a late time-out can be to not cancel it, but to ignore it if it arrives in a state where it is known to be late. </p> @@ -793,6 +990,7 @@ open(cast, {button,_}, Data) -> <!-- =================================================================== --> <section> + <marker id="Postponing Events" /> <title>Postponing Events</title> <p> If you want to ignore a particular event in the current state @@ -817,20 +1015,28 @@ open(cast, {button,_}, Data) -> ... ]]></code> <p> - The fact that a postponed event is only retried after a state change - translates into a requirement on the event and state space. - If you have a choice between storing a state data item - in the <c>State</c> or in the <c>Data</c>: - if a change in the item value affects which events that - are handled, then this item is to be part of the state. + Since a postponed event is only retried after a state change, + you have to think about where to keep a state data item. + You can keep it in the server <c>Data</c> + or in the <c>State</c> itself, + for example by having two more or less identical states + to keep a boolean value, or by using a complex state with + <seealso marker="#Callback Modes">callback mode</seealso> + <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso>. + If a change in the value changes the set of events that is handled, + then the value should be kept in the State. + Otherwise no postponed events will be retried + since only the server Data changes. </p> <p> - You want to avoid that you maybe much later decide - to postpone an event in one state and by misfortune it is never retried, - as the code only changes the <c>Data</c> but not the <c>State</c>. + This is not important if you do not postpone events. + But if you later decide to start postponing some events, + then the design flaw of not having separate states + when they should be, might become a hard to find bug. </p> <section> + <marker id="Fuzzy State Diagrams" /> <title>Fuzzy State Diagrams</title> <p> It is not uncommon that a state diagram does not specify @@ -847,6 +1053,7 @@ open(cast, {button,_}, Data) -> </section> <section> + <marker id="Selective Receive" /> <title>Selective Receive</title> <p> Erlang's selective receive statement is often used to @@ -926,6 +1133,70 @@ do_unlock() -> <!-- =================================================================== --> <section> + <marker id="State Entry Actions" /> + <title>State Entry Actions</title> + <p> + Say you have a state machine specification + that uses state entry actions. + Allthough you can code this using self-generated events + (described in the next section), especially if just + one or a few states has got state entry actions, + this is a perfect use case for the built in + <seealso marker="#State Enter Calls">state enter calls</seealso>. + </p> + <p> + You return a list containing <c>state_enter</c> from your + <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>callback_mode/0</c></seealso> + function and the <c>gen_statem</c> engine will call your + state callback once with the arguments + <c>(enter, OldState, ...)</c> whenever the state changes. + Then you just need to handle these event-like calls in all states. + </p> + <code type="erl"><![CDATA[ +... +init(Code) -> + process_flag(trap_exit, true), + Data = #{code => Code}, + {ok, locked, Data}. + +callback_mode() -> + [state_functions,state_enter]. + +locked(enter, _OldState, Data) -> + do_lock(), + {keep_state,Data#{remaining => Code}}; +locked( + cast, {button,Digit}, + #{code := Code, remaining := Remaining} = Data) -> + case Remaining of + [Digit] -> + {next_state, open, Data}; +... + +open(enter, _OldState, _Data) -> + do_unlock(), + {keep_state_and_data, [{state_timeout,10000,lock}]}; +open(state_timeout, lock, Data) -> + {next_state, locked, Data}; +... + ]]></code> + <p> + You can repeat the state entry code by returning one of + <c>{repeat_state, ...}</c>, <c>{repeat_state_and_data,_}</c> + or <c>repeat_state_and_data</c> that otherwise behaves + exactly like their <c>keep_state</c> siblings. + See the type + <seealso marker="stdlib:gen_statem#type-state_callback_result"> + <c>state_callback_result()</c> + </seealso> + in the reference manual. + </p> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Self-Generated Events" /> <title>Self-Generated Events</title> <p> It can sometimes be beneficial to be able to generate events @@ -943,67 +1214,71 @@ do_unlock() -> from your state machine to itself. </p> <p> - One example of using self-generated events can be when you have - a state machine specification that uses state entry actions. - You can code that using a dedicated function - to do the state transition. But if you want that code to be - visible besides the other state logic, you can insert - an <c>internal</c> event that does the entry actions. - This has the same unfortunate consequence as using - state transition functions: everywhere you go to - the state, you must explicitly - insert the <c>internal</c> event - or use a state transition function. + One example for this is to pre-process incoming data, for example + decrypting chunks or collecting characters up to a line break. + Purists may argue that this should be modelled with a separate + state machine that sends pre-processed events + to the main state machine. + But to decrease overhead the small pre-processing state machine + can be implemented in the common state event handling + of the main state machine using a few state data variables + that then sends the pre-processed events as internal events + to the main state machine. </p> <p> - The following is an implementation of entry actions - using <c>internal</c> events with content <c>enter</c> - using a helper function <c>enter/3</c> for state entry: + The following example uses an input model where you give the lock + characters with <c>put_chars(Chars)</c> and then call + <c>enter()</c> to finish the input. </p> <code type="erl"><![CDATA[ ... --define(CALLBACK_MODE, state_functions). - +-export(put_chars/1, enter/0). ... +put_chars(Chars) when is_binary(Chars) -> + gen_statem:call(?NAME, {chars,Chars}). -init(Code) -> - process_flag(trap_exit, true), - Data = #{code => Code}, - enter(?CALLBACK_MODE, locked, Data). +enter() -> + gen_statem:call(?NAME, enter). ... -locked(internal, enter, _Data) -> +locked(enter, _OldState, Data) -> do_lock(), - {keep_state,Data#{remaining => Code}}; -locked( - cast, {button,Digit}, - #{code := Code, remaining := Remaining} = Data) -> - case Remaining of - [Digit] -> - enter(next_state, open, Data); + {keep_state,Data#{remaining => Code, buf => []}}; ... -open(internal, enter, _Data) -> - Tref = erlang:start_timer(10000, self(), lock), - do_unlock(), - {keep_state,Data#{timer => Tref}}; -open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) -> - enter(next_state, locked, Data); +handle_event({call,From}, {chars,Chars}, #{buf := Buf} = Data) -> + {keep_state, Data#{buf := [Chars|Buf], + [{reply,From,ok}]}; +handle_event({call,From}, enter, #{buf := Buf} = Data) -> + Chars = unicode:characters_to_binary(lists:reverse(Buf)), + try binary_to_integer(Chars) of + Digit -> + {keep_state, Data#{buf := []}, + [{reply,From,ok}, + {next_event,internal,{button,Chars}}]} + catch + error:badarg -> + {keep_state, Data#{buf := []}, + [{reply,From,{error,not_an_integer}}]} + end; ... - -enter(Tag, State, Data) -> - {Tag,State,Data,[{next_event,internal,enter}]}. ]]></code> + <p> + If you start this program with <c>code_lock:start([17])</c> + you can unlock with <c>code_lock:put_chars(<<"001">>), + code_lock:put_chars(<<"7">>), code_lock:enter()</c>. + </p> </section> <!-- =================================================================== --> <section> + <marker id="Example Revisited" /> <title>Example Revisited</title> <p> - This section includes the example after all mentioned modifications - and some more using the entry actions, + This section includes the example after most of the mentioned + modifications and some more using state enter calls, which deserves a new state diagram: </p> <image file="../design_principles/code_lock_2.png"> @@ -1019,6 +1294,7 @@ enter(Tag, State, Data) -> </p> <section> + <marker id="Callback Mode: state_functions" /> <title>Callback Mode: state_functions</title> <p> Using state functions: @@ -1027,11 +1303,10 @@ enter(Tag, State, Data) -> -module(code_lock). -behaviour(gen_statem). -define(NAME, code_lock_2). --define(CALLBACK_MODE, state_functions). -export([start_link/1,stop/0]). -export([button/1,code_length/0]). --export([init/1,terminate/3,code_change/4]). +-export([init/1,callback_mode/0,terminate/3,code_change/4]). -export([locked/3,open/3]). start_link(Code) -> @@ -1047,40 +1322,44 @@ code_length() -> init(Code) -> process_flag(trap_exit, true), Data = #{code => Code}, - enter(?CALLBACK_MODE, locked, Data). + {ok, locked, Data}. + +callback_mode() -> + [state_functions,state_enter]. -locked(internal, enter, #{code := Code} = Data) -> +locked(enter, _OldState, #{code := Code} = Data) -> do_lock(), - {keep_state,Data#{remaining => Code}}; + {keep_state, Data#{remaining => Code}}; +locked( + timeout, _, + #{code := Code, remaining := Remaining} = Data) -> + {keep_state, Data#{remaining := Code}}; locked( cast, {button,Digit}, #{code := Code, remaining := Remaining} = Data) -> case Remaining of [Digit] -> % Complete - enter(next_state, open, Data); + {next_state, open, Data}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}}; + {keep_state, Data#{remaining := Rest}, 30000}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}} + {keep_state, Data#{remaining := Code}} end; locked(EventType, EventContent, Data) -> handle_event(EventType, EventContent, Data). -open(internal, enter, Data) -> - Tref = erlang:start_timer(10000, self(), lock), +open(enter, _OldState, _Data) -> do_unlock(), - {keep_state,Data#{timer => Tref}}; -open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) -> - enter(next_state, locked, Data); + {keep_state_and_data, [{state_timeout,10000,lock}]}; +open(state_timeout, lock, Data) -> + {next_state, locked, Data}; open(cast, {button,_}, _) -> - {keep_state_and_data,[postpone]}; + {keep_state_and_data, [postpone]}; open(EventType, EventContent, Data) -> handle_event(EventType, EventContent, Data). handle_event({call,From}, code_length, #{code := Code}) -> - {keep_state_and_data,[{reply,From,length(Code)}]}. -enter(Tag, State, Data) -> - {Tag,State,Data,[{next_event,internal,enter}]}. + {keep_state_and_data, [{reply,From,length(Code)}]}. do_lock() -> io:format("Locked~n", []). @@ -1091,64 +1370,69 @@ terminate(_Reason, State, _Data) -> State =/= locked andalso do_lock(), ok. code_change(_Vsn, State, Data, _Extra) -> - {?CALLBACK_MODE,State,Data}. + {ok,State,Data}. ]]></code> </section> <section> + <marker id="Callback Mode: handle_event_function" /> <title>Callback Mode: handle_event_function</title> <p> This section describes what to change in the example to use one <c>handle_event/4</c> function. The previously used approach to first branch depending on event - does not work that well here because of the generated - entry actions, so this example first branches depending on state: + does not work that well here because of the state enter calls, + so this example first branches depending on state: </p> <code type="erl"><![CDATA[ ... --define(CALLBACK_MODE, handle_event_function). - -... -export([handle_event/4]). ... +callback_mode() -> + [handle_event_function,state_enter]. %% State: locked -handle_event(internal, enter, locked, #{code := Code} = Data) -> +handle_event( + enter, _OldState, locked, + #{code := Code} = Data) -> do_lock(), - {keep_state,Data#{remaining => Code}}; + {keep_state, Data#{remaining => Code}}; +handle_event( + timeout, _, locked, + #{code := Code, remaining := Remaining} = Data) -> + {keep_state, Data#{remaining := Code}}; handle_event( cast, {button,Digit}, locked, #{code := Code, remaining := Remaining} = Data) -> case Remaining of [Digit] -> % Complete - enter(next_state, open, Data); + {next_state, open, Data}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}}; + {keep_state, Data#{remaining := Rest}, 30000}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}} + {keep_state, Data#{remaining := Code}} end; %% %% State: open -handle_event(internal, enter, open, Data) -> - Tref = erlang:start_timer(10000, self(), lock), +handle_event(enter, _OldState, open, _Data) -> do_unlock(), - {keep_state,Data#{timer => Tref}}; -handle_event(info, {timeout,Tref,lock}, open, #{timer := Tref} = Data) -> - enter(next_state, locked, Data); + {keep_state_and_data, [{state_timeout,10000,lock}]}; +handle_event(state_timeout, lock, open, Data) -> + {next_state, locked, Data}; handle_event(cast, {button,_}, open, _) -> {keep_state_and_data,[postpone]}; %% %% Any state handle_event({call,From}, code_length, _State, #{code := Code}) -> - {keep_state_and_data,[{reply,From,length(Code)}]}. + {keep_state_and_data, [{reply,From,length(Code)}]}. ... ]]></code> </section> <p> Notice that postponing buttons from the <c>locked</c> state - to the <c>open</c> state feels like the wrong thing to do + to the <c>open</c> state feels like a strange thing to do for a code lock, but it at least illustrates event postponing. </p> </section> @@ -1156,6 +1440,7 @@ handle_event({call,From}, code_length, _State, #{code := Code}) -> <!-- =================================================================== --> <section> + <marker id="Filter the State" /> <title>Filter the State</title> <p> The example servers so far in this chapter @@ -1208,19 +1493,21 @@ format_status(Opt, [_PDict,State,Data]) -> <seealso marker="stdlib:gen_statem#Module:format_status/2"><c>Module:format_status/2</c></seealso> function. If you do not, a default implementation is used that does the same as this example function without filtering - the <c>Data</c> term, that is, <c>StateData = {State,Data}</c>. + the <c>Data</c> term, that is, <c>StateData = {State,Data}</c>, + in this example containing sensitive information. </p> </section> <!-- =================================================================== --> <section> + <marker id="Complex State" /> <title>Complex State</title> <p> The callback mode <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso> enables using a non-atom state as described in section - <seealso marker="#callback_modes">Callback Modes</seealso>, + <seealso marker="#Callback Modes">Callback Modes</seealso>, for example, a complex state term like a tuple. </p> <p> @@ -1273,11 +1560,10 @@ format_status(Opt, [_PDict,State,Data]) -> -module(code_lock). -behaviour(gen_statem). -define(NAME, code_lock_3). --define(CALLBACK_MODE, handle_event_function). -export([start_link/2,stop/0]). -export([button/1,code_length/0,set_lock_button/1]). --export([init/1,terminate/3,code_change/4,format_status/2]). +-export([init/1,callback_mode/0,terminate/3,code_change/4,format_status/2]). -export([handle_event/4]). start_link(Code, LockButton) -> @@ -1295,68 +1581,68 @@ set_lock_button(LockButton) -> init({Code,LockButton}) -> process_flag(trap_exit, true), - Data = #{code => Code, remaining => undefined, timer => undefined}, - enter(?CALLBACK_MODE, {locked,LockButton}, Data, []). + Data = #{code => Code, remaining => undefined}, + {ok, {locked,LockButton}, Data}. + +callback_mode() -> + [handle_event_function,state_enter]. handle_event( {call,From}, {set_lock_button,NewLockButton}, {StateName,OldLockButton}, Data) -> - {next_state,{StateName,NewLockButton},Data, + {next_state, {StateName,NewLockButton}, Data, [{reply,From,OldLockButton}]}; handle_event( {call,From}, code_length, {_StateName,_LockButton}, #{code := Code}) -> {keep_state_and_data, - [{reply,From,length(Code)}]}; + [{reply,From,length(Code)}]}; +%% +%% State: locked handle_event( EventType, EventContent, {locked,LockButton}, #{code := Code, remaining := Remaining} = Data) -> - case {EventType,EventContent} of - {internal,enter} -> + case {EventType, EventContent} of + {enter, _OldState} -> do_lock(), - {keep_state,Data#{remaining := Code}}; - {{call,From},{button,Digit}} -> + {keep_state, Data#{remaining := Code}}; + {timeout, _} -> + {keep_state, Data#{remaining := Code}}; + {{call,From}, {button,Digit}} -> case Remaining of [Digit] -> % Complete - next_state( - {open,LockButton}, Data, - [{reply,From,ok}]); + {next_state, {open,LockButton}, Data, + [{reply,From,ok}]}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}, + {keep_state, Data#{remaining := Rest, 30000}, [{reply,From,ok}]}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}, + {keep_state, Data#{remaining := Code}, [{reply,From,ok}]} end end; +%% +%% State: open handle_event( EventType, EventContent, - {open,LockButton}, #{timer := Timer} = Data) -> - case {EventType,EventContent} of - {internal,enter} -> - Tref = erlang:start_timer(10000, self(), lock), + {open,LockButton}, Data) -> + case {EventType, EventContent} of + {enter, _OldState} -> do_unlock(), - {keep_state,Data#{timer := Tref}}; - {info,{timeout,Timer,lock}} -> - next_state({locked,LockButton}, Data, []); - {{call,From},{button,Digit}} -> + {keep_state_and_data, [{state_timeout,10000,lock}]}; + {state_timeout, lock} -> + {next_state, {locked,LockButton}, Data}; + {{call,From}, {button,Digit}} -> if Digit =:= LockButton -> - erlang:cancel_timer(Timer), - next_state( - {locked,LockButton}, Data, - [{reply,From,locked}]); + {next_state, {locked,LockButton}, Data, + [{reply,From,locked}]); true -> {keep_state_and_data, [postpone]} end end. -next_state(State, Data, Actions) -> - enter(next_state, State, Data, Actions). -enter(Tag, State, Data, Actions) -> - {Tag,State,Data,[{next_event,internal,enter}|Actions]}. - do_lock() -> io:format("Locked~n", []). do_unlock() -> @@ -1366,7 +1652,7 @@ terminate(_Reason, State, _Data) -> State =/= locked andalso do_lock(), ok. code_change(_Vsn, State, Data, _Extra) -> - {?CALLBACK_MODE,State,Data}. + {ok,State,Data}. format_status(Opt, [_PDict,State,Data]) -> StateData = {State, @@ -1393,6 +1679,7 @@ format_status(Opt, [_PDict,State,Data]) -> <!-- =================================================================== --> <section> + <marker id="Hibernation" /> <title>Hibernation</title> <p> If you have many servers in one node @@ -1418,20 +1705,21 @@ format_status(Opt, [_PDict,State,Data]) -> </p> <code type="erl"><![CDATA[ ... +%% State: open handle_event( EventType, EventContent, - {open,LockButton}, #{timer := Timer} = Data) -> - case {EventType,EventContent} of - {internal,enter} -> - Tref = erlang:start_timer(10000, self(), lock), + {open,LockButton}, Data) -> + case {EventType, EventContent} of + {enter, _OldState} -> do_unlock(), - {keep_state,Data#{timer := Tref},[hibernate]}; + {keep_state_and_data, + [{state_timeout,10000,lock},hibernate]}; ... ]]></code> <p> - The - <seealso marker="stdlib:gen_statem#type-hibernate"><c>[hibernate]</c></seealso> - action list on the last line + The atom + <seealso marker="stdlib:gen_statem#type-hibernate"><c>hibernate</c></seealso> + in the action list on the last line when entering the <c>{open,_}</c> state is the only change. If any event arrives in the <c>{open,_},</c> state, we do not bother to rehibernate, so the server stays @@ -1446,6 +1734,10 @@ handle_event( <c>{open,_}</c> state, which would clutter the code. </p> <p> + Another not uncommon scenario is to use the event time-out + to triger hibernation after a certain time of inactivity. + </p> + <p> This server probably does not use heap memory worth hibernating for. To gain anything from hibernation, your server would |