aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/design_principles/statem.xml
diff options
context:
space:
mode:
authorRaimo Niskanen <[email protected]>2016-11-08 15:55:06 +0100
committerRaimo Niskanen <[email protected]>2016-11-08 15:55:06 +0100
commit251012d820ab75833c6dd787b2450a94e1bb5aa2 (patch)
tree161bfe8bed859d584746c77d7edbcc52e07eedbc /system/doc/design_principles/statem.xml
parente29dad91f685a05e5d11380bd5cae8434790d685 (diff)
parent167c57b1472746d01ff10f759e18e17bf5fb4fb6 (diff)
downloadotp-251012d820ab75833c6dd787b2450a94e1bb5aa2.tar.gz
otp-251012d820ab75833c6dd787b2450a94e1bb5aa2.tar.bz2
otp-251012d820ab75833c6dd787b2450a94e1bb5aa2.zip
Merge branch 'raimo/gen_statem-improvements/OTP-13929' into maint
* raimo/gen_statem-improvements/OTP-13929: Log terminate to sys debug Optimize event timeout Rework timeout handling Clarify the chapter 'Postponing Events' (ERL-284) Fix doc and type for state enter calls
Diffstat (limited to 'system/doc/design_principles/statem.xml')
-rw-r--r--system/doc/design_principles/statem.xml29
1 files changed, 18 insertions, 11 deletions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index bece95e6b8..f627145f9f 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -1015,17 +1015,24 @@ 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.
- </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>.
+ 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>
+ 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>