Rework timeout handling

Handling of timers and timeouts has been cleaned up
and generalized.

Semantic change regarding state timeout zero:

Previously if one state caused a state timeout zero and
managed to stay in the same state to insert additional
timeout zero(s) in the next state callback invocation, then
there would be only one timeout zero event.  The mindset
was that the machine was faster then the timeout zero.

This has changed with the mindset that all state callback
invocations should be independent, so now the machine will
get one state timeout zero event per started state timeout
zero.

Note that just using zero timeouts is fairly esoteric...

1 files changed, 40 insertions, 26 deletions

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index fb1e4e8da2..567130875a 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -639,6 +639,20 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<list type="ordered">
 	  <item>
+            <p>
+	      If the state changes or is the initial state, and
+	      <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>
+	      are used, the <c>gen_statem</c> calls
+	      the new state callback with arguments
+	      <seealso marker="#type-state_enter">(enter, OldState, Data)</seealso>.
+	      Any 
+	      <seealso marker="#type-enter_action"><c>actions</c></seealso>
+	      returned from this call are handled as if they were
+	      appended to the actions 
+	      returned by the state callback that changed states.
+            </p>
+	  </item>
+	  <item>
 	    <p>
 	      All
               <seealso marker="#type-action">actions</seealso>
@@ -668,36 +682,36 @@ handle_event(_, _, State, Data) ->
             </p>
 	  </item>
 	  <item>
-            <p>
-	      If the state changes or is the initial state, and
-	      <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>
-	      are used, the <c>gen_statem</c> calls
-	      the new state callback with arguments
-	      <seealso marker="#type-state_enter">(enter, OldState, Data)</seealso>.
-	      Any 
-	      <seealso marker="#type-enter_action"><c>actions</c></seealso>
-	      returned from this call are handled as if they were
-	      appended to the actions 
-	      returned by the state callback that changed states.
-            </p>
-	  </item>
-	  <item>
-	    <p>
-	      If there are enqueued events the (possibly new)
-	      <seealso marker="#state callback">state callback</seealso>
-	      is called with the oldest enqueued event,
-	      and we start again from the top of this list.
-	    </p>
-	  </item>
-	  <item>
 	    <p>
 	      Timeout timers 
               <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
 	      and 
               <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>
-	      are handled.  This may lead to a time-out zero event
-	      being generated to the
+	      are handled.  Time-outs with zero time are guaranteed to be
+	      delivered to the state machine before any external
+	      not yet received event so if there is such a timeout requested,
+	      the corresponding time-out zero event is enqueued as
+	      the newest event.
+	    </p>
+	    <p>
+	      Any event cancels an
+              <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>
+	      so a zero time event time-out is only generated
+	      if the event queue is empty.
+	    </p>
+	    <p>
+	      A state change cancels a
+              <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
+	      and any new transition option of this type
+	      belongs to the new state.
+	    </p>
+	  </item>
+	  <item>
+	    <p>
+	      If there are enqueued events the
 	      <seealso marker="#state callback">state callback</seealso>
+	      for the possibly new state
+	      is called with the oldest enqueued event,
 	      and we start again from the top of this list.
 	    </p>
 	  </item>
@@ -802,7 +816,7 @@ handle_event(_, _, State, Data) ->
 	<p>
 	  Setting this timer while it is running will restart it with
 	  the new time-out value.  Therefore it is possible to cancel
-	  this timeout by setting it to <c>infinity</c>.
+	  this time-out by setting it to <c>infinity</c>.
 	</p>
       </desc>
     </datatype>
@@ -1130,7 +1144,7 @@ handle_event(_, _, State, Data) ->
 	  <c><anno>Timeout</anno></c> can also be a tuple
 	  <c>{clean_timeout,<anno>T</anno>}</c> or
 	  <c>{dirty_timeout,<anno>T</anno>}</c>, where
-	  <c><anno>T</anno></c> is the timeout time.
+	  <c><anno>T</anno></c> is the time-out time.
 	  <c>{clean_timeout,<anno>T</anno>}</c> works like
 	  just <c>T</c> described in the note above
 	  and uses a proxy process for <c>T &lt; infinity</c>,