CVS difference for ais/ai-00297.txt

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

--- ais/ai-00297.txt	2004/07/27 23:00:55	1.16
+++ ais/ai-00297.txt	2004/11/14 06:37:09	1.17
@@ -1,5 +1,6 @@
-!standard D.7 (00)                                     04-03-25  AI95-00297/09
-!standard D.15(00)
+!standard D.7 (10)                                     04-11-12  AI95-00297/10
+!standard D.13(01)
+!standard D.15(01)
 !class amendment 02-06-01
 !status Amendment 200Y 04-06-24
 !status ARG Approved 8-0-0  04-06-14
@@ -18,7 +19,7 @@
 
 !problem
 
-An exploration of various flexible scheduling schemes, 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 than that in effect when
@@ -29,8 +30,8 @@
 More generally, Ada provides only one mechanism for associating the execution
 of code with points in time. A lower level primitive would increase the
 applicability of the Ada language. A protected procedure can currently be
-associated with interrupt events; the proposal allows similar functionality
-for timing events.
+associated with interrupt events; this proposal similarly allows a protected
+procedure to be associated with timing events.
 
 !proposal
 
@@ -58,7 +59,6 @@
             At_Time : in Time; Handler: in Timing_Event_Handler);
   procedure Set_Handler(Event : in out Timing_Event;
             In_Time: in Time_Span; Handler: in Timing_Event_Handler);
-  function Is_Handler_Set(Event : Timing_Event) return Boolean;
   function Current_Handler(Event : Timing_Event)
            return Timing_Event_Handler;
   procedure Cancel_Handler(Event : in out Timing_Event;
@@ -68,74 +68,91 @@
   ... -- not specified by the language
 end Ada.Real_Time.Timing_Events;
 
-The type Timing_Event needs finalization (see 7.6).
+The type Timing_Event represents a time in the future when an event is
+to occur. The type Timing_Event needs finalization (see 7.6).
 
-An object of type Timing_Event is said to be set if it has a
-registered Timing_Event_Handler. An object is said to be cleared
-if it has no registered Timing_Event_Handler. All Timing_Event objects
-are initially cleared.
+An object of type Timing_Event is said to be *set* if it is associated
+with a (non-null) Timing_Event_Handler and *cleared* otherwise. All
+Timing_Event objects are initially cleared. The Timing_Event_Handler
+identifies a protected procedure to be executed by the implementation
+when the timing event occurs.
 
 Dynamic Semantics
 
-A call to a Set_Handler procedure returns after the Timing_Event_Handler
-denoted by Handler is registered. The first Set_Handler procedure
-registers the Timing_Event_Handler for execution at time At_Time.
-The second Set_Handler procedure registers the Timing_Event_Handler
-for execution at time Ada.Real_Time.Clock + In_Time;
-
-A call to a Set_Handler procedure for a Timing_Event that is already
-set will initially cancel the earlier registration.
-The Timing_Event denoted by Event remains set.
-
-A call of either Set_Handler procedure is not a potentially blocking
-operation.
-
-As soon as possible after the time registered for the event, the
-Timing_Event_Handler procedure is executed. 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.
+The procedures Set_Handler associate a Timing_Event_Handler with a
+Timing_Event. The first procedure Set_Handler sets the
+Timing_Event_Handler for execution at time At_Time. The second
+procedure Set_Handler sets the Timing_Event_Handler for execution at
+time Ada.Real_Time.Clock + In_Time.
+
+A call of a procedure Set_Handler for a Timing_Event that is already
+set replaces the handler and the time of execution and the Timing_Event
+remains set. A call with a null value of Handler clears the event.
+
+As soon as possible after the time set for the event, the
+Timing_Event_Handler is executed. The Timing_Event_Handler is only
+executed if the timing event is in the set state at the time of
+execution. The initial action of the execution of the
+Timing_Event_Handler is to clear the event.
+
+AARM note
+The second sentence of this paragraph is because of a potential race
+condition. The time might expire and yet before the handler is executed,
+some task could call Cancel_Handler (or equivalently call Set_Handler
+with a null parameter) and thus clear the handler.
+end AARM note
 
-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
+If the Ceiling_Locking policy (see D.3) is in effect when a procedure
+Set_Handler is called, a check is made that the ceiling priority of
 Timing_Event_Handler is Interrupt_Priority'last. If the check fails,
 Program_Error is raised.
 
-If a Set_Handler procedure is called with zero or negative In_Time or with
-At_Time indicating a time in the past then Timing_Event_Handler is
-executed immediately by the task executing the Set_Handler call.
-The Timing_Event denoted by Event is cleared and the handler is not
-registered.
+If a procedure Set_Handler is called with zero or negative In_Time
+or with At_Time indicating a time in the past then Timing_Event_Handler
+is executed immediately by the task executing the call of Set_Handler.
+The Timing_Event denoted by Event is cleared.
 
 An exception propagated from a Timing_Event_Handler invoked by
 a timing event has no effect.
 
-A call to Is_Handler_Set returns True if Event is set;
-otherwise it returns False.
+The function Current_Handler returns the Timing_Event_Handler associated
+with the event if the event is set, otherwise it returns null.
 
-A call to Current_Handler returns with the current Timing_Event_Handler.
-If the Timing_Event denoted by Event is not set, Current_Handler returns
-null.
-
-A call to Cancel_Handler returns after the Timing_Event denoted by Event
-is cleared. Cancelled is assigned True if Event was set prior to it
-being cleared; otherwise the parameter is assigned False.
+The procedure Cancel_Handler clears the event if it was set. Cancelled
+is assigned True if the event was set prior to it being cleared, otherwise
+it is assigned False.
 
-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.
+The function Time_Of_Event returns the time of the event if the event is
+set, otherwise it returns Ada.Real_Time.Time_First.
 
 As the final step of finalization of an object of type Timing_Event,
 the Timing_Event is cleared.
 
-If several timing events are registered for the same time,
-they are executed in FIFO order of registration.
+If several timing events are set for the same time, they are executed in
+FIFO order of being set.
 
+Implementation Requirements
+
+For a given Timing_Event object, the implementation shall perform the
+operations declared in this package atomically with respect to any of
+these operations on the same Timing_Event object. The replacement of a
+handler, by a call of Set_Handler, shall be performed atomically with
+respect to the execution of the Timing_Event_Handler.
+
+AARM note
+This prevents various race conditions. In particular it ensures that if
+an event occurs when Set_Handler is changing the handler then either the
+new or old handler is executed in response to the appropriate event. It
+is never possible for a new handler to be executed in response to an old
+event.
+end AARM note
+
 Metrics
 
 The Implementation shall document the following metric:
   An upper bound on the lateness of the execution of a registered handler.
-  That is, the maximum time between when a handler is actually executed
-  and the time specified in the registration of that handler.
+  That is, the maximum time between when a handler is actually executed and
+  the time specified when the event was set.
 
 Implementation Advice
 
@@ -143,9 +160,11 @@
 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.
+Since a call of Set_Handler is not a blocking operation, it can be
+called from within a Timing_Event_Handler.
 
+A Timing_Event_Handler can be associated with several Timing_Event objects.
+
 Add to D.7 a new restriction identifier
 
 No_Local_Timing_Events
@@ -164,7 +183,7 @@
 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 implementations a low
-priority task coming off a delay queue will cause priority inversion.
+priority task coming off a delay queue causes priority inversion.
 
 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
@@ -215,7 +234,7 @@
 
   procedure Call_in is
   begin
-    Set_Handler(Fifty_Mil_Event, TS, Watchdog.Timer'access);
+    Set_Handler(Fifty_Mil_Event, TS, Watchdog.Timer'Access);
     -- note, this call to Set_Handler cancels the previous call
   end Call_in;
 end Watchdog;
@@ -249,7 +268,7 @@
   begin
     Pulse_Hardware;
     Next_Time := Clock + Pulse_Interval;
-    Set_Handler(Pulse, Next_Time, Pulser.Timer'access);
+    Set_Handler(Pulse, Next_Time, Pulser.Timer'Access);
   end Start;
 
   procedure Stop is
@@ -261,7 +280,7 @@
   begin
     Pulse_Hardware;
     Next_Time := Next_Time + Pulse_Interval;
-    Set_Handler(Event, Next_Time, Pulser.Timer'access);
+    Set_Handler(Event, Next_Time, Pulser.Timer'Access);
   end Timer;
 end Pulser;
 
@@ -340,7 +359,6 @@
             At_Time : @b<in> Time; Handler: @b<in> Timing_Event_Handler);
   @b<procedure> Set_Handler(Event : @b<in out> Timing_Event;
             In_Time: @b<in> Time_Span; Handler: @b<in> Timing_Event_Handler);
-  @b<function> Is_Handler_Set(Event : Timing_Event) @b<return> Boolean;
   @b<function> Current_Handler(Event : Timing_Event)
            @b<return> Timing_Event_Handler;
   @b<procedure> Cancel_Handler(Event : @b<in out> Timing_Event;
@@ -350,79 +368,87 @@
   ... -- not specified by the language
 @b<end> Ada.Real_Time.Timing_Events;>
 
-The type Timing_Event needs finalization (see 7.6).
+The type Timing_Event represents a time in the future when an event is
+to occur. The type Timing_Event needs finalization (see 7.6).
 
-An object of type Timing_Event is said to be @i<set> if it has a
-registered Timing_Event_Handler. An object is said to be @i<cleared>
-if it has no registered Timing_Event_Handler. All Timing_Event objects
-are initially cleared.
+An object of type Timing_Event is said to be @i<set> if it is associated
+with a (non-null) Timing_Event_Handler and @i<cleared> otherwise. All
+Timing_Event objects are initially cleared. The Timing_Event_Handler
+identifies a protected procedure to be executed by the implementation
+when the timing event occurs.
 
 @i<@s8<Dynamic Semantics>>
-
-A call to a Set_Handler procedure returns after the Timing_Event_Handler
-denoted by Handler is registered. The first Set_Handler procedure
-registers the Timing_Event_Handler for execution at time At_Time.
-The second Set_Handler procedure registers the Timing_Event_Handler
-for execution at time Ada.Real_Time.Clock + In_Time;
-
-A call of either Set_Handler procedure is not a potentially blocking
-operation.
-
-As soon as possible after the time registered for the event, the
-Timing_Event_Handler procedure is executed. 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
-Timing_Event_Handler is Interrupt_Priority'last. If the check fails,
-Program_Error is raised.
 
-If a Set_Handler procedure is called with zero or negative In_Time or with
-At_Time indicating a time in the past then Timing_Event_Handler is
-executed immediately by the task executing the Set_Handler call.
-The Timing_Event denoted by Event is cleared and the handler is not
-registered.
+The procedures Set_Handler associate a Timing_Event_Handler with a
+Timing_Event. The first procedure Set_Handler sets the
+Timing_Event_Handler for execution at time At_Time. The second
+procedure Set_Handler sets the Timing_Event_Handler for execution at
+time Ada.Real_Time.Clock + In_Time.
+
+A call of a procedure Set_Handler for a Timing_Event that is already
+set replaces the handler and the time of execution and the Timing_Event
+remains set. A call with a null value of Handler clears the event.
+
+As soon as possible after the time set for the event, the
+Timing_Event_Handler is executed. The Timing_Event_Handler is only
+executed if the timing event is in the set state at the time of
+execution. The initial action of the execution of the
+Timing_Event_Handler is to clear the event.
+
+If the Ceiling_Locking policy (see D.3) is in effect when a procedure
+Set_Handler is called, a check is made that the ceiling priority of
+Timing_Event_Handler is Interrupt_Priority'Last. If the
+check fails, Program_Error is raised.
+
+If a procedure Set_Handler is called with zero or negative In_Time
+or with At_Time indicating a time in the past then Timing_Event_Handler
+is executed immediately by the task executing the call of Set_Handler.
+The Timing_Event denoted by Event is cleared.
 
 An exception propagated from a Timing_Event_Handler invoked by
 a timing event has no effect.
 
-A call to Is_Handler_Set returns True if Event is set;
-otherwise it returns False.
+The function Current_Handler returns the Timing_Event_Handler associated
+with the event if the event is set, otherwise it returns null.
 
-A call to Current_Handler returns with the current Timing_Event_Handler.
-If the Timing_Event denoted by Event is not set, Current_Handler returns
-null.
-
-A call to Cancel_Handler returns after the Timing_Event denoted by Event
-is cleared. Cancelled is assigned True if Event was set prior to it
-being cleared; otherwise the parameter is assigned False.
+The procedure Cancel_Handler clears the event if it was set. Cancelled
+is assigned True if the event was set prior to it being cleared, otherwise
+it is assigned False.
 
-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.
+The function Time_Of_Event returns the time of the event if the event is
+set, otherwise it returns Ada.Real_Time.Time_First.
 
 As the final step of finalization of an object of type Timing_Event,
 the Timing_Event is cleared.
+
+If several timing events are set for the same time, they are executed in
+FIFO order of being set.
 
-If several timing events are registered for the same time,
-they are executed in FIFO order of registration.
+@i<@s8<Implementation Requirements>>
 
+For a given Timing_Event object, the implementation shall perform the
+operations declared in this package atomically with respect to any of
+these operations on the same Timing_Event object. The replacement of a
+handler, by a call of Set_Handler, shall be performed atomically with
+respect to the execution of the Timing_Event_Handler.
+
 @i<@s8<Metrics>>
 
-The Implementation shall document the following metric:
-@xbullet<An upper bound on the lateness of the execution of a registered
-handler. That is, the maximum time between when a handler is actually executed
-and the time specified in the registration of that handler.>
+The implementation shall document the following metric:
+@xbullet<An upper bound on the lateness of the execution of a handler.
+That is, the maximum time between when a handler is actually executed and
+the time specified when the event was set.>
 
 @i<@s8<Implementation Advice>>
 
 The protected handler procedure should be executed directly by the
 real-time clock interrupt mechanism.
+
+@xindent<@s9<NOTES@hr
+Since a call of Set_Handler is not a blocking operation, it can be
+called from within a Timing_Event_Handler.>>
 
-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.
+@xindent<@s9<A Timing_Event_Handler can be associated with several Timing_Event objects.>>
 
 !ACATS Test
 

Questions? Ask the ACAA Technical Agent