From e660572b020da58c89149c7f052c7127cc0263cb Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 29 Feb 2016 11:36:27 +0100
Subject: Remove the remove_event action and all alike

Removing events from the internal queues is not necessary with
the choosen semantics of the event queue vs. hibernate.

In an early implementation it was possible by combining
hibernate with e.g. postpone to get an event in the queue
that you would not see before processing the postponed event,
and therefore should you decide to cancel a timer it was
essential to be able to remove that unseen event from the queue.

With the choosen semantics you will have to postpone or generate
an event for it to be in the event queue, and if you e.g. postpone
a timeout event and then cancel the timer it is your mistake.
You have seen the event and should know better than to try to
cancel the timer.

So, the actions: remove_event, cancel_timer, demonitor and unlink
are now removed.

There have also been some cleanup of the timer handling code.
---
 lib/stdlib/doc/src/gen_statem.xml | 71 +++------------------------------------
 1 file changed, 4 insertions(+), 67 deletions(-)

(limited to 'lib/stdlib/doc/src/gen_statem.xml')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index bda3ef081d..04b80d29ac 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -461,24 +461,6 @@ ok
 	</p>
       </desc>
     </datatype>
-    <datatype>
-      <name name="event_predicate" />
-      <desc>
-	<p>
-	  A <c>fun()</c> of arity 2 that takes an event
-	  and returns a boolean.
-	  When used in the
-	  <seealso marker="#type-action">action()</seealso>
-	  <c>{remove_event,RemoveEventPredicate}</c>,
-	  the oldest event for which the predicate returns <c>true</c>
-	  will be removed.
-	</p>
-	<p>
-	  The predicate may <em>not</em> use a throw exception
-	  to return its result.
-	</p>
-      </desc>
-    </datatype>
     <datatype>
       <name name="callback_mode" />
       <desc>
@@ -617,13 +599,11 @@ ok
 	  counts just like a new in this respect.
 	  If the value is <c>infinity</c> no timer is started.
 	  If it is <c>0</c> the timeout event
-	  is immediately enqueued as the newest received.
+	  is immediately enqueued as the newest received
+	  (unless there are retried or inserted events to process).
 	  Also note that it is not possible nor needed
-	  to cancel this timeout using the
-	  <seealso marker="#type-action">
-	    <c>action() cancel_timer</c>
-	  </seealso>
-	  since this timeout is cancelled automatically by any other event.
+	  to cancel this timeout since it is cancelled automatically
+	  by any other event.
 	</p>
       </desc>
     </datatype>
@@ -702,49 +682,6 @@ ok
 	    should be used when you want to reliably distinguish
 	    an event inserted this way from any external event.
 	  </item>
-	  <tag><c>remove_event</c></tag>
-	  <item>
-	    Remove the oldest queued event
-	    that matches equal to <c><anno>EventType</anno></c>
-	    and <c><anno>EventContent</anno></c> or for which
-	    <c><anno>EventPredicate</anno></c>
-	    returns <c>true</c>.  Note that <c>next_event</c>
-	    and <c>postpone</c> events in the same actions list
-	    does not get into the event queue until after all actions
-	    has been done so you can not remove an event that you insert
-	    with the same actions list.  Make up your mind!
-	  </item>
-	  <tag><c>cancel_timer</c></tag>
-	  <item>
-	    Cancel the timer by calling
-	    <seealso marker="erts:erlang#cancel_timer/2">
-	      <c>erlang:cancel_timer/2</c>
-	    </seealso>
-	    with <c><anno>TimerRef</anno></c>,
-	    clean the process message queue from any late timeout message,
-	    and remove any late timeout message
-	    from the <c>gen_statem</c> event queue using
-	    <c>{remove_event,<anno>EventPredicate</anno>}</c> above.
-	    This is a convenience function that saves quite some
-	    lines of code and testing time over doing it from
-	    the primitives mentioned above.
-	  </item>
-	  <tag><c>demonitor</c></tag>
-	  <item>
-	    Like <c>cancel_timer</c> above but for
-	    <seealso marker="erts:erlang#demonitor/2">
-	      <c>demonitor/2</c>
-	    </seealso>
-	    with <c><anno>MonitorRef</anno></c>.
-	  </item>
-	  <tag><c>unlink</c></tag>
-	  <item>
-	    Like <c>cancel_timer</c> above but for
-	    <seealso marker="erts:erlang#unlink/1">
-	      <c>unlink/1</c>
-	    </seealso>
-	    with <c><anno>Id</anno></c>.
-	  </item>
 	</taglist>
       </desc>
     </datatype>
-- 
cgit v1.2.3