CVS difference for ais/ai-00297.txt

Differences between 1.2 and version 1.3
Log of other versions for file ais/ai-00297.txt

--- ais/ai-00297.txt	2002/07/23 01:05:25	1.2
+++ ais/ai-00297.txt	2002/10/01 03:08:54	1.3
@@ -1,4 +1,4 @@
-!standard D.8 (00)                                     02-06-01  AI95-00297/01
+!standard D.8 (00)                                     02-09-05  AI95-00297/02
 !class amendment 02-06-01
 !status work item 02-06-01
 !status received 02-06-01
@@ -13,7 +13,7 @@
 
 !problem
 
-An exploration of various flexible scheduling scheme, for example imprecise
+An exploration of various flexible scheduling schemes, for example imprecise
 computation, has illustrated the need a) to asynchronously change the
 priority of a task at a particular future time, and b) to allow tasks to
 come off the delay queue at a different priority to that in effect when
@@ -31,27 +31,33 @@
 
 A child package of Ada.Real_Time is proposed.
 
-with Ada.Real_Time; use Ada.Real_Time;
 package Ada.Real_Time.Timing_Events is
 
   type Timing_Event is limited private;
 
-  type Parameterless_Handler is access protected procedure;
+  type Timing_Event_Handler
+    is access protected procedure(TE : in out Timing_Event);
 
-  procedure Set_Handler(TE : in out Timing_Event; At_Time : Time;
-             Handler: Parameterless_Handler);
+  procedure Set_Handler(TE : in out Timing_Event; At_Time : in Time;
+             Handler: in Timing_Event_Handler);
 
-  procedure Set_Handler(TE : in out Timing_Event; In_Time: Time_Span;
-             Handler: Parameterless_Handler);
+  procedure Set_Handler(TE : in out Timing_Event; In_Time: in Time_Span;
+             Handler: in Timing_Event_Handler);
 
   function Is_Handler_Set(TE : Timing_Event) return boolean;
 
+  function Current_Handler(TE : Timing_Event) return Timing_Event_Handler;
+
   procedure Cancel_Handler(TE : in out Timing_Event);
 
+  function Time_Of_Event(TE : Timing_Event) return Time;
+
 private
   ... -- not specified by the language
 end Ada.Real_Time.Timing_Events;
 
+The protected procedure corresponding to the Timing_Event_Handler
+must be a library level definition.
 
 A call to a Set_Handler procedure returns when the Handler is registered.
 
@@ -80,7 +86,9 @@
 
 A call to Is_Handler_Set following a call to Cancel_Handler for the
 same timing_event will return false. A call to Cancel_Handler will
-have no effect if the timing event is not set.
+have no effect if the timing event is not set. A call to Current_Handler
+for a timing event that is not set will return null. A call to
+Time_Of_Event for a timing event that is not set will return Time_First.
 
 A number of timing events registered for the same time will execute in FIFO
 order. Note, all will be executed before any other application code.
@@ -107,7 +115,9 @@
 
 !example
 
-The first example is a watchdog timer. Here a condition is tested every 50
+The attached appendix has an extended example but uses an earlier
+definition of the feature. Two further illustrations are
+given here. First, a watchdog timer. Here a condition is tested every 50
 milliseconds. If the condition has not been called during this time an
 alarm handling task is released.
 
@@ -116,10 +126,10 @@
 with System; use System;
 ...
 
-protected Watchdog is
+protected Watchdog is  -- library level declaration
   pragma Interrupt_Priority (Interrupt_Priority'Last);
   entry Alarm_Control;    -- called by alarm handling task
-  procedure Timer;        -- timer event code
+  procedure Timer(TE : in out Timing_Event);    -- timer event code
   procedure Call_in;      -- called by application code every 50ms if alive
 private
   Alarm : Boolean := False;
@@ -134,7 +144,7 @@
     Alarm := False;
   end Alarm_Control;
 
-  procedure Timer is
+  procedure Timer(TE : in out Timing_Event) is
   begin
     Alarm := True;
   end Timer;
@@ -158,11 +168,11 @@
 with System; use System;
 ...
 
-protected Pulser is
+protected Pulser is -- library level
   pragma Interrupt_Priority (Interrupt_Priority'Last);
   procedure Start;
   procedure Stop;
-  procedure Timer;
+  procedure Timer(TE : in out Timing_Event);
 private
   Next_Time : Time;
 end Pulser;
@@ -183,15 +193,14 @@
     Cancel_Handler(Pulse);
   end Stop;
 
-  procedure Timer is
+  procedure Timer(TE : in out Timing_Event) is
   begin
     Pulse_Hardware;
     Next_Time := Next_Time + Pulse_Interval;
-    Set_Handler(Pulse, Next_Time, Pulser.Timer'access);
+    Set_Handler(TE, Next_Time, Pulser.Timer'access);
   end Timer;
 end Pulser;
 
-Additional examples can be found in the appendix.
 
 !ACATS Test
 
@@ -860,3 +869,138 @@
 Ada Workshop, pages 5-8. ACM Ada Letters, 2001.
 
 ****************************************************************
+
+From: Tucker Taft
+Sent: Thursday, September 5, 2002  9:56 AM
+
+Alan Burns wrote:
+> ...
+> !proposal
+>
+> A child package of Ada.Real_Time is proposed.
+>
+> package Ada.Real_Time.Timing_Events is
+>
+>   type Timing_Event is limited private;
+>
+>   type Timing_Event_Handler(TE : in out Timing_Event)
+>     is access protected procedure;
+
+This should be:
+
+    type Timing_Event_Handler is
+      access protected procedure(TE: in out Timing_Event);
+
+>
+>   procedure Set_Handler(TE : in out Timing_Event; At_Time : Time;
+>              Handler: Timing_Event_Handler);
+>
+>   procedure Set_Handler(TE : in out Timing_Event; In_Time: Time_Span;
+>              Handler: Timing_Event_Handler);
+
+Once you give a mode for one parameter, it seems to be "good form"
+to use explicit rather than implicit "in" thereafter.
+Hence, I would recommend adding "in" after "*_Time:" and "Handler:".
+
+>
+>   function Is_Handler_Set(TE : Timing_Event) return boolean;
+>
+>   function Current_Handler(TE : Timing_Event) return Timing_Event_Handler;
+>
+>   procedure Cancel_Handler(TE : in out Timing_Event);
+>
+>   function Time_Of_Event(TE : Timing_Event) return Time;
+>
+> private
+>   ... -- not specified by the language
+> end Ada.Real_Time.Timing_Events;
+> ...
+
+****************************************************************
+
+From: Alan Burns
+Sent: Thursday, September 5, 2002  10:09 AM
+
+Thanks for stopping silly mistake with the parameter.
+
+I'll note you advice about in paramters
+
+****************************************************************
+
+From: Robert A. Duff
+Sent: Thursday, September 5, 2002  5:38 PM
+
+> Once you give a mode for one parameter, it seems to be "good form"
+> to use explicit rather than implicit "in" thereafter.
+> Hence, I would recommend adding "in" after "*_Time:" and "Handler:".
+
+For what it's worth, I don't agree with that advice.  My advice is:
+Never use 'in'; always make it implicit.
+
+I don't see the point in Tucker's advice on this point.
+
+****************************************************************
+
+From: Robert Dewar
+Sent: Thursday, September 5, 2002  7:10 PM
+
+I strongly agree with Bob here, I find gratuitous IN mode indications
+(such as those that infest the RM) annoying :-)
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Thursday, September 5, 2002  9:07 PM
+
+I think consistency with the rest of the RM is appropriate.
+The general rule in the RM seems to be *always* use
+explicit parameter modes on procedures.  For functions,
+either always or never in a given package.
+
+I don't believe we should be debating our own
+personal styles here, but rather the de-facto "RM style."
+That's what I meant by "good form."
+
+****************************************************************
+
+From: Robert A. Duff
+Sent: Friday, September 6, 2002  7:39 PM
+
+OK, fine.  You confused me by saying it has something to do with the
+*previous* parameter, which is a rule I had never heard of.
+
+****************************************************************
+
+From: Robert Dewar
+Sent: Friday, September 6, 2002  4:28 PM
+
+<<I don't believe we should be debating our own
+personal styles here, but rather the de-facto "RM style."
+That's what I meant by "good form.">>
+
+Yes, that makes sense, but it means that pushing a personal style of
+giving modes once one mode has been given is also inappropriate :-)
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Friday, September 6, 2002  8:59 PM
+
+Yes, I agree.  I was really making an imperfect guess
+what was the RM style.  I took a closer look afterward
+and discovered that we always used modes for procedures,
+and always or never used them for functions in a given
+package.
+
+****************************************************************
+
+From: Robert Dewar
+Sent: Friday, September 6, 2002  9:25 PM
+
+For the record, the reason I prefer to leave out IN (and object to the
+implied recommendation in the RM) is that IN parameters are indeed the
+normal case. OUT and IN OUT parameters are the exceptional cases, and
+I prefer to use the keywords to point out the exceptional cases.
+
+****************************************************************
+

Questions? Ask the ACAA Technical Agent