CVS difference for ais/ai-00297.txt

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

--- ais/ai-00297.txt	2005/03/25 02:50:32	1.20
+++ ais/ai-00297.txt	2005/04/13 05:37:09	1.21
@@ -1,4 +1,4 @@
-!standard D.7 (10)                                     05-02-25  AI95-00297/11
+!standard D.7 (10)                                     05-03-23  AI95-00297/12
 !standard D.13.1(01)
 !standard D.15(01)
 !class amendment 02-06-01
@@ -44,9 +44,9 @@
 
 D.15 Timing Events
 
-This clause introduces a language-defined child package of Ada.Real_Time
-to allow user-defined protected procedures to be executed at a specified
-time without the need to use a task or a delay statement.
+This clause describes a language-defined package to allow user-defined
+protected procedures to be executed at a specified time without the need for a
+task or a delay statement.
 
 Static Semantics
 
@@ -55,15 +55,17 @@
 package Ada.Real_Time.Timing_Events is
   type Timing_Event is limited private;
   type Timing_Event_Handler
-       is access protected procedure(Event : in out Timing_Event);
-  procedure Set_Handler(Event : in out Timing_Event;
-            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 Current_Handler(Event : Timing_Event)
+       is access protected procedure (Event : in out Timing_Event);
+  procedure Set_Handler (Event   : in out Timing_Event;
+                         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 Current_Handler (Event : Timing_Event)
            return Timing_Event_Handler;
-  procedure Cancel_Handler(Event : in out Timing_Event;
-            Cancelled : out Boolean);
+  procedure Cancel_Handler (Event     : in out Timing_Event;
+                            Cancelled : out Boolean);
   function Time_Of_Event(Event : Timing_Event) return Time;
 private
   ... -- not specified by the language
@@ -73,28 +75,29 @@
 to occur. The type Timing_Event needs finalization (see 7.6).
 
 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.
+with a non-null value of type Timing_Event_Handler and *cleared* otherwise.
+All Timing_Event objects are initially cleared.
 
+The type Timing_Event_Handler identifies a protected procedure to be executed
+by the implementation when the timing event occurs. Such a protected procedure
+is called a *handler*.
+
 Dynamic Semantics
 
-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.
+The procedures Set_Handler associate the handler Handler with the event Event;
+if Handler is null, the event is cleared, otherwise it is set. The first
+procedure Set_Handler sets the execution time for the event to be At_Time.
+The second  procedure Set_Handler sets the execution time for the event
+to be Real_Time.Clock + In_Time.
+
+A call of a procedure Set_Handler for an event that is already set replaces the
+handler and the time of execution; if Handler is not null, the event remains
+set.
+
+As soon as possible after the time set for the event, the handler is executed,
+passing the event as parameter. The 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 handler is to clear the event.
 
 AARM note
 The second sentence of this paragraph is because of a potential race
@@ -104,41 +107,39 @@
 end AARM note
 
 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.
+Set_Handler is called, a check is made that the ceiling priority of Handler.all
+is Interrupt_Priority'Last. If the check fails, Program_Error is raised.
 
-An exception propagated from a Timing_Event_Handler invoked by
-a timing event has no effect.
+If a procedure Set_Handler is called with zero or negative In_Time or with
+At_Time indicating a time in the past then the handler is executed immediately
+by the task executing the call of Set_Handler. The timing event Event is
+cleared.
 
-The function Current_Handler returns the Timing_Event_Handler associated
-with the event if the event is set, otherwise it returns null.
+The function Current_Handler returns the handler associated with the event
+Event if that event is set; otherwise it returns null.
 
-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
+The procedure Cancel_Handler clears the event if it is set. Cancelled
+is assigned True if the event was set prior to it being cleared; otherwise
 it is assigned False.
 
 The function Time_Of_Event returns the time of the event if the event is
-set, otherwise it returns Ada.Real_Time.Time_First.
+set; otherwise it returns Real_Time.Time_First.
 
-As the final step of finalization of an object of type Timing_Event,
+As the final step of the 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.
 
+An exception propagated from a handler invoked by a timing event has no effect.
+
 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.
+handler by a call of Set_Handler shall be performed atomically with
+respect to the execution of the handler.
 
 AARM note
 This prevents various race conditions. In particular it ensures that if
@@ -151,7 +152,7 @@
 Metrics
 
 The Implementation shall document the following metric:
-  An upper bound on the lateness of the execution of a registered handler.
+  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.
 
@@ -162,7 +163,7 @@
 
 Notes
 Since a call of Set_Handler is not a blocking operation, it can be
-called from within a Timing_Event_Handler.
+called from within a handler.
 
 A Timing_Event_Handler can be associated with several Timing_Event objects.
 
@@ -286,8 +287,7 @@
 end Pulser;
 
 !corrigendum D.7(10)
-!comment AI-360 replaces this restriction with this type being one that
-!comment "needs finalization".
+
 @dinsa
 @xhang<@xterm<No_Asynchronous_Control>
 There are no semantic dependences on the package Asynchronous_Task_Control.>
@@ -340,14 +340,13 @@
                 No_Task_Termination,
                 Simple_Barriers);>
 
-
 !corrigendum D.15(01)
 
 @dinsc
 
-This clause introduces a language-defined child package of Ada.Real_Time
-to allow user-defined protected procedures to be executed at a specified
-time without the need to use a task or a delay statement.
+This clause describes a language-defined package to allow user-defined
+protected procedures to be executed at a specified time without the need for a
+task or a delay statement.
 
 @i<@s8<Static Semantics>>
 
@@ -356,16 +355,18 @@
 @xcode<@b<package> Ada.Real_Time.Timing_Events @b<is>
   @b<type> Timing_Event @b<is limited private>;
   @b<type> Timing_Event_Handler
-       @b<is access protected procedure>(Event : @b<in out> Timing_Event);
-  @b<procedure> Set_Handler(Event : @b<in out> Timing_Event;
-            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> Current_Handler(Event : Timing_Event)
-           @b<return> Timing_Event_Handler;
-  @b<procedure> Cancel_Handler(Event : @b<in out> Timing_Event;
-            Cancelled : @b<out> Boolean);
-  @b<function> Time_Of_Event(Event : Timing_Event) @b<return> Time;
+       @b<is access protected procedure> (Event : @b<in out> Timing_Event);
+  @b<procedure> Set_Handler (Event   : @b<in out> Timing_Event;
+                         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> Current_Handler (Event : Timing_Event)
+       @b<return> Timing_Event_Handler;
+  @b<procedure> Cancel_Handler (Event     : @b<in out> Timing_Event;
+                            Cancelled : @b<out> Boolean);
+  @b<function> Time_Of_Event (Event : Timing_Event) @b<return> Time;
 @b<private>
   ... -- @ft<@i<not specified by the language>>
 @b<end> Ada.Real_Time.Timing_Events;>
@@ -374,65 +375,65 @@
 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 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.
+with a non-null value of type Timing_Event_Handler and @i<cleared> otherwise.
+All Timing_Event objects are initially cleared.
+
+The type Timing_Event_Handler identifies a protected procedure to be executed
+by the implementation when the timing event occurs. Such a protected procedure
+is called a @i<handler>.
 
 @i<@s8<Dynamic Semantics>>
 
-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.
+The procedures Set_Handler associate the handler Handler with the event Event;
+if Handler is @b<null>, the event is cleared, otherwise it is set. The first
+procedure Set_Handler sets the execution time for the event to be At_Time.
+The second  procedure Set_Handler sets the execution time for the event
+to be Real_Time.Clock + In_Time.
+
+A call of a procedure Set_Handler for an event that is already set replaces the
+handler and the time of execution; if Handler is not @b<null>, the event
+remains set.
+
+As soon as possible after the time set for the event, the handler is executed,
+passing the event as parameter. The 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 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.
+Handler.@b<all> 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.
+If a procedure Set_Handler is called with zero or negative In_Time or with
+At_Time indicating a time in the past then the handler is executed immediately
+by the task executing the call of Set_Handler. The timing event Event is
+cleared.
 
-An exception propagated from a Timing_Event_Handler invoked by
-a timing event has no effect.
+The function Current_Handler returns the handler associated with the event Event
+if that event is set; otherwise it returns @b<null>.
 
-The function Current_Handler returns the Timing_Event_Handler associated
-with the event if the event is set, otherwise it returns null.
-
-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
+The procedure Cancel_Handler clears the event if it is set. Cancelled
+is assigned True if the event was set prior to it being cleared; otherwise
 it is assigned False.
 
 The function Time_Of_Event returns the time of the event if the event is
-set, otherwise it returns Ada.Real_Time.Time_First.
+set; otherwise it returns Real_Time.Time_First.
 
-As the final step of finalization of an object of type Timing_Event,
+As the final step of the 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.
 
+An exception propagated from a handler invoked by a timing event has no effect.
+
 @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.
+handler by a call of Set_Handler shall be performed atomically with
+respect to the execution of the handler.
 
 @i<@s8<Metrics>>
 
@@ -448,9 +449,10 @@
 
 @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.>>
+called from within a handler.>>
 
-@xindent<@s9<A Timing_Event_Handler can be associated with several Timing_Event objects.>>
+@xindent<@s9<A Timing_Event_Handler can be associated with several Timing_Event
+objects.>>
 
 !ACATS Test
 

Questions? Ask the ACAA Technical Agent