diff options
Diffstat (limited to 'system/doc')
| -rw-r--r-- | system/doc/design_principles/statem.xml | 107 |
1 files changed, 89 insertions, 18 deletions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index b44e169a9a..c44f240098 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -85,6 +85,69 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <!-- =================================================================== --> <section> + <marker id="When to use gen_statem" /> + <title>When to use gen_statem</title> + <p> + If your process logic is convenient to describe as a state machine, + and you want any of these <c>gen_statem</c> key features: + </p> + <list type="bulleted"> + <item> + Gathered callback code for each state, + regardless of + <seealso marker="#Event Types">Event Types</seealso>. + (such as <em>calls</em>, <em>casts</em> and <em>infos</em>) + </item> + <item> + <seealso marker="#Postponing Events"> + Postponing Events + </seealso> + (a substitute for selective receive) + </item> + <item> + <seealso marker="#Inserted Events"> + Inserted Events + </seealso> + (in particular purely internal events) + </item> + <item> + <seealso marker="#State Enter Calls"> + State Enter Calls + </seealso> + (callback on state entry gathered with the rest + of the state callback code) + </item> + <item> + Higher level timeouts + ( + <seealso marker="#State Time-Outs">State Time-Outs</seealso>, + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> + or + <seealso marker="#Generic Time-Outs">Generic Time-outs</seealso> + (named time-outs)) + </item> + </list> + <p> + If so, or if possibly needed in future versions, + then you should consider using <c>gen_statem</c> over + <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>. + </p> + <p> + For simple state machines not needing these fetures + <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso> + works just fine. + It also has got smaller call overhead, + but we are talking about something like 2 vs 3.3 microseconds + call roundtrip time here, so if the server callback + does just a little bit more than just replying, + or if the callback is not extremely frequent, + that difference will be hard to notice. + </p> + </section> + +<!-- =================================================================== --> + + <section> <marker id="Callback Module" /> <title>Callback Module</title> <p> @@ -160,7 +223,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> function may also return a list containing the callback mode and the atom <c>state_enter</c> in which case - <seealso marker="#State Enter Calls">state enter calls</seealso> + <seealso marker="#State Enter Calls">State Enter Calls</seealso> are activated for the callback mode. </p> @@ -176,7 +239,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <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 @@ -221,6 +284,8 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <p> The mode enables the use of non-atom states, for example, complex states or even hierarchical states. + See section + <seealso marker="#Complex State">Complex State</seealso>. If, for example, a state diagram is largely alike for the client side and the server side of a protocol, you can have a state <c>{StateName,server}</c> or @@ -344,7 +409,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <item> <p> Same as the <c>keep_state</c> or <c>keep_state_and_data</c> values, - and if <seealso marker="#State Enter Calls">state enter calls</seealso> + and if + <seealso marker="#State Enter Calls"> + State Enter Calls + </seealso> are enabled, repeat that call. </p> </item> @@ -379,7 +447,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <c>Module:init(Args)</c> </seealso> callback function is called before any - <seealso marker="#Event Handler">event handler</seealso> + <seealso marker="#Event Handler">Event Handler</seealso> is called. This function behaves like an event handler function, but gets its only argument <c>Args</c> from the <c>gen_statem</c> @@ -407,8 +475,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <marker id="State Transition Actions" /> <title>State Transition Actions</title> <p> - In the first - <seealso marker="#Event-Driven State Machines">section</seealso> + 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 @@ -644,7 +714,7 @@ StateName(EventType, EventContent, Data) -> <p> Since the state enter call is not an event there are restrictions on the allowed return value and - <seealso marker="#State Transition Actions">state transition actions</seealso>. + <seealso marker="#State Transition Actions">State Transition Actions</seealso>. You may not change the state, <seealso marker="#Postponing Events">postpone</seealso> this non-event, or @@ -657,7 +727,7 @@ StateName(EventType, EventContent, Data) -> <p> You may repeat the state enter call using the <c>{repeat_state,...}</c> return value from the - <seealso marker="#Event Handler">event handler</seealso>. + <seealso marker="#Event Handler">Event Handler</seealso>. In this case <c>OldState</c> will also be equal to the current state. </p> <p> @@ -1301,8 +1371,8 @@ open(cast, {button,_}, Data) -> ... ]]></code> <p> - An specific generic time-out can just as a - <seealso marker="#State Time-Outs">state time-out</seealso> + Specific generic time-outs can just as + <seealso marker="#State Time-Outs">State Time-Outs</seealso> be restarted or cancelled by setting it to a new time or <c>infinity</c>. </p> @@ -1397,7 +1467,7 @@ open(cast, {button,_}, Data) -> <p> Postponing is ordered by the state transition <seealso marker="#State Transition Actions"> - state transition action + State Transition Action </seealso> <c>postpone</c>. </p> @@ -1422,7 +1492,7 @@ open(cast, {button,_}, Data) -> (see section <seealso marker="#Complex State">Complex State</seealso>) with - <seealso marker="#Callback Modes">callback mode</seealso> + <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. @@ -1527,8 +1597,8 @@ do_unlock() -> </p> <p> The - <seealso marker="#State Transition Action"> - state transition action + <seealso marker="#State Transition Actions"> + State Transition Action </seealso> <c>postpone</c> is designed to model selective receives. A selective receive implicitly postpones @@ -1555,7 +1625,7 @@ do_unlock() -> (described in the next section), especially if just one or a few states has got state enter actions, this is a perfect use case for the built in - <seealso marker="#State Enter Calls">state enter calls</seealso>. + <seealso marker="#State Enter Calls">State Enter Calls</seealso>. </p> <p> You return a list containing <c>state_enter</c> from your @@ -1617,7 +1687,7 @@ open(state_timeout, lock, Data) -> to your own state machine. This can be done with the <seealso marker="#State Transition Action"> - state transition action + State Transition Action </seealso> <c>{next_event,EventType,EventContent}</c>. </p> @@ -1970,7 +2040,7 @@ format_status(Opt, [_PDict,State,Data]) -> <p> One reason to use this is when you have a state item that when changed should cancel the - <seealso marker="#State Time-Outs">state time-out</seealso>, + <seealso marker="#State Time-Outs">State Time-Out</seealso>, or one that affects the event handling in combination with postponing events. We will go for the latter and complicate the previous example @@ -2160,7 +2230,8 @@ handle_event(enter, _OldState, {open,_}, _Data) -> <c>{open,_}</c> state, which would clutter the code. </p> <p> - Another not uncommon scenario is to use the event time-out + Another not uncommon scenario is to use the + <seealso marker="#Event Time-Outs">Event Time-Out</seealso> to trigger hibernation after a certain time of inactivity. There is also a server start option <seealso marker="stdlib:gen_statem#type-hibernate_after_opt"> |