Improve user's guide on time-outs

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>