CVS difference for ais/ai-00307.txt

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

--- ais/ai-00307.txt	2003/11/25 02:24:25	1.8
+++ ais/ai-00307.txt	2004/02/12 05:59:12	1.9
@@ -1,4 +1,4 @@
-!standard D.14 (01)                                  03-11-24  AI95-00307/06
+!standard D.14 (01)                                  04-02-10  AI95-00307/07
 !class amendment 02-08-28
 !status work item 03-09-21
 !status ARG Approved 12-0-1  03-06-20
@@ -93,8 +93,8 @@
 The following language-defined library package exists:
 
 with Ada.Task_Identification;
-with System;
-package Ada.Real_Time.Execution_Time is
+with Ada.Real_Time; use Ada.Real_Time;
+package Ada.Execution_Time is
 
    type CPU_Time is private;
    CPU_Time_First : constant CPU_Time;
@@ -122,29 +122,11 @@
 
    function Time_Of (SC : Seconds_Count; TS : Time_Span) return CPU_Time;
 
-   type Timer (T : access Ada.Task_Identification.Task_ID) is
-      limited private;
-
-   type Handler is access protected procedure (TM : in out Timer);
-
-   Min_Handler_Ceiling : constant System.Any_Priority :=
-    <Implementation Defined>;
-
-   procedure Arm (TM: in out Timer; Interval : Time_Span; H : Handler);
-   procedure Arm (TM: in out Timer; Abs_Time : CPU_Time;  H : Handler);
-   procedure Disarm(TM : in out Timer);
-   function Timer_Has_Expired(TM : Timer) return Boolean;
-   function Time_Remaining(TM : Timer) return Time_Span;
-
-   Timer_Error : exception;
-
-   Timer_Resource_Error : exception;
-
 private
    ... --  not specified by the language
-end Ada.Real_Time.Execution_Time;
+end Ada.Execution_Time;
 
-Execution time or cpu time of a given task is defined as the time spent
+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
@@ -174,8 +156,8 @@
 calling the Clock function) remains constant. CPU_Tick is the average
 length of such intervals.
 
-The effects of the operators on Time and Time_Span are as for the
-operators defined for integer values.
+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 amount of execution time of the task
 associated with the execution-time clock of the task represented by T.
@@ -188,63 +170,6 @@
 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.
 
-Package Execution_Time contains a type called Timer, which represents a
-software object that is capable of detecting execution time overruns. Each
-timer is attached to a specific execution time clock, which is the clock of the
-task specified by the access discriminant T. This type has operations for the
-application tasks to arm or disarm a timer, and to determine whether a timer
-has expired or not (Timer_Has_Expired). In addition, when arming the timer, an
-access to a protected procedure (type Handler) is passed. This procedure
-will be called by the implementation when the timer expires. This can be used
-by the application (for example) to trigger the abortion of the instructions of
-a select statement with an abortable part.
-
-The constant Min_Handler_Ceiling indicates the minimum ceiling
-priority that must be assigned to any protected object associated with
-the Handler protected procedure.
-
-When a Timer object is created, or upon the first call to one of its Arm
-procedures, 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 Timer_Resource_Error exception is raised. The timer
-is initialized in the disarmed state.
-
-The Arm procedure that takes a Time_Span parameter loads the associated timer
-with the relative value specified by Interval and sets it to the armed state.
-In this state the timer counts execution time and, when the CPU clock
-associated with the timer measures the passage of Interval, it is said to have
-expired. If the timer was already armed, it is rearmed.
-
-The Arm procedure that takes a CPU_Time parameter loads the associated timer
-with the absolute value specified by Abs_Time and sets it to the armed state.
-In this state the timer monitors execution time and, when the CPU clock
-associated with the timer reaches the value Abs_Time, it is said to have
-expired. If the value of Abs_Time had already been reached by the clock at the
-time of the call, the timer is set to the armed state and is said to have
-expired. If the timer was already armed, it is rearmed.
-
-For any of the Arm procedures, when the timer expires, the protected
-procedure Handler is invoked by the system with a parameter equal to
-the Timer.
-
-The Disarm procedure sets the timer to the disarmed state. In this
-state no timer expirations occur.
-
-The Time_Has_Expired 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 Timer_Error exception is raised.
-
-The Time_Remaining 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 Timer_Error exception is raised.
-
-The Timer_Error exception is raised by Timer_Has_Expired, or
-Time_Remaining if an attempt is made to use a timer that is in the
-disarmed state.
-
 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.
@@ -259,13 +184,6 @@
 
 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.
-
-When an object of type Timer is finalized, the system resources used by
-the timer shall 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.
@@ -292,7 +210,7 @@
    - An upper bound on the size of a clock jump. A clock jump is the
      difference between two successive distinct values of an execution
      -time clock (as observed by calling the Clock function with the
-     same Task_Id)
+     same Task_Id).
 
    - An upper bound on the execution time of a call to the Clock
      function, in processor clock cycles.
@@ -306,15 +224,124 @@
 bits need not support the full range and granularity of the CPU_Time
 type.
 
-Implementations may limit the number of timers that can be defined for
-each task. If this limit is exceed the Timer_Resource_Error exception
-is raised.
-
 Implementation Advice
 
 When appropriate, implementations should provide configuration
 mechanisms to change the value of CPU_Tick.
 
+Add new section D.14.1
+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.
+
+Static Semantics
+
+The following language-defined library package exists:
+
+with Ada.Task_Identification;
+with System;
+with Ada.Real_Time; use Ada.Real_Time;
+with Ada.Execution_Time;
+package Ada.Execution_Time.Timers is
+
+   type Timer (T : access Ada.Task_Identification.Task_ID) is
+      limited private;
+
+   type Handler is not null access protected procedure (TM : in out Timer);
+
+   Min_Handler_Ceiling : constant System.Any_Priority :=
+    <Implementation Defined>;
+
+   procedure Arm (TM: in out Timer; Interval : Time_Span; H : Handler);
+   procedure Arm (TM: in out Timer; Abs_Time : CPU_Time;  H : Handler);
+   procedure Disarm(TM : in out Timer);
+
+   function Timer_Has_Expired(TM : Timer) return Boolean;
+   function Time_Remaining(TM : Timer) return Time_Span;
+
+   Timer_Error : exception;
+   Timer_Resource_Error : exception;
+
+private
+   ... --  not specified by the language
+end Ada.Execution_Time.Timers;
+
+Dynamic Semantics
+
+Type Timer represents a software object that is capable of detecting
+execution time overruns. Each timer is attached to a specific
+execution time clock, which is the clock of the task specified
+by the access discriminant T. This type has operations for the
+application tasks to arm or disarm a timer, and to determine whether a timer
+has expired or not (Timer_Has_Expired). In addition, when arming the timer, an
+access to a protected procedure (type Handler) is passed. This procedure
+will be called by the implementation when the timer expires.
+
+The constant Min_Handler_Ceiling is the priority value that will insure that
+no ceiling violation will occur when a handler is executed.
+
+When a Timer object is created, or upon the first call to one of its Arm
+procedures, the resources required to operate a CPU-time timer based on
+the associated execution-time clock will be allocated and initialized.
+The timer is initialized in the disarmed state. If this operation would
+exceed the limit of the maximum number of timers in the system, the
+Timer_Resource_Error exception is raised.
+
+The Arm procedure that takes a Time_Span parameter loads the associated timer
+with the relative value specified by Interval and sets it to the armed state.
+In this state the timer counts execution time and, when the CPU clock
+associated with the timer measures the passage of Interval, it is said to have
+expired. If the timer was already armed, it is rearmed.
+
+The Arm procedure that takes a CPU_Time parameter loads the associated timer
+with the absolute value specified by Abs_Time and sets it to the armed state.
+In this state the timer monitors execution time and, when the CPU clock
+associated with the timer reaches the value Abs_Time, it is said to have
+expired. If the value of Abs_Time had already been reached by the clock at the
+time of the call, the timer is set to the armed state and is said to have
+expired. If the timer was already armed, it is rearmed.
+
+When a Timer expires, the protected procedure Handler is invoked by the system
+with a parameter equal to the Timer.
+
+The Disarm procedure sets the timer to the disarmed state. In this
+state the timer will not expire.
+
+The Time_Has_Expired 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 Timer_Error exception is raised.
+
+The Time_Remaining 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 Timer_Error exception is raised.
+
+The Timer_Error exception is raised by Timer_Has_Expired, or
+Time_Remaining if an attempt is made to use a timer that is in the
+disarmed state.
+
+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.
+
+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.
+
+When an object of type Timer is finalized, the system resources used by
+the timer shall be deallocated.
+
+Implementation Permissions
+
+Implementations may limit the number of timers that can be defined for
+each task. If this limit is exceeded the Timer_Resource_Error exception
+is raised.
+
 !discussion
 
 A prototype implementations was developed for the initial proposal, using the
@@ -326,7 +353,7 @@
 
 Implementations on bare machines or systems without POSIX
 execution-time clocks and timers would be a bit more complex because
-the underlaying execution-time monitoring functionality would have to
+the underlying execution-time monitoring functionality would have to
 be implemented in the scheduler. Document [2] describes one such
 implementation and it can be seen that it is relatively simple, and
 that it does not introduce any significant overhead into the
@@ -393,7 +420,7 @@
 time). If an execution time overrun is detected, the task aborts the
 remainder of its execution, until the next period.
 
-with Ada.Real_Time, Ada.Real_Time.Execution_Time, Ada.Task_Identification;
+with Ada.Real_Time, Ada.Execution_Time.Timers, Ada.Task_Identification;
 use Ada;
 use type Ada.Real_Time.Time;
 
@@ -403,8 +430,8 @@
 
    protected Control is
      entry Wait_Budget_Expiry;
-     procedure Budget_Expired(T : in out Ada.Real_Time.Execution_Time.Timer);
-     pragma Priority(Ada.Real_Time.Execution_Time.Min_Handler_Ceiling);
+     procedure Budget_Expired(T : in out Ada.Execution_Time.Timers.Timer);
+     pragma Priority(Ada.Execution_Time.Timers.Min_Handler_Ceiling);
    private
      Expired : Boolean := False;
    end Control;
@@ -415,7 +442,7 @@
        Expired := False;
      end Wait_Budget_Expiry;
 
-     procedure Budget_Expired(T : in out Ada.Real_Time.Execution_Time.Timer) is
+     procedure Budget_Expired(T : in out Ada.Execution_Time.Timers.Timer) is
      begin
        Expired := True;
      end Budget_Expired;
@@ -424,14 +451,14 @@
    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.Execution_Time.Timers.Timer(My_Id'Access);
 
       Next_Start : Real_Time.Time:=Real_Time.Clock;
       WCET : constant Duration:=1.0E-3;
       Period : constant Duration:=1.0E-2;
    begin
       loop
-         Ada.Real_Time.Execution_Time.Arm
+         Ada.Execution_Time.Timers.Arm
             (The_Timer, Real_Time.To_Time_Span(WCET),
              Control.Budget_Expired'Access);
          select
@@ -440,7 +467,7 @@
          then abort
             null; -- Do_useful_work;
          end select;
-         Ada.Real_Time.Execution_Time.Disarm(The_Timer);
+         Ada.Execution_Time.Timers.Disarm(The_Timer);
          Next_Start := Next_Start + Real_Time.To_Time_Span(Period);
          delay until Next_Start;
       end loop;
@@ -463,7 +490,7 @@
 completes the work before the instant of the priority change then it
 aborts the Supervisor task.
 
-with Ada.Real_Time,Ada.Real_Time.Execution_Time,
+with Ada.Real_Time,Ada.Execution_Time.Timers,
    Ada.Dynamic_Priorities, System, Ada.Task_Identification;
 use Ada;
 
@@ -471,8 +498,8 @@
 
    protected Control is
      entry Wait_Budget_Expiry;
-     procedure Budget_Expired(T : in out Ada.Real_Time.Execution_Time.Timer);
-     pragma Priority(Ada.Real_Time.Execution_Time.Min_Announce_Ceiling);
+     procedure Budget_Expired(T : in out Ada.Execution_Time.Timers.Timer);
+     pragma Priority(Ada.Execution_Time.Timers.Min_Announce_Ceiling);
    private
      Expired : Boolean := False;
    end Control;
@@ -483,7 +510,7 @@
        Expired := False;
      end Wait_Budget_Expiry;
 
-     procedure Budget_Expired(T : in out Ada.Real_Time.Execution_Time.Timer) is
+     procedure Budget_Expired(T : in out Ada.Execution_Time.Timers.Timer) is
      begin
        Expired := True;
      end Budget_Expired;
@@ -499,10 +526,10 @@
       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.Execution_Time.Timers.Timer(My_Id'Access);
          Low_Prio : System.Priority:=System.Priority'First;
       begin
-         Ada.Real_Time.Execution_Time.Arm
+         Ada.Execution_Time.Timers.Arm
            (The_Timer, Real_Time.To_Time_Span(WCET),
             Control.Budget_Expired'Access);
          Control.Wait_Budget_Expiry; -- wait for timer overrun
@@ -559,6 +586,19 @@
  [3] Extending Ada's Real-Time Systems Annex with the POSIX Scheduling
      Services. By: Mario Aldea Rivas and Michael Gonzalez
      Harbour. IRTAW-2000, Las Navas, Avila, Spain.
+
+****************************************************************
+
+From: Alan Burns
+Sent: Tuesday, August 10, 2004  10:50 PM
+
+I attach new version of 307 - execution time clocks
+[Editor's note: This is version /07.]
+
+Main change is the spliting of the package into 2.
+Also handler is now 'not null'. Text for meaning of
+operators was there al the time; other changes to
+words from minutes made.
 
 ****************************************************************
 

Questions? Ask the ACAA Technical Agent