CVS difference for ais/ai-00297.txt

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

--- ais/ai-00297.txt	2003/10/29 22:54:11	1.10
+++ ais/ai-00297.txt	2003/12/07 05:00:31	1.11
@@ -1,8 +1,8 @@
-!standard D.7 (00)                                     03-07-01  AI95-00297/06
+!standard D.7 (00)                                     03-12-03  AI95-00297/07
 !standard D.15(00)
 !class amendment 02-06-01
-!status Amendment 200Y 03-07-01
-!status ARG Approved 10-0-3  03-07-01
+!status Amendment 200Y 03-06-23
+!status ARG Approved 10-0-3  03-06-23
 !status work item 02-06-01
 !status received 02-06-01
 !priority High
@@ -19,7 +19,7 @@
 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
+come off the delay queue at a different priority than that in effect when
 the task was delayed. This functionality can only be achieved by the use
 of a 'minder' high priority task that makes the necessary priority changes
 to its client. This is an inefficient and inelegant solution.
@@ -71,21 +71,20 @@
 if it has no registered Timing_Event_Handler. All Timing_Event objects
 are initially cleared.
 
-A call to a Set_Handler procedure returns after the Timing_Event
-denoted by Event is set.
-
 Dynamic Semantics
 
+A call to a Set_Handler procedure returns after the Timing_Event
+denoted by Event is registered.
+
 A call of either Set_Handler procedure is not a potentially blocking
-operation and hence can be called from within an object of type
-Timing_Event_Handler.
+operation.
 
-Following a call of a Set_Handler procedure, at a time no earlier than
-that specified by the time parameter, the Timing_Event_Handler procedure
-is executed. The rules governing timing accuracy are the same as in D.9.
-The Timing_Event_Handler is only executed if the timing event is set
-at the time of execution. Following the execution of the
-Timing_Event_Handler the Timing_Event denoted by Event is cleared.
+Following a call of a Set_Handler procedure, at a time no earlier than and as
+soon as possible after the time specified by the time parameter, the
+Timing_Event_Handler procedure is executed. The rules governing timing accuracy
+are the same as in D.9. The Timing_Event_Handler is only executed if the timing
+event is set at the time of execution. As the initial action of the execution
+of the Timing_Event_Handler the Timing_Event denoted by Event is cleared.
 
 If the Ceiling_Locking policy (see D.3) is in effect when a Set_Handler
 procedure is called, a check is made that the ceiling priority of
@@ -112,7 +111,7 @@
 being cleared; otherwise the parameter is assigned False.
 
 A call to Current_Handler returns with the current Timing_Event_Handler.
-If the Timing_Event denoted Event is not set, Current_Handler returns null.
+If the Timing_Event denoted by Event is not set, Current_Handler returns null.
 
 A call to Time_Of_Event returns with the time of Event.
 If Event is not set, Time_Of_Event returns Ada.Real_Time.Time_First.
@@ -121,13 +120,16 @@
 the Timing_Event is cleared.
 
 If several timing events are registered for the same time,
-they are executed in FIFO order.
+they are executed in FIFO order of registration.
 
 Implementation Advice
 
 The protected handler procedure should be executed directly by the
 real-time clock interrupt mechanism.
 
+Notes
+Since a call to Set_Handling is a not a blocking operation, it can be
+called from within an object of type Timing_Event_Handler.
 
 Add to D.7 a new restriction identifier
 
@@ -142,19 +144,24 @@
 The proposal provides an effective solution for some specific scheduling
 algorithms. Moreover it provides an additional paradigm for programming
 real-time systems. The use of timing events may reduce the number of tasks
-in a program and hence reduce the overheads with context switching.
+in a program and hence reduce the overheads of context switching.
 All tasks will suffer interference from timing events, hence they give rise
 to priority inversion. They are thus not an alternative to the use of
 time-triggered tasks, but provide an efficient means of programming short
-time-triggered procedures. Note, with all current implementation a low
+time-triggered procedures. Note, with all current implementations a low
 priority task coming off a delay queue will cause priority inversion.
 
-The type, timing_event, provides an easy means for cancelling an event. It also
+The type, Timing_Event, provides an easy means for cancelling an event. It also
 allows an implementation to allocate an object that will be linked into the
 delay queue. An implementation that links task control blocks (TCB) within its
 delay queue will, in effect, define a pseudo TCB for each declared timing
 event.
 
+The No_Local_Timing_Events restriction is added to Ravenscar as the Ravenscar
+profile does not allow any local entities (those with limited lifetimes) that
+use the task runtime (that is, no local protected objects, no local tasks,
+etc.). A Timing_Event should be treated similarly.
+
 !example
 
 The attached appendix has an extended example but uses an earlier
@@ -171,7 +178,7 @@
 protected Watchdog is
   pragma Interrupt_Priority (Interrupt_Priority'Last);
   entry Alarm_Control;    -- called by alarm handling task
-  procedure Timer(TE : in out Timing_Event);    -- timer event code
+  procedure Timer(Event : in out Timing_Event);    -- timer event code
   procedure Call_in;      -- called by application code every 50ms if alive
 private
   Alarm : Boolean := False;
@@ -186,7 +193,7 @@
     Alarm := False;
   end Alarm_Control;
 
-  procedure Timer(TE : in out Timing_Event) is
+  procedure Timer(Event : in out Timing_Event) is
   begin
     Alarm := True;
   end Timer;
@@ -214,7 +221,7 @@
   pragma Interrupt_Priority (Interrupt_Priority'Last);
   procedure Start;
   procedure Stop;
-  procedure Timer(TE : in out Timing_Event);
+  procedure Timer(Event : in out Timing_Event);
 private
   Next_Time : Time;
 end Pulser;
@@ -235,11 +242,11 @@
     Cancel_Handler(Pulse);
   end Stop;
 
-  procedure Timer(TE : in out Timing_Event) is
+  procedure Timer(Event : in out Timing_Event) is
   begin
     Pulse_Hardware;
     Next_Time := Next_Time + Pulse_Interval;
-    Set_Handler(TE, Next_Time, Pulser.Timer'access);
+    Set_Handler(Event, Next_Time, Pulser.Timer'access);
   end Timer;
 end Pulser;
 
@@ -333,21 +340,21 @@
 if it has no registered Timing_Event_Handler. All Timing_Event objects
 are initially cleared.
 
-A call to a Set_Handler procedure returns after the Timing_Event
-denoted by Event is set.
-
 @i<@s8<Dynamic Semantics>>
 
+A call to a Set_Handler procedure returns after the Timing_Event
+denoted by Event is registered.
+
 A call of either Set_Handler procedure is not a potentially blocking
 operation and hence can be called from within an object of type
 Timing_Event_Handler.
 
-Following a call of a Set_Handler procedure, at a time no earlier than
-that specified by the time parameter, the Timing_Event_Handler procedure
-is executed. The rules governing timing accuracy are the same as in D.9.
-The Timing_Event_Handler is only executed if the timing event is set
-at the time of execution. Following the execution of the
-Timing_Event_Handler the Timing_Event denoted by Event is cleared.
+Following a call of a Set_Handler procedure, at a time no earlier than and as
+soon as possible after the time specified by the Time parameter, the
+Timing_Event_Handler procedure is executed. The rules governing timing accuracy
+are the same as in D.9. The Timing_Event_Handler is only executed if the timing
+event is set at the time of execution. As the initial action of the execution
+of the Timing_Event_Handler the Timing_Event denoted by Event is cleared.
 
 If the Ceiling_Locking policy (see D.3) is in effect when a Set_Handler
 procedure is called, a check is made that the ceiling priority of
@@ -374,7 +381,7 @@
 being cleared; otherwise the parameter is assigned False.
 
 A call to Current_Handler returns with the current Timing_Event_Handler.
-If the Timing_Event denoted Event is not set, Current_Handler returns null.
+If the Timing_Event denoted by Event is not set, Current_Handler returns null.
 
 A call to Time_Of_Event returns with the time of Event.
 If Event is not set, Time_Of_Event returns Ada.Real_Time.Time_First.
@@ -383,14 +390,18 @@
 the Timing_Event is cleared.
 
 If several timing events are registered for the same time,
-they are executed in FIFO order.
+they are executed in FIFO order of registration.
 
 @i<@s8<Implementation Advice>>
 
 The protected handler procedure should be executed directly by the
 real-time clock interrupt mechanism.
 
+NOTES@hr
+Since a call to Set_Handling is a not a blocking operation, it can be
+called from within an object of type Timing_Event_Handler.
 
+
 !ACATS Test
 
 ACATS test(s) need to be created.
@@ -1225,6 +1236,186 @@
 hard work. Ravenscar runtimes presumably would do something different
 (depending on the restriction), but they typically are completely different
 than a full runtime anyway.
+
+****************************************************************
+
+From: Alan Burns
+Sent: Saturday, November 8, 2003  3:13 AM
+
+A minor issue was raised by someone at the IRTAW reading the AI on
+timing events. I would hope we could deal with this during
+editorial review.
+
+Under the dynamic semantics we have:
+
+>>
+Following a call of a Set_Handler procedure, at a time no earlier than
+that specified by the time parameter, the Timing_Event_Handler procedure
+is executed. The rules governing timing accuracy are the same as in D.9.
+The Timing_Event_Handler is only executed if the timing event is set
+at the time of execution. Following the execution of the
+Timing_Event_Handler the Timing_Event denoted by Event is cleared.
+<<
+
+The last sentance is the issue.
+
+A common use of timing events will be to reset the event for some
+time in the future while handling the current event. The semantics
+are therefore more straighforward if the Event is cleared as the
+initial action of executing the handler (allowing it to be
+set again during the execution of the handler). The current last sentance
+implies clearing could happen as the final act which is not what
+was intended.
+
+I would propose changing the last sentance to:
+
+>>
+As the initial action of the execution of the
+Timing_Event_Handler the Timing_Event denoted by Event is cleared.
+<<
+
+This makes is it clear.
+
+Acceptable?
+
+****************************************************************
+
+From: Erhard Ploedereder
+Sent: Sunday, November 23, 2003  4:46 PM
+
+I have some major editorial problems with the !wording. For example:
+
+The last paragraph of the static semantics talks about something that
+is clearly dynamic semantics.
+
+Nowhere do I find words that really explain the semantics of
+Set_Handler (e.g., that it registers the handler). There is talk
+of a time parameter, but there are two versions, one using type Time,
+the other Time_Span; the difference is never explained in words.
+
+The term "can be called from within an object of type X" doesn't
+mean anything in LRM-ese, especially when X is an access type.
+
+There is a bit of a contradiction on the negative time rule, which
+specifies that the handler gets executed by the calling task, while
+elsewhere (far away), the semantics say that the call returns after
+the Timing Event is set. I hate to have to gather the semantics of
+an interface piecemeal from 3 different places in the section.
+
+In short, while the intent of the AI looks o.k., the wording needs
+work to match LM style of presenting packages.
+
+****************************************************************
+
+From: Alan Burns
+Sent: Monday, November 24, 2003  5:56 PM
+
+As this is 'wording' I'll leave the detailed changes up to
+Randy - but here are some observations
+
+>
+> The last paragraph of the static semantics talks about something that
+> is clearly dynamic semantics.
+
+agreed
+
+>
+> Nowhere do I find words that really explain the semantics of
+> Set_Handler (e.g., that it registers the handler). There is talk
+> of a time parameter, but there are two versions, one using type Time,
+> the other Time_Span; the difference is never explained in words.
+
+the first words after the package do clearly imply an object of type
+Timing_Event is set if it has a registered Timing_Event_Handler.
+Is it not clear that Time is absolute and Time_Span relative? and both
+define the time for the event to fire
+
+>
+> The term "can be called from within an object of type X" doesn't
+> mean anything in LRM-ese, especially when X is an access type.
+
+yes, I'll leave that to expert LRM-ese editor
+
+>
+> There is a bit of a contradiction on the negative time rule, which
+> specifies that the handler gets executed by the calling task, while
+> elsewhere (far away), the semantics say that the call returns after
+> the Timing Event is set. I hate to have to gather the semantics of
+> an interface piecemeal from 3 different places in the section.
+
+There are a number of points to make about the semantics, they
+cannot all be in the same paragraph. As it is the normal behaviours
+are closer together. But obviously others (editors for example)
+may feel a different order would be prefered.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Monday, November 24, 2003  8:34 PM
+
+Alan said, responding to Erhard:
+
+> > The term "can be called from within an object of type X" doesn't
+> > mean anything in LRM-ese, especially when X is an access type.
+>
+> yes, I'll leave that to expert LRM-ese editor
+
+Gee, thanks. :-)
+
+The entire "can be called part" seems to be a note; it isn't normative in
+any way. I'd either put it in the AARM or as a RM note; either way, I don't
+have to rewrite it (other than to add "designated"). Any preference on
+which?
+
+****************************************************************
+
+From: Alan Burns
+Sent: Tuesday, November 25, 2003  2:36 AM
+
+I agree this isn't normative. I would prefer to see a RM note.
+
+****************************************************************
+
+From: Robert Dewar
+Sent: Tuesday, November 25, 2003  6:01 AM
+
+It should be an RM note. The AARM has no formal status, and should not be
+used for any important information.
+
+****************************************************************
+
+From: Robert A. Duff
+Sent: Sunday, November 30, 2003  5:34 PM
+
+Neither RM notes nor AARM annotations have "normative" status under ISO
+rules.  During the Ada 9X project, the primary criterion for choosing
+between the two was that RM notes should be of use to Ada programmers,
+whereas AARM annotations should be of use to compiler writers and
+language designers.
+
+Sorry for being overly emotional, but I take a little bit of offense at
+the implication that AARM annotations are not "important information".
+I'm a bit touchy on the subject, having expended a lot of energy trying
+to put information useful, and even "important", to compiler writers
+and language designers into the AARM!  ;-)
+
+****************************************************************
+
+From: Robert Dewar
+Sent: Sunday, November 30, 2003 10:47 PM
+
+That's a very reasonable viewpoint, but all too often information ends
+up in the AARM which is indeed useful to Ada programmers. And I think
+this particular case is an example.
+
+****************************************************************
+
+From: Robert A. Duff
+Sent: Monday, December 1, 2003  8:12 AM
+
+Yeah, there was a lot of pressure to keep the RM as small as possible,
+so we probably did put some things in the AARM when an RM note would
+have been more appropriate.
 
 ****************************************************************
 

Questions? Ask the ACAA Technical Agent