CVS difference for ais/ai-00354.txt

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

--- ais/ai-00354.txt	2003/11/27 02:01:16	1.3
+++ ais/ai-00354.txt	2004/02/21 04:15:11	1.4
@@ -1,4 +1,4 @@
-!standard D.03 (00)                                   03-11-24  AI95-00354/02
+!standard D.03 (00)                                   04-02-19  AI95-00354/03
 !class amendment 03-09-27
 !status work item 03-09-27
 !status received 03-09-27
@@ -8,7 +8,7 @@
 
 !summary
 
-This AI proposes a child package of Ada.Real_Time.Execution_Time
+This AI proposes a child package of Ada.Execution_Time
 (the revised AI 00307) to allow more than one task to share an
 execution-time budget.
 
@@ -29,7 +29,7 @@
 
 Add new section:
 
-D.14.1 Group Execution Time Budgets
+D.14.2 Group Execution Time Budgets
 
 This clause specifies a group execution time control package.
 
@@ -39,78 +39,72 @@
 
 with System;
 with Ada.Task_Identification;
-package Ada.Real_Time.Execution_Time.Group_Budgets is
+package Ada.Execution_Time.Group_Budgets is
   type Group_Budget is limited private;
 
-  type Handler is access protected procedure(GB : in out Group_Budget);
+  type Handler is not null access
+       protected procedure(GB : in out Group_Budget);
 
-  type Task_Group is array(Natural range <>) of
+  type Task_Array is array(Natural range <>) of
                                   Ada.Task_Identification.Task_ID;
 
   Min_Handler_Ceiling : constant System.Any_Priority :=
     <Implementation Defined>;
 
-  procedure Set_Handler(GB: in out Group_Budget; H : Handler);
-  function Current_Handler(GB: Group_Budget) return Handler;
-
-  procedure Replenish (GB: in out Group_Budget; To : Time_Span);
-  procedure Add(GB: in out Group_Budget; Interval : Time_Span);
-
   procedure Add_Task(GB: in out Group_Budget;
                        T : Ada.Task_Identification.Task_ID);
   procedure Remove_Task(GB: in out Group_Budget;
                        T : Ada.Task_Identification.Task_ID);
   function Is_Member(GB: Group_Budget;
              T : Ada.Task_Identification.Task_ID) return Boolean;
-  function Is_Member(
+  function Is_A_Group_Member(
              T : Ada.Task_Identification.Task_ID) return Boolean;
+  function Members(GB: Group_Budget) return Task_Array;
 
+  procedure Replenish (GB: in out Group_Budget; To : Time_Span);
+  procedure Add(GB: in out Group_Budget; Interval : Time_Span);
   function Budget_Has_Expired(GB: Group_Budget) return Boolean;
   function Budget_Remaining(GB: Group_Budget) return Time_Span;
 
-  function Members(GB: Group_Budget) return Task_Group;
+  procedure Set_Handler(GB: in out Group_Budget; H : Handler);
+  function Current_Handler(GB: Group_Budget) return Handler;
+  procedure Cancel_Handler(GB: in out Group_Budget;
+               Cancelled : out Boolean);
 
   Group_Budget_Error : exception;
 private
     --  not specified by the language
-end Ada.Real_Time.Execution_Time.Group_Budgets;
+end Ada.Execution_Time.Group_Budgets;
+
+The type Group_Budget represents a CPU budget to be used by a
+group of tasks. Objects of this type require finalization.
 
-The type Group_Budget represents a CPU budget to be
-used by a group of tasks.
+An object of type Group_Budget is said to be set if it has a
+registered Handler. An object is said to be cleared if it has
+no Handler. All Group_Budget objects are initially cleared.
 
 Dynamic Semantics
 
-Tasks of any priority can be added to a group by calling Add_Task.
-Tasks can be the member of at most one group. Group_Budget_Error
+Tasks of any priority are added to a group by calling Add_Task.
+Tasks are members of at most one group. Group_Budget_Error
 is raised by a call to Add_Task if the task is already a member
 of any group.
 
-Tasks can be removed from a group by calling Remove_Task.
+Tasks are removed from a group by calling Remove_Task.
 An attempt to remove a task that has not been added to the
 group will cause Group_Budget_Error to be raised.
 
-The first Is_Member function will return True if the task parameter is
-a member of the specified group. The other Is_Member function returns
+The Is_Member function will return True if the task parameter is
+a member of the specified group. The Is_A_Group_Member function returns
 True if the task is a member of any group. Both return False otherwise.
 
-When the Group_Budget is exhausted a call is made to a protected
-procedure. This procedure can be set by the Set_Handler subprogram.
-The subprogram Current_Handler allows the current procedure to be obtained.
-A call to Set_Handler for a Group_Budget that is already set, resets
-the handler.
-
-The constant Min_Handler_Ceiling indicates the minimum ceiling
-priority that must be assigned to any protected object associated with
-the Handler protected procedure.
-
-A Group_Budget is initially without budget. The Handler protected
-procedure is initially null.
+The Members function returns the task IDs of the members of the group.
 
 When a call to Replenish is made, the Group_Budget is loaded with the
 Time_Span value passed as a parameter. Any execution of the group of
 tasks results in the Group_Budget counting down. When the budget is
-exhausted (goes to Time_Span_Zero), the handler is called; the tasks
-continue to execute.
+exhausted (goes to Time_Span_Zero) the handler, if set, is called; the tasks
+continue to execute. A Group_Budget is initially loaded with zero budget.
 
 A call to Budget_Remaining returns the remaining budget. If the budget
 is exhausted it will return Time_Span_Zero. This is the minimum value
@@ -123,27 +117,38 @@
 
 A call of Replenish with a non positive value of To will causes exception
 Group_Budget_Error to be raised. A call to Add that results in the value
-of the budget going to Time_Span_Zero will cause the handler to be executed.
+of the budget going to Time_Span_Zero will cause the handler, if set,
+to be executed.
 
-The Members function returns the task IDs of the members of the group.
+A call to Set_Handler registers the Handler and returns when GB is set.
+A call to Set_Handler for a Group_Budget that is already set, initially
+clears the Group_Budget then registers the new Handler.
+
+A call to Current_Handler returns with the current Handler.
+If the Group_Budget denoted by GB is not set, exception Group_Budget_Error
+is raised.
+
+A call to Cancel_Handler returns after the Group_Budget denoted by GB
+is cleared. Cancelled is assigned True if GB was set prior to it
+being cleared; otherwise the parameter is assigned False.
 
+The constant Min_Handler_Ceiling is the priority value that will insure that
+no ceiling violation will occur when a handler is executed.
+
 The precision of the accounting of task execution time to a Group_Budget
-is the same as that of Timers from the parent package.
+is the same as that defined for execution-time clocks from the parent
+package.
 
-As part of the finalization of an object of type Group_Budget all
+As part of the finalization of an object of type Group_Budget all member
 tasks are removed from the group identified by the object.
 
-If restriction No_Nested_Finalization is in effect Group_Budget objects
-can only be defined at the library level.
-
 If a task is a member of a Group_Budget when it terminates then as part of
 the finalization of the task it is removed from the group.
 
 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 task identified by T has terminated. Program_Error
 is raised if the value of T is Null_Task_ID.
 
-
 Implementation Requirements
 
 For a given Group_Budget object, the implementation shall perform the
@@ -156,8 +161,8 @@
 The code for a simple deferrable server is given below:
 
 with Ada.Timing_Events; use Ada.Timing_Events;
-with Ada.Real_Time.Execution_Time.Group_Budgets;
-use Ada.Real_Rime.Execution_Time.Group_Budgets;
+with Ada.Execution_Time.Group_Budgets;
+use Ada.Execution_Time.Group_Budgets;
 with Ada.Task_Identification; use Ada.Task_Identification;
 with Ada.Real_Time; use Ada.Real_Time;
 with System; use System;
@@ -217,21 +222,24 @@
 
   protected body Controller is
     procedure Budget_Expired(GB : in out Group_Budget) is
+      TA : Task_Array := Members(GB);
     begin
-      for T in Members(GB)'Range loop
-        Ada.Asynchronous_Control.Hold(T);
+      for ID in TA'Range loop
+        Ada.Asynchronous_Control.Hold(TA(ID));
       end loop;
     end Budget_Expired;
 
     procedure Replenish_Due(TE : in out Timing_Event) is
+      TA : Task_Array;
     begin
       Replenish(DS.Budget_Control, DS.Budget);
       DS.Next_Replenishment_Time := DS.Next_Replenishment_Time + DS.Period;
       Timing_Events.Set_Handler(DS.Replenish_Control,
                               DS.Next_Replenishment_Time,
                               DS.Server_Control.Replenish_Due'Access);
-      for T in Members(GB)'Range loop
-        Ada.Asynchronous_Control.Continue(T);
+      TA := Members(DS.Budget_Control);
+      for ID in TA'Range loop
+        Ada.Asynchronous_Control.Continue(TA(ID));
       end loop;
     end Replenish_Due;
 
@@ -243,8 +251,7 @@
 
 !discussion
 
-Should the Add_Task, Remove_Task and the two Is_Member functions have
-a default task_ID of the current task?
+Should the Add_Task, Remove_Task have a default task_ID of the current task?
 
 
 Various alternative models were considered including:
@@ -279,5 +286,20 @@
 Tests should be created to check on the implementation of this feature.
 
 !appendix
+
+From: Robert Dewar
+Sent: Thursday, February 19, 2004  12:14 PM
+
+For a proposal like this, I would like to see an analysis of
+implemntability under various operating systems and real time
+executives, e.g. AE653. These days almost all Ada real-time programs are
+deployed in such environments and it is important to understand whether
+this feature fits smoothly into existing environments. If not, I would
+consider this a serious problem with the proposal.
+
+In other words, it is hard to convince me that Ada needs to be able to
+do something that cannot be done under Lynx, VxWorks, Integrity,
+Solaris, NT, and other systems typically being used today
+to implement real time systems.
 
 ****************************************************************

Questions? Ask the ACAA Technical Agent