CVS difference for ais/ai-00307.txt

Differences between 1.13 and version 1.14
Log of other versions for file ais/ai-00307.txt

--- ais/ai-00307.txt	2004/11/14 06:37:11	1.13
+++ ais/ai-00307.txt	2005/04/13 05:37:12	1.14
@@ -1,4 +1,4 @@
-!standard D.14 (00)                                  04-11-11  AI95-00307/10
+!standard D.14 (00)                                  05-03-16  AI95-00307/11
 !standard D.14.1 (00)
 !class amendment 02-08-28
 !status Amendment 200Y 04-06-24
@@ -74,7 +74,7 @@
 
 D.14 Execution Time
 
-This clause specifies an execution-time clock package.
+This clause describes a language-defined package to measure execution time.
 
 Static Semantics
 
@@ -91,7 +91,7 @@
    CPU_Tick : constant Time_Span;
 
    function Clock
-     (T : Ada.Task_Identification.Task_ID
+     (T : Ada.Task_Identification.Task_Id
           := Ada.Task_Identification.Current_Task)
      return CPU_Time;
 
@@ -114,17 +114,16 @@
    ... --  not specified by the language
 end Ada.Execution_Time;
 
-Execution time or CPU time of a given task is defined as the time spent
-by the system executing that task, including the time spent executing
-run-time or system services on behalf of it. The mechanism used to
-measure execution time is implementation defined. It is implementation
-defined which task, if any, is charged the execution time that is
-consumed by interrupt handlers and run-time services on behalf of the
-system.
-
-The type CPU_Time represents the execution time of a task. The set of
-values of the type CPU_Time corresponds one-to-one with an
-implementation-defined range of mathematical integers.
+The *execution time* or CPU time of a given task is defined as the time spent
+by the system executing that task, including the time spent executing run-time
+or system services on its behalf. The mechanism used to measure execution time
+is implementation defined. It is implementation defined which task, if any, is
+charged the execution time that is consumed by interrupt handlers and run-time
+services on behalf of the system.
+
+The type CPU_Time represents the execution time of a task. The set of values of
+this type corresponds one-to-one with an implementation-defined range of
+mathematical integers.
 
 The CPU_Time value I represents the half-open execution-time interval
 that starts with I*CPU_Time_Unit and is limited by
@@ -139,7 +138,7 @@
 Dynamic Semantics
 
 CPU_Time_Unit is the smallest amount of execution time representable
-by the CPU_Time type; it is expressed in seconds. A CPU clock tick is an
+by the CPU_Time type; it is expressed in seconds. A *CPU clock tick* is an
 execution time interval during which the clock value (as observed by
 calling the Clock function) remains constant. CPU_Tick is the average
 length of such intervals.
@@ -147,7 +146,9 @@
 The effects of the operators on CPU_Time and Time_Span are as for the
 operators defined for integer types.
 
-The function Clock returns the current execution time of the task T.
+The function Clock returns the current execution time of the task identified by
+T; Tasking_Error is raised if that task has terminated; Program_Error is raised
+if the value of T is Task_Identification.Null_Task_Id.
 
 The effects of the Split and Time_Of operations are defined as
 follows, treating values of type CPU_Time, Time_Span, and
@@ -157,22 +158,15 @@
 returned by Time_Of(SC,TS) is the execution-time value T such that
 T*CPU_Time_Unit=SC*1.0 + TS*CPU_Time_Unit.
 
-For all the operations and types defined in this package, Tasking_Error
-is raised if the task identified by T has terminated. Program_Error
-is raised if the value of T is Null_Task_ID.
-
 Erroneous Execution
 
-If a value of Task_ID is passed as a parameter to any of the subprograms
-of this package or used to define an object declared by a type provided by
-this package (or any language-defined child package of this package) and the
-corresponding task object no longer exists, the execution of the
-program is erroneous.
+For a call of Clock, if the task identified by T no longer exists, the
+execution of the program is erroneous.
 
 Implementation Requirements
 
 The range of CPU_Time values shall be sufficient to uniquely represent
-the range of execution times from the task start-up to 50 years of
+the range of execution times from the task creation to 50 years of
 execution time later. CPU_Tick shall be no greater than 1 millisecond.
 
 Documentation Requirements
@@ -221,20 +215,17 @@
 
 D.14.1 Execution Time Timers
 
-This clause specifies a child of Execution_Time that provides a
-facility for calling a handler when a task has used a defined quantity
-of CPU time.
+This clause describes a language-defined package that provides a facility for
+calling a handler when a task has used a defined amount of CPU time.
 
 Static Semantics
 
 The following language-defined library package exists:
 
-with Ada.Task_Identification;
 with System;
-with Ada.Real_Time; use Ada.Real_Time;
 package Ada.Execution_Time.Timers is
 
-   type Timer (T : access Ada.Task_Identification.Task_ID) is
+   type Timer (T : access Ada.Task_Identification.Task_Id) is
       limited private;
 
    type Timer_Handler is access protected procedure (TM : in out Timer);
@@ -242,15 +233,17 @@
    Min_Handler_Ceiling : constant System.Any_Priority :=
     implementation-defined;
 
-   procedure Set_Handler(TM: in out Timer; In_Time : in Time_Span;
+   procedure Set_Handler (TM      : in out Timer;
+                          In_Time : in Time_Span;
                           Handler : in Timer_Handler);
-   procedure Set_Handler(TM: in out Timer; At_Time : in CPU_Time;
+   procedure Set_Handler (TM      : in out Timer;
+                          At_Time : in CPU_Time;
                           Handler : in Timer_Handler);
-   function Current_Handler(TM: Timer) return Timer_Handler;
-   procedure Cancel_Handler(TM : in out Timer;
-                            Cancelled : out Boolean);
+   function Current_Handler (TM: Timer) return Timer_Handler;
+   procedure Cancel_Handler (TM        : in out Timer;
+                             Cancelled : out Boolean);
 
-   function Time_Remaining(TM : Timer) return Time_Span;
+   function Time_Remaining (TM : Timer) return Time_Span;
 
    Timer_Resource_Error : exception;
 
@@ -263,66 +256,77 @@
 identifies the task concerned. The type Timer needs finalization (see 7.6).
 
 An object of type Timer is said to be *set* if it is associated with a
-(non-null) Timer_Handler and *cleared* otherwise. All Timer objects are
-initially cleared. The Timer_Handler identifies a protected procedure to
-be executed by the implementation when the timer expires.
+non-null value of type Timer_Handler and *cleared* otherwise. All Timer
+objects are initially cleared.
+
+The type Timer_Handler identifies a protected procedure to be executed by the
+implementation when the timer expires. Such a protected procedure is called a
+*handler*.
 
 Dynamic Semantics
 
 When a Timer object is created, or upon the first call of a Set_Handler
-procedure with the timer as parameter, the resources required to operate a
-CPU-time timer based on the associated execution-time clock will be
-allocated and initialized. If this operation would exceed the limit of the
-maximum number of timers in the system, Timer_Resource_Error is raised.
-
-A call of a procedure Set_Handler associates a Timer_Handler with a Timer.
-The first procedure Set_Handler loads the timer with an interval specified
-by the Time_Span parameter. In this state the timer counts execution time
-and, when the CPU clock associated with the timer measures the passage of
-In_Time, it is said to have expired. The second procedure Set_Handler
-loads the timer with the absolute value specified by At_Time. In this
-state the timer monitors execution time and, when the CPU clock associated
-with the timer reaches the value At_Time, it is said to have expired. If
-the value of At_Time had already been reached by the clock at the time of
-the call, the timer is said to have expired.
-
-A call of a procedure Set_Handler for a Timer that is already set replaces
-the handler and the time of execution and the Timer remains set. A call
-with a null value of Handler clears the Timer.
-
-When a Timer expires, the associated protected procedure Timer_Handler is
-executed with a parameter equal to the Timer. The initial action of the
-execution of the Timer_Handler is to clear the event.
+procedure with the timer as parameter, the resources required to operate an
+execution-time timer based on the associated execution-time clock are allocated and
+initialized. If this operation would exceed the available resources,
+Timer_Resource_Error is raised.
+
+The procedures Set_Handler associate the handler Handler with the timer TM; if
+Handler is null, the timer is cleared, otherwise it is set. The first
+procedure Set_Handler loads the timer TM with an interval specified by the
+Time_Span parameter. In this mode, when the execution time of the task
+identified by TM.T has increased by In_Time, the timer TM is said to have
+expired. The second procedure Set_Handler loads the timer TM with the absolute
+value specified by At_Time. In this mode, when the the execution time of the
+task identified by TM.T reaches At_Time, the timer TM is said to have *expired*;
+if the value of At_Time has already been reached when Set_Handler is called,
+the timer TM is said to be expired.
+
+A call of a procedure Set_Handler for a timer that is already set replaces the
+handler and the (absolute or relative) execution time; if Handler is not null,
+the timer remains set.
+
+When a timer expires, the associated handler is executed, passing the timer as
+parameter. The initial action of the execution of the handler is to clear the
+event.
 
-The procedure Cancel_Handler clears the timer if it was set. Cancelled is
-assigned True if the timer was set prior to it being cleared, otherwise it
-is assigned False.
+The function Current_Handler returns the handler associated with the timer
+TM if that timer is set; otherwise it returns null.
 
-The function Current_Handler returns the Timer_Handler associated with the
-timer if the timer is set, otherwise it returns null.
+The procedure Cancel_Handler clears the timer if it is set. Cancelled is
+assigned True if the timer was set prior to it being cleared; otherwise it
+is assigned False.
 
-The function Time_Remaining returns the CPU time interval that remains
-until the timer will expire if the timer is set, otherwise it returns
+The function Time_Remaining returns the execution time interval that remains
+until the timer TM would expire, if that timer is set; otherwise it returns
 Time_Span_Zero.
+
+The constant Min_Handler_Ceiling is the priority value that ensures
+that no ceiling violation would occur, were a handler to be executed.
 
-The constant Min_Handler_Ceiling is the priority value that will ensure
-that no ceiling violation will occur when a handler is executed.
+For all the subprograms defined in this package, Tasking_Error
+is raised if the task identified by TM.T has terminated, and Program_Error
+is raised if the value of TM.T is Task_Identification.Null_Task_Id.
+
+An exception propagated from a handler invoked as part of the expiration of a
+timer has no effect.
+
+Erroneous Execution
 
-For all the operations and types defined in this package, Tasking_Error
-is raised if the task identified by T has terminated. Program_Error
-is raised if the value of T is Null_Task_ID.
+For a call of any of the subprograms defined in this package, if the task
+identified by TM.T no longer exists, the execution of the program is erroneous.
 
 Implementation Requirements
 
 For a given Timer object, the implementation shall perform the operations
 declared in this package atomically with respect to any of these
 operations on the same Timer object. The replacement of a handler by a
-call of Set_Handler, shall be performed atomically with respect to the
-execution of the Timer_Handler.
+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
- an event occurs when Set_Handler is changing the handler then either
+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.
@@ -406,7 +410,7 @@
 
 Without these operations, a library implementation of the package on top
 of the POSIX execution-time services will have to include a component
-derived from Ada.Finalization.Controlled in the protected type to ensure
+derived from Finalization.Controlled in the protected type to ensure
 that appropriate initialization and finalization are made. This should not
 cause a hardship; restricted runtime implementations may have to resort to
 some "magic", but most implementations will not need extra support. In
@@ -553,7 +557,7 @@
 
 @dinsc
 
-This clause specifies an execution-time clock package.
+This clause describes a language-defined package to measure execution time.
 
 @i<@s8<Static Semantics>>
 
@@ -570,7 +574,7 @@
    CPU_Tick : @b<constant> Time_Span;
 
    @b<function> Clock
-     (T : Ada.Task_Identification.Task_ID
+     (T : Ada.Task_Identification.Task_Id
           := Ada.Task_Identification.Current_Task)
      @b<return> CPU_Time;
 
@@ -593,17 +597,16 @@
    ... --  not specified by the language
 @b<end> Ada.Execution_Time;>
 
-Execution time or CPU time of a given task is defined as the time spent
-by the system executing that task, including the time spent executing
-run-time or system services on behalf of it. The mechanism used to
-measure execution time is implementation defined. It is implementation
-defined which task, if any, is charged the execution time that is
-consumed by interrupt handlers and run-time services on behalf of the
-system.
-
-The type CPU_Time represents the execution time of a task. The set of
-values of the type CPU_Time corresponds one-to-one with an
-implementation-defined range of mathematical integers.
+The @i<execution time> or CPU time of a given task is defined as the time spent by
+the system executing that task, including the time spent executing run-time or
+system services on its behalf. The mechanism used to measure execution time is
+implementation defined. It is implementation defined which task, if any, is
+charged the execution time that is consumed by interrupt handlers and run-time
+services on behalf of the system.
+
+The type CPU_Time represents the execution time of a task. The set of values of
+this type corresponds one-to-one with an implementation-defined range of
+mathematical integers.
 
 The CPU_Time value I represents the half-open execution-time interval
 that starts with I*CPU_Time_Unit and is limited by
@@ -618,7 +621,7 @@
 @i<@s8<Dynamic Semantics>>
 
 CPU_Time_Unit is the smallest amount of execution time representable
-by the CPU_Time type; it is expressed in seconds. A CPU clock tick is an
+by the CPU_Time type; it is expressed in seconds. A @i<CPU clock tick> is an
 execution time interval during which the clock value (as observed by
 calling the Clock function) remains constant. CPU_Tick is the average
 length of such intervals.
@@ -626,7 +629,9 @@
 The effects of the operators on CPU_Time and Time_Span are as for the
 operators defined for integer types.
 
-The function Clock returns the current execution time of the task T.
+The function Clock returns the current execution time of the task identified by
+T; Tasking_Error is raised if that task has terminated; Program_Error is raised
+if the value of T is Task_Identification.Null_Task_Id.
 
 The effects of the Split and Time_Of operations are defined as
 follows, treating values of type CPU_Time, Time_Span, and
@@ -636,17 +641,10 @@
 returned by Time_Of(SC,TS) is the execution-time value T such that
 T*CPU_Time_Unit=SC*1.0 + TS*CPU_Time_Unit.
 
-For all the operations and types defined in this package, Tasking_Error
-is raised if the task identified by T has terminated. Program_Error
-is raised if the value of T is Null_Task_ID.
-
 @i<@s8<Erroneous Execution>>
 
-If a value of Task_ID is passed as a parameter to any of the subprograms
-of this package or used to define an object declared by a type provided by
-this package (or any language-defined child package of this package) and the
-corresponding task object no longer exists, the execution of the
-program is erroneous.
+For a call of Clock, if the task identified by T no longer exists, the
+execution of the program is erroneous.
 
 @i<@s8<Implementation Requirements>>
 
@@ -699,36 +697,36 @@
 
 @dinsc
 
-This clause specifies a child of Execution_Time that provides a
-facility for calling a handler when a task has used a defined quantity
-of CPU time.
+This clause describes a language-defined package that provides a facility for
+calling a handler when a task has used a defined amount of CPU time.
 
 @i<@s8<Static Semantics>>
 
 The following language-defined library package exists:
 
-@xcode<@b<with> Ada.Task_Identification;
 @b<with> System;
-@b<with> Ada.Real_Time; @b<use> Ada.Real_Time;
 @b<package> Ada.Execution_Time.Timers @b<is>
 
-   @b<type> Timer (T : @b<access> Ada.Task_Identification.Task_ID) @b<is>
+   @b<type> Timer (T : @b<access> Ada.Task_Identification.Task_Id) @b<is>
       @b<limited private>;
 
-   @b<type> Timer_Handler @b<is access protected procedure> (TM : @b<in out> Timer);
+   @b<type> Timer_Handler @b<is>
+      @b<access protected procedure> (TM : @b<in out> Timer);
 
    Min_Handler_Ceiling : @b<constant> System.Any_Priority :=
     @ft<@i<implementation-defined>>;
 
-   @b<procedure> Set_Handler(TM: @b<in out> Timer; In_Time : @b<in> Time_Span;
-                       Handler : @b<in> Timer_Handler);
-   @b<procedure> Set_Handler(TM: @b<in out> Timer; At_Time : @b<in> CPU_Time;
-                       Handler : @b<in> Timer_Handler);
-   @b<function> Current_Handler(TM: Timer) @b<return> Timer_Handler;
-   @b<procedure> Cancel_Handler(TM : @b<in out> Timer;
-                                 Cancelled : @b<in out> Boolean);
+   @b<procedure> Set_Handler (TM      : @b<in out> Timer;
+                          In_Time : @b<in> Time_Span;
+                          Handler : @b<in> Timer_Handler);
+   @b<procedure> Set_Handler (TM      : @b<in out> Timer;
+                          At_Time : @b<in> CPU_Time;
+                          Handler : @b<in> Timer_Handler);
+   @b<function> Current_Handler (TM : Timer) @b<return> Timer_Handler;
+   @b<procedure> Cancel_Handler (TM        : @b<in out> Timer;
+                             Cancelled : @b<in out> Boolean);
 
-   @b<function> Time_Remaining(TM : Timer) @b<return> Time_Span;
+   @b<function> Time_Remaining (TM : Timer) @b<return> Time_Span;
 
    Timer_Resource_Error : @b<exception>;
 
@@ -740,65 +738,75 @@
 capable of detecting execution time overruns. The access discriminant T
 identifies the task concerned. The type Timer needs finalization (see 7.6).
 
-An object of type Timer is said to be set if it is associated with a
-(non-null) Timer_Handler and cleared otherwise. All Timer objects are
-initially cleared. The Timer_Handler identifies a protected procedure to
-be executed by the implementation when the timer expires.
+An object of type Timer is said to be @i<set> if it is associated with a
+non-null value of type Timer_Handler and @i<cleared> otherwise. All Timer
+objects are initially cleared.
+
+The type Timer_Handler identifies a protected procedure to be executed by the
+implementation when the timer expires. Such a protected procedure is called a
+@i<handler>.
 
 @i<@s8<Dynamic Semantics>>
 
 When a Timer object is created, or upon the first call of a Set_Handler
 procedure with the timer as parameter, the resources required to operate a
-CPU-time timer based on the associated execution-time clock will be
-allocated and initialized. If this operation would exceed the limit of the
-maximum number of timers in the system, Timer_Resource_Error is raised.
-
-A call of a procedure Set_Handler associates a Timer_Handler with a Timer.
-The first procedure Set_Handler loads the timer with an interval specified
-by the Time_Span parameter. In this state the timer counts execution time
-and, when the CPU clock associated with the timer measures the passage of
-In_Time, it is said to have expired. The second procedure Set_Handler
-loads the timer with the absolute value specified by At_Time. In this
-state the timer monitors execution time and, when the CPU clock associated
-with the timer reaches the value At_Time, it is said to have expired. If
-the value of At_Time had already been reached by the clock at the time of
-the call, the timer is said to have expired.
-
-A call of a procedure Set_Handler for a Timer that is already set replaces
-the handler and the time of execution and the Timer remains set. A call
-with a null value of Handler clears the Timer.
-
-When a Timer expires, the associated protected procedure Timer_Handler is
-executed with a parameter equal to the Timer. The initial action of the
-execution of the Timer_Handler is to clear the event.
+execution-time timer based on the associated execution-time clock are allocated
+and initialized. If this operation would exceed the available resources,
+Timer_Resource_Error is raised.
+
+The procedures Set_Handler associate the handler Handler with the timer TM; if
+Handler is @b<null>, the timer is cleared, otherwise it is set. The first
+procedure Set_Handler loads the timer TM with an interval specified by the
+Time_Span parameter. In this mode, when the execution time of the task
+identified by TM.T has increased by In_Time, the timer TM is said to have
+expired. The second procedure Set_Handler loads the timer TM with the absolute
+value specified by At_Time. In this mode, when the the execution time of the
+task identified by TM.T reaches At_Time, the timer TM is said to have
+@i<expired>; if the value of At_Time has already been reached when Set_Handler
+is called, the timer TM is said to be expired.
+
+A call of a procedure Set_Handler for a timer that is already set replaces the
+handler and the (absolute or relative) execution time; if Handler is not
+@b<null>, the timer remains set.
+
+When a timer expires, the associated handler is executed, passing the timer as
+parameter. The initial action of the execution of the handler is to clear the
+event.
 
-The procedure Cancel_Handler clears the timer if it was set. Cancelled is
-assigned True if the timer was set prior to it being cleared, otherwise it
-is assigned False.
+The function Current_Handler returns the handler associated with the timer
+TM if that timer is set; otherwise it returns @b<null>.
 
-The function Current_Handler returns the Timer_Handler associated with the
-timer if the timer is set, otherwise it returns null.
+The procedure Cancel_Handler clears the timer if it is set. Cancelled is
+assigned True if the timer was set prior to it being cleared; otherwise it
+is assigned False.
 
-The function Time_Remaining returns the CPU time interval that remains
-until the timer will expire if the timer is set, otherwise it returns
+The function Time_Remaining returns the execution time interval that remains
+until the timer TM would expire, if that timer is set; otherwise it returns
 Time_Span_Zero.
+
+The constant Min_Handler_Ceiling is the priority value that ensures
+that no ceiling violation would occur, were a handler to be executed.
 
-The constant Min_Handler_Ceiling is the priority value that will ensure
-that no ceiling violation will occur when a handler is executed.
+For all the subprograms defined in this package, Tasking_Error
+is raised if the task identified by TM.T has terminated, and Program_Error
+is raised if the value of TM.T is Task_Identification.Null_Task_Id.
 
-For all the operations and types defined in this package, Tasking_Error
-is raised if the task identified by T has terminated. Program_Error
-is raised if the value of T is Null_Task_ID.
+An exception propagated from a handler invoked as part of the expiration of a
+timer has no effect.
 
+@i<@s8<Erroneous Execution>>
+
+For a call of any of the subprograms defined in this package, if the task
+identified by TM.T no longer exists, the execution of the program is erroneous.
+
 @i<@s8<Implementation Requirements>>
 
 For a given Timer object, the implementation shall perform the operations
 declared in this package atomically with respect to any of these
 operations on the same Timer object. The replacement of a handler by a
-call of Set_Handler, shall be performed atomically with respect to the
-execution of the Timer_Handler.
+call of Set_Handler shall be performed atomically with respect to the
+execution of the handler.
 
-
 When an object of type Timer is finalized, the system resources used by
 the timer shall be deallocated.
 
@@ -809,7 +817,6 @@
 
 @xindent<@s9<NOTES@hr
 A Timer_Handler can be associated with several Timer objects.>>
-
 
 !ACATS test
 

Questions? Ask the ACAA Technical Agent