CVS difference for ais/ai-00307.txt

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

--- ais/ai-00307.txt	2003/05/24 00:51:41	1.3
+++ ais/ai-00307.txt	2003/06/17 21:18:37	1.4
@@ -1,4 +1,4 @@
-!standard 9.6 (00)                                   03-01-15  AI95-00307/02
+!standard 9.6 (00)                                   03-06-10  AI95-00307/03
 !standard D.9 (00)
 !class amendment 02-08-28
 !status work item 02-08-28
@@ -61,14 +61,14 @@
 
 !proposal
 
-Proposal: Execution time provided as a library package
-------------------------------------------------------
+(See wording.)
 
-A new section D.X is proposed for Annex D:
+!wording
 
-D.X Execution Time
-------------------
+Add new section D.14.
 
+D.14 Execution Time
+
 This clause specifies an execution-time clock package.
 
 Static Semantics
@@ -110,17 +110,21 @@
       procedure Arm (Interval : Time_Span);
       procedure Arm (Abs_Time : CPU_Time);
       procedure Disarm;
-      entry Time_Exceeded;
-      function Time_Was_Exceeded return Boolean;
+      entry Timer_Expired;
+      function Timer_Has_Expired return Boolean;
       function Time_Remaining return Time_Span;
    private
       ... --  not specified by the language
    end Timer;
 
-   Time_Error : exception;
-   -- may be raised by Timer.Time_Exceeded, Timer.Time_Was_exceeded,
+   Timer_Error : exception;
+   -- may be raised by Timer.Timer_Expired, Timer.Time_Has_Expired,
    -- and Timer.Time_Remaining
 
+   Timer_Resource_Error : exception;
+   -- may be raised on the declaration of a Timer or calls to
+   -- either Arm
+
 private
    ... --  not specified by the language
 end Ada.Real_Time.Execution_Time;
@@ -129,7 +133,7 @@
 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. The implementation shall also define to whom will be charged
+defined. It is implementation defined to whom will be charged
 the execution time that is consumed by interrupt handlers and run-time
 services on behalf of the system.
 
@@ -141,12 +145,14 @@
 that starts with I*CPU_Time_Unit and is limited by
 (I+1)*CPU_Time_Unit, where CPU_Time_Unit is an implementation-defined
 real number. For each task, the execution time value is set to zero at
-some unspecified point between the task creation and the end of the
+some unspecified point between the task creation and the start of the
 task's activation.
 
 CPU_Time_First and CPU_Time_Last are the smallest and largest values
 of the Time type, respectively.
 
+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
 execution time interval during which the clock value (as observed by
@@ -173,20 +179,18 @@
 time clock, which is the clock of the task specified by the access
 discriminant T. This protected object type has visible operations for
 the application tasks to arm or disarm a timer, and to determine
-whether a timer has expired or not (Time_Was_Exceeded). In addition,
-Timer has an entry (Time_Exceeded) that can be used by application
-tasks to block until an execution time overrun is detected, or as an
+whether a timer has expired or not (Timer_Has_Expired). In addition,
+Timer has an entry (Timer_Expired) that can be used by application
+tasks to block until an execution time budget is exhausted, or as an
 event that triggers the abortion of the instructions of a select
 statement with an abortable part.
 
-When a Timer is created, the resources required to operate a CPU-time
-timer based on the associated execution-time clock shall be allocated
+When a Timer is created, at a time no later than return from the
+first call of an Arm procedure, 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, the Storage_Error exception is
-raised. The timer is initialized in the disarmed state.
-
-When a Timer is destroyed, the system resources used by the timer
-shall be deallocated.
+maximum number of timers in the system, the Timer_Resource_Error
+exception is raised. The timer is initialized in the disarmed state.
 
 The Timer.Arm protected procedure that takes a Time_Span parameter
 loads the associated timer with the relative value specified by
@@ -207,28 +211,31 @@
 The Timer.Disarm protected procedure sets the timer to the disarmed
 state. In this state no timer expirations occur.
 
-The Timer.Time_Exceeded protected entry suspends the calling task if
+The Timer.Timer_Expired protected entry suspends the calling task if
 the timer is in the armed state but has not yet expired. The entry is
 allowed to complete when the timer is in the armed state and has
-expired. If the timer is in the disarmed state, the Time_Error exception
+expired. If the timer is in the disarmed state, the Timer_Error exception
 is raised.
 
-The Timer.Time_Was_Exceeded protected function returns True if the
+The Timer.Time_Has_Expired protected function returns True if the
 timer is in the armed state and has expired, and returns False if the
 timer is in the armed state but has not yet expired. If the timer is
-in the disarmed state, the Time_Error exception is raised.
+in the disarmed state, the Timer_Error exception is raised.
 
 The Timer.Time_Remaining protected function returns, when the timer is
 in the armed state, the CPU time interval that remains until the timer
 will expire, or a value representing zero if the timer has expired. If
-the timer is in the disarmed state, the Time_Error exception is raised.
+the timer is in the disarmed state, the Timer_Error exception is raised.
 
-The Time_Error exception is raised by Timer.Time_Exceeded,
-Timer.Time_Was_Exceeded, or Timer.Time_Remaining if an attempt is made
+The Timer_Error exception is raised by Timer.Timer_Expired,
+Timer.Timer_Has_Expired, or Timer.Time_Remaining if an attempt is made
 to use a timer that is in the disarmed state.
 
 Implementation Requirements
 
+When an object of type Timer is finalized, the system resources user by
+the timer must be deallocated.
+
 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
 execution time later. CPU_Tick shall be no greater than 1 millisecond.
@@ -272,10 +279,19 @@
 Implementation Advice
 
 When appropriate, implementations should provide configuration
-mechanisms to change the value of Tick.
+mechanisms to change the value of CPU_Tick.
 
 !discussion
 
+Changes made from previous version include renaming two of the
+components of Timer, making it implementation defined to whom
+system resources are charged, changing time when clock is set
+to zero to be between task creation and start of activation,
+the need to deallocate resources at finalization is moved to
+implementation requirement, exception raised when resources
+not available is Timer_Resource_Error (and this can be raised
+by first call of Arm).
+
 Need for execution time monitoring functionality
 ------------------------------------------------
 
@@ -493,7 +509,7 @@
    task body Periodic_Stopped is
       My_Id : aliased Task_Identification.Task_Id:=
          Periodic_Stopped'Identity;
-      The_Timer : Ada_Real_Time_Execution_Time.Timer(My_Id'Access);
+      The_Timer : Ada.Real_Time.Execution_Time.Timer(My_Id'Access);
       Next_Start : Real_Time.Time:=Real_Time.Clock;
       WCET : constant Duration:=1.0E-3;
       Period : constant Duration:=1.0E-2;
@@ -501,7 +517,7 @@
       loop
          The_Timer.Arm(Real_Time.To_Time_Span(WCET));
          select
-            The_Timer.Time_Exceeded; -- Execution-time overrun detection
+            The_Timer.Timer_Expired; -- Execution-time overrun detection
             Handle_the_error;
          then abort
             Do_useful_work;
@@ -542,11 +558,11 @@
       task body Supervisor is
          WCET : constant Duration:=1.0E-3;
          My_Id : aliased Task_Identification.Task_Id:=Supervisor'Identity;
-         The_Timer : Ada_Real_Time_Execution_Time.Timer(My_Id'Access);
+         The_Timer : Ada.Real_Time.Execution_Time.Timer(My_Id'Access);
          Low_Prio : System.Priority:=System.Priority'First;
       begin
          The_Timer.Arm(Real_Time.To_Time_Span(WCET));
-         The_Timer.Time_Exceeded; -- wait for timer overrun
+         The_Timer.Timer_Expired; -- wait for timer overrun
          Dynamic_Priorities.Set_Priority(Low_Prio,Worker'Identity);
       end Supervisor;
    begin
@@ -555,21 +571,6 @@
    end Worker;
 
 ...
-
-Discussion on the names used
-----------------------------
-
-One reviewer commented that the names are perhaps not quite
-appropriate. For many users, time exceeded will be an error,
-but for others (undertaking imprecise computation etc) it
-is not an error but part of the algorithm (e.g. give this
-routine X amount of computation time). This reviewer suggests
-different names:
-
-Timer_Expired instead of Time_Exceeded
-Timer_Has_Expired instead of Time_Was_Exceeded
-Time_To_Expiration instead of Time_Remaining
-Timer_Disarmed instead of Time_Error
 
 !appendix
 

Questions? Ask the ACAA Technical Agent