diff options
| -rw-r--r-- | system/doc/design_principles/statem.xml | 161 |
1 files changed, 136 insertions, 25 deletions
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 29e19163a5..07b4284cb8 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -546,7 +546,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> If set postpone the current event, see section - <seealso marker="#Postponing Events">Postponing Events</seealso> + <seealso marker="#Postponing Events">Postponing Events</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-hibernate"> @@ -557,41 +557,44 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> If set hibernate the <c>gen_statem</c>, treated in section - <seealso marker="#Hibernation">Hibernation</seealso> + <seealso marker="#Hibernation">Hibernation</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-state_timeout"> - <c>{state_timeout, Time}</c> + <c>{state_timeout, EventContent, Time}</c> </seealso> <br /> - <c>{state_timeout, Time, Opts}</c> + <c>{state_timeout, EventContent, Time, Opts}</c> </tag> <item> - Start a state time-out, read more in section - <seealso marker="#State Time-Outs">State Time-Outs</seealso> + Start a state time-out, read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#State Time-Outs">State Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-generic_timeout"> - <c>{{timeout, Name}, Time}</c> + <c>{{timeout, Name}, EventContent, Time}</c> </seealso> <br /> - <c>{{timeout, Name}, Time, Opts}</c> + <c>{{timeout, Name}, EventContent, Time, Opts}</c> </tag> <item> - Start a generic time-out, read more in section - <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso> + Start a generic time-out, read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-event_timeout"> - <c>{timeout, Time}</c> + <c>{timeout, EventContent, Time}</c> </seealso> <br /> - <c>{timeout, Time, Opts}</c><br /> + <c>{timeout, EventContent, Time, Opts}</c><br /> <c>Time</c> </tag> <item> - Start an event time-out, see more in section - <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> + Start an event time-out, see more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-reply_action"> @@ -600,7 +603,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Reply to a caller, mentioned at the end of section - <seealso marker="#All State Events">All State Events</seealso> + <seealso marker="#All State Events">All State Events</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-action"> @@ -609,7 +612,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Generate the next event to handle, see section - <seealso marker="#Inserted Events">Inserted Events</seealso> + <seealso marker="#Inserted Events">Inserted Events</seealso>. </item> </taglist> <p> @@ -678,10 +681,12 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-state_timeout"> + <seealso marker="stdlib:gen_statem#type-timeout_action"> <c>{state_timeout,Time,EventContent}</c> </seealso> - state timer timing out. + state timer timing out. Read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#State Time-Outs">State Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-timeout_event_type"> @@ -690,10 +695,12 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-generic_timeout"> + <seealso marker="stdlib:gen_statem#type-timeout_action"> <c>{{timeout,Name},Time,EventContent}</c> </seealso> - generic timer timing out. + generic timer timing out. Read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-timeout_event_type"> @@ -702,11 +709,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-event_timeout"> + <seealso marker="stdlib:gen_statem#type-timeout_action"> <c>{timeout,Time,EventContent}</c> </seealso> (or its short form <c>Time</c>) - event timer timing out. + event timer timing out. Read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-event_type"> @@ -714,10 +723,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> </tag> <item> - Generated by <em>state transition</em> - <seealso marker="stdlib:gen_statem#type-action">action</seealso> - <c>{next_event,internal,EventContent}</c>. + Generated by <em>transition action</em> + <seealso marker="stdlib:gen_statem#type-enter_action"><c>{next_event,internal,EventContent}</c></seealso>. All <em>event types</em> above can also be generated using + the <c>next_event</c> action: <c>{next_event,EventType,EventContent}</c>. </item> </taglist> @@ -783,6 +792,108 @@ StateName(EventType, EventContent, Data) -> <!-- =================================================================== --> <section> + <marker id="Time-Outs" /> + <title>Time-outs</title> + <p> + Time-outs in <c>gen_statem</c> are started from a + <seealso marker="#Transition Actions"> + <em>transition action</em> + </seealso> + during a state transition that is when exiting from the + <seealso marker="#State Callback"><em>state callback</em></seealso>. + </p> + <p> + There are 3 types of time-outs in <c>gen_statem</c>: + </p> + <taglist> + <tag> + <seealso marker="stdlib:gen_statem#type-state_timeout"> + <c>state_timeout</c> + </seealso> + </tag> + <item> + There is one + <seealso marker="#State Time-Outs">State Time-Out</seealso> + that is automatically cancelled by a <em>state change</em>. + </item> + <tag> + <seealso marker="stdlib:gen_statem#type-generic_timeout"> + <c>{timeout, Name}</c> + </seealso> + </tag> + <item> + There are any number of + <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso> + differing by their <c>Name</c>. + They have no automatic cancelling. + </item> + <tag> + <seealso marker="stdlib:gen_statem#type-event_timeout"> + <c>timeout</c> + </seealso> + </tag> + <item> + There is one + <seealso marker="#Event Time-Outs">Event Time-Out</seealso> + that is automatically cancelled by any event. + Note that + <seealso marker="#Postponing Events">postponed </seealso> + and + <seealso marker="#Inserted Events">inserted</seealso> + events cancel this timeout just as external events. + </item> + </taglist> + <p> + When a time-out is started any running time-out with the same tag, + <c>state_timeout</c>, <c>{timeout, Name}</c> or <c>timeout</c>, + is cancelled, that is the time-out is restarted with the new time. + </p> + <p> + All time-outs has got an <c>EventContent</c> that is part of the + <seealso marker="#Transition Actions"> + <em>transition action</em> + </seealso> + that starts the time-out. + Different <c>EventContent</c>s does not create different time-outs. + The <c>EventContent</c> is delivered to the + <seealso marker="#State Callback"><em>state callback</em></seealso> + when the time-out expires. + </p> + <section> + <marker id="Cancelling a Time-Out" /> + <title>Cancelling a Time-Out</title> + <p> + If a time-out is started with the time <c>infinity</c> it will + never time out, in fact it will not even be started, and any + running time-out with the same tag will be cancelled. + The <c>EventContent</c> will in this case be ignored, + so why not set it to <c>undefined</c>. + </p> + </section> + <section> + <marker id="Time-Out Zero" /> + <title>Time-Out Zero</title> + <p> + If a time-out is started with the time <c>0</c> it will + actually not be started. Instead the time-out event will + immediately be inserted to be processed after any events + already enqueued, and before any not yet received external events. + Note that some time-outs are automatically cancelled + so if you for example combine + <seealso marker="#Postponing Events">postponing</seealso> + an event in a <em>state change</em> with starting an + <seealso marker="#Event Time-Outs">event time-out</seealso> + with time <c>0</c> there will be no timeout event inserted + since the event time-out is cancelled by the postponed + event that is delivered due to the state change. + </p> + </section> + </section> + + +<!-- =================================================================== --> + + <section> <marker id="Example" /> <title>Example</title> <p> |