CVS difference for ais/ai-00354.txt

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

--- ais/ai-00354.txt	2004/11/14 06:37:19	1.8
+++ ais/ai-00354.txt	2005/03/26 00:26:38	1.9
@@ -1,4 +1,4 @@
-!standard D.14.2 (01)                                 04-11-12  AI95-00354/06
+!standard D.14.2 (01)                                 05-03-16  AI95-00354/07
 !class amendment 03-09-27
 !status Amendment 200Y 04-06-25
 !status ARG Approved 7-0-1  04-06-13
@@ -32,139 +32,150 @@
 
 D.14.2 Group Execution Time Budgets
 
-This clause specifies a group execution time control package.
+This clause describes a language-defined package to assign execution time
+budgets to groups of tasks.
 
 Static Semantics
 
 The following language-defined library package exists:
 
 with System;
-with Ada.Task_Identification;
 package Ada.Execution_Time.Group_Budgets is
   type Group_Budget is limited private;
 
   type Group_Budget_Handler is access
-       protected procedure(GB : in out Group_Budget);
+       protected procedure (GB : in out Group_Budget);
 
-  type Task_Array is array(Positive range <>) of
+  type Task_Array is array (Positive range <>) of
                                   Ada.Task_Identification.Task_ID;
 
   Min_Handler_Ceiling : constant System.Any_Priority :=
     *implementation-defined*;
 
-  procedure Add_Task(GB: in out Group_Budget;
-                       T : in Ada.Task_Identification.Task_ID);
-  procedure Remove_Task(GB: in out Group_Budget;
-                       T : in Ada.Task_Identification.Task_ID);
-  function Is_Member(GB: Group_Budget;
-             T : Ada.Task_Identification.Task_ID) return Boolean;
-  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 : in Time_Span);
-  procedure Add(GB: in out Group_Budget; Interval : in Time_Span);
-  function Budget_Has_Expired(GB: Group_Budget) return Boolean;
-  function Budget_Remaining(GB: Group_Budget) return Time_Span;
-
-  procedure Set_Handler(GB: in out Group_Budget;
-                        Handler : in Group_Budget_Handler);
-  function Current_Handler(GB: Group_Budget) return Group_Budget_Handler;
-  procedure Cancel_Handler(GB: in out Group_Budget;
-               Cancelled : out Boolean);
+  procedure Add_Task (GB : in out Group_Budget;
+                      T  : in Ada.Task_Identification.Task_ID);
+  procedure Remove_Task (GB : in out Group_Budget;
+                         T  : in Ada.Task_Identification.Task_ID);
+  function Is_Member (GB : Group_Budget;
+                      T  : Ada.Task_Identification.Task_ID) return Boolean;
+  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 : in Time_Span);
+  procedure Add (GB : in out Group_Budget; Interval : in Time_Span);
+  function Budget_Has_Expired (GB : Group_Budget) return Boolean;
+  function Budget_Remaining (GB : Group_Budget) return Time_Span;
+
+  procedure Set_Handler (GB      : in out Group_Budget;
+                         Handler : in Group_Budget_Handler);
+  function Current_Handler (GB : Group_Budget) return Group_Budget_Handler;
+  procedure Cancel_Handler (GB        : in out Group_Budget;
+                            Cancelled : out Boolean);
 
   Group_Budget_Error : exception;
 private
     --  not specified by the language
 end Ada.Execution_Time.Group_Budgets;
 
-The type Group_Budget represents a CPU budget to be used by a
-group of tasks. This type needs finalization (see 7.6). A task can
-belong to at most one group. Tasks of any priority can be added to a
-group.
-
-An object of type Group_Budget is said to be *set* if it is associated
-with a (non-null) Group_Budget_Handler and *cleared* otherwise.
-All Group_Budget objects are initially cleared.
-
-An object of type Group_Budget has an associated non-negative
-value of type Time_Span known as the *budget*. The Group_Budget_Handler
-identifies a protected procedure to be executed by the implementation when
-the budget is exhausted.
+The type Group_Budget represents an execution time budget to be used by a group
+of tasks. The type Group_Budget needs finalization (see 7.6). A task can belong
+to at most one group. Tasks of any priority can be added to a group.
+
+An object of type Group_Budget is said to be *set* if it is associated with a
+non-null Group_Budget_Handler and *cleared* otherwise. All Group_Budget
+objects are initially cleared. An object of type Group_Budget has an associated
+non-negative value of type Time_Span known as its *budget*.
+
+The type Group_Budget_Handler identifies a protected procedure to be executed by
+the implementation when the budget is exhausted. Such a protected procedure is
+called a *handler*.
 
 Dynamic Semantics
 
-The procedure Add_Task adds a task to a group if the task is not a member
-of a group. Otherwise, Group_Budget_Error is raised.
+The procedure Add_Task adds the task identified by T to the group GB; if that
+task is already a member of some other group, Group_Budget_Error is raised.
 
-The procedure Remove_Task removes a task from a group. If the task is not
-a member of the group Group_Budget_Error is raised; otherwise the task is no
-longer a member of any group.
-
-The function Is_Member returns True if the task T is a member of the
-specified group. The function Is_A_Group_Member returns
-True if the task is a member of any group. Both return False otherwise.
-
-The function Members returns an array of the task IDs of the members of the
-group. The order of the components of the array is not specified.
-
-The procedure Replenish loads a Group_Budget with the Time_Span value
-passed as a parameter. Any execution of any member of the group of
-tasks results in the budget counting down. When the budget becomes
-exhausted (goes to Time_Span_Zero), the associated handler is called if
-the Group_Budget is set; the tasks continue to execute. A Group_Budget is
-initially loaded with zero budget.
-
-The function Budget_Remaining returns the remaining budget. If the budget
-is exhausted it returns Time_Span_Zero. This is the minimum value
-for a budget. The function Budget_Has_Expired returns True if the
-budget is exhausted (equal to Time_Span_Zero), otherwise it returns False.
-
-The procedure Add can be used to increase a budget. A negative
-value for the parameter reduces the budget, but never below
-Time_Span_Zero. A zero value for the parameter has no effect.
-
-A call of procedure Replenish with a non-positive Time_Span value causes
-Group_Budget_Error to be raised. A call of procedure Add that results in
-the value of the budget going to Time_Span_Zero causes the associated
-handler to be called if the Group_Budget is set.
-
-The procedure Set_Handler associates a Group_Budget_Handler with a
-Group_Budget and thereby sets the Group_Budget. A call of Set_Handler for a
-Group_Budget that is already set replaces the handler and the Group_Budget
-remains set. A call with a null value of Handler clears the Group_Budget.
-
-The function Current_Handler returns the Group_Budget_Handler associated
-with the Group Budget if it is set, otherwise it returns null.
-
-The procedure Cancel_Handler clears the Group_Budget if it was set.
-Cancelled is assigned True if the Group_Budget was set prior to it being
-cleared, otherwise it is assigned False.
+The procedure Remove_Task removes the task identified by T from the group GB;
+if that task is not a member of the group GB, Group_Budget_Error is raised.
+After successful execution of this procedure, the task is no longer a member of
+any group.
+
+The function Is_Member returns True if the task identified by T is a member of
+the group GB; otherwise it return False.
+
+The function Is_A_Group_Member returns True if the task identified by T is a
+member of some group; otherwise it returns False.
+
+The function Members returns an array of values of type
+Ada.Task_Identification.Task_ID identifying the members of the group GB. The
+order of the components of the array is unspecified.
+
+The procedure Replenish loads the group budget GB with the Time_Span value To.
+Group_Budget_Error is raised if the Time_Span value To is non-positive. Any
+execution of any member of the group of tasks results in the budget counting
+down. When the budget becomes exhausted (goes to Time_Span_Zero), the associated
+handler is executed if the group budget GB is set; the tasks continue to
+execute. An object of type Group_Budget is initially loaded with zero budget.
+
+The procedure Add modifies the budget of the group GB. A positive value for
+Interval increases the budget. A negative value for Interval reduces the budget,
+but never below Time_Span_Zero. A zero value for Interval has no effect. A call
+of procedure Add that results in the value of the budget going to Time_Span_Zero
+causes the associated handler to be executed if the group budget GB is set.
+
+The function Budget_Has_Expired returns True if the budget of group GB is
+exhausted (equal to Time_Span_Zero); otherwise it returns False.
+
+The function Budget_Remaining returns the remaining budget for the group GB. If
+the budget
+is exhausted it returns Time_Span_Zero. This is the minimum value for a budget.
+
+The procedure Set_Handler associates the handler Handler with the Group_Budget
+GB; if Handler is null, the Group_Budget is cleared, otherwise it is set.
+
+A call of Set_Handler for a Group_Budget that is already set replaces the
+handler; if Handler is not null, the Group_Budget remains set.
+
+The function Current_Handler returns the handler associated with the group
+budget GB if that group budget is set; otherwise it returns null.
+
+The procedure Cancel_Handler clears the group budget if it is set. Cancelled is
+assigned True if the group budget was set prior to it being cleared; otherwise
+it is assigned False.
 
-The constant Min_Handler_Ceiling is the priority value that will ensure
-that no ceiling violation will occur when a handler is executed.
+The constant Min_Handler_Ceiling is the priority value that ensures
+that no ceiling violation would occur, were a handler to be executed.
 
 The precision of the accounting of task execution time to a Group_Budget
 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 member
-tasks are removed from the group identified by the object.
+tasks are removed from the group identified by that object.
 
 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 defined in this package, Tasking_Error
+is raised if the task identified by T has terminated, and Program_Error
+is raised if the value of T is Ada.Task_Identification.Null_Task_ID.
+
+An exception propagated from a handler invoked when the budget of a
+group of tasks becomes exhausted has no effect.
 
-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
 
+For a call of any of the subprograms defined in this package, if the task
+identified by T no longer exists, the execution of the program is erroneous.
+
 Implementation Requirements
 
 For a given Group_Budget object, the implementation shall perform the
 operations declared in this package atomically with respect to any
 of these operations on the same Group_Budget object. The replacement of
 a handler, by a call of Set_Handler, shall be performed atomically with
-respect to the execution of the Group_Budget_Handler.
+respect to the execution of the handler.
 
 AARM note:
 This prevents various race conditions. In particular it ensures that
@@ -175,9 +186,9 @@
 
 Notes
 
-Clearing or setting of a handler does not change the current value of
+Clearing or setting of a group budget does not change the current value of
 the budget. Exhaustion or loading of a budget does not change whether the
-handler is set or cleared.
+group budget is set or cleared.
 
 A Group_Budget_Handler can be associated with several Group_Budget objects.
 
@@ -311,132 +322,143 @@
 
 @dinsc
 
-This clause specifies a group execution time control package.
+This clause describes a language-defined package to assign execution time
+budgets to groups of tasks.
 
 @i<@s8<Static Semantics>>
 
 The following language-defined library package exists:
 
 @xcode<@b<with> System;
-@b<with> Ada.Task_Identification;
 @b<package> Ada.Execution_Time.Group_Budgets @b<is>
   @b<type> Group_Budget @b<is limited private>;
 
   @b<type> Group_Budget_Handler @b<is access>
-       @b<protected procedure>(GB : @b<in out> Group_Budget);
+       @b<protected procedure> (GB : @b<in out> Group_Budget);
 
-  @b<type> Task_Array @b<is array>(Positive @b<range> <@>) @b<of>
+  @b<type> Task_Array @b<is array> (Positive @b<range> <@>) @b<of>
                                   Ada.Task_Identification.Task_ID;
 
   Min_Handler_Ceiling : @b<constant> System.Any_Priority :=
     @ft<@i<implementation-defined>>;
 
-  @b<procedure> Add_Task(GB: @b<in out> Group_Budget;
-                       T : @b<in> Ada.Task_Identification.Task_ID);
-  @b<procedure> Remove_Task(GB: @b<in out> Group_Budget;
-                       T : @b<in> Ada.Task_Identification.Task_ID);
-  @b<function> Is_Member(GB: Group_Budget;
-             T : Ada.Task_Identification.Task_ID) @b<return> Boolean;
-  @b<function> Is_A_Group_Member(
-             T : Ada.Task_Identification.Task_ID) @b<return> Boolean;
-  @b<function> Members(GB: Group_Budget) @b<return> Task_Array;
-
-  @b<procedure> Replenish (GB: @b<in out> Group_Budget; To : @b<in> Time_Span);
-  @b<procedure> Add(GB: @b<in out> Group_Budget; Interval : @b<in> Time_Span);
-  @b<function> Budget_Has_Expired(GB: Group_Budget) @b<return> Boolean;
-  @b<function> Budget_Remaining(GB: Group_Budget) @b<return> Time_Span;
+  @b<procedure> Add_Task (GB : @b<in out> Group_Budget;
+                      T  : @b<in> Ada.Task_Identification.Task_ID);
+  @b<procedure> Remove_Task (GB: @b<in out> Group_Budget;
+                         T  : @b<in> Ada.Task_Identification.Task_ID);
+  @b<function> Is_Member (GB : Group_Budget;
+                      T : Ada.Task_Identification.Task_ID) @b<return> Boolean;
+  @b<function> Is_A_Group_Member
+     (T : Ada.Task_Identification.Task_ID) @b<return> Boolean;
+  @b<function> Members (GB : Group_Budget) @b<return> Task_Array;
+
+  @b<procedure> Replenish (GB : @b<in out> Group_Budget; To : @b<in> Time_Span);
+  @b<procedure> Add (GB : @b<in out> Group_Budget; Interval : @b<in> Time_Span);
+  @b<function> Budget_Has_Expired (GB : Group_Budget) @b<return> Boolean;
+  @b<function> Budget_Remaining (GB : Group_Budget) @b<return> Time_Span;
 
-  @b<procedure> Set_Handler(GB: @b<in out> Group_Budget;
+  @b<procedure> Set_Handler (GB      : @b<in out> Group_Budget;
                          Handler : @b<in> Group_Budget_Handler);
-  @b<function> Current_Handler(GB: Group_Budget)
-                                    @b<return> Group_Budget_Handler;
-  @b<procedure> Cancel_Handler(GB: @b<in out> Group_Budget;
-               Cancelled : @b<out> Boolean);
+  @b<function> Current_Handler (GB : Group_Budget)
+     @b<return> Group_Budget_Handler;
+  @b<procedure> Cancel_Handler (GB        : @b<in out> Group_Budget;
+                            Cancelled : @b<out> Boolean);
 
   Group_Budget_Error : @b<exception>;
 @b<private>
     --  not specified by the language
 @b<end> Ada.Execution_Time.Group_Budgets;>
-
-The type Group_Budget represents a CPU budget to be used by a
-group of tasks. This type needs finalization (see 7.6). A task can
-belong to at most one group. Tasks of any priority can be added to a
-group.
 
-An object of type Group_Budget is said to be @i<set> if it is associated
-with a (non-null) Group_Budget_Handler and @i<cleared> otherwise.
-All Group_Budget objects are initially cleared.
-
-An object of type Group_Budget has an associated non-negative
-value of type Time_Span known as the @i<budget>. The Group_Budget_Handler
-identifies a protected procedure to be executed by the implementation when
-the budget is exhausted.
+The type Group_Budget represents an execution time budget to be used by a group
+of tasks. The type Group_Budget needs finalization (see 7.6). A task can belong to at most
+one group. Tasks of any priority can be added to a group.
+
+An object of type Group_Budget is said to be @i<set> if it is associated with a
+non-null Group_Budget_Handler and @i<cleared> otherwise. All Group_Budget
+objects are initially cleared. An object of type Group_Budget has an associated
+non-negative value of type Time_Span known as its @i<budget>.
+
+The type Group_Budget_Handler identifies a protected procedure to be executed by
+the implementation when the budget is exhausted. Such a protected procedure is
+called a @i<handler>.
 
 @i<@s8<Dynamic Semantics>>
 
-The procedure Add_Task adds a task to a group if the task is not a member
-of a group. Otherwise, Group_Budget_Error is raised.
+The procedure Add_Task adds the task identified by T to the group GB; if that
+task is already a member of some other group, Group_Budget_Error is raised.
 
-The procedure Remove_Task removes a task from a group. If the task is not
-a member of the group Group_Budget_Error is raised; otherwise the task is no
-longer a member of any group.
-
-The function Is_Member returns True if the task T is a member of the
-specified group. The function Is_A_Group_Member returns
-True if the task is a member of any group. Both return False otherwise.
-
-The function Members returns an array of the task IDs of the members of the
-group. The order of the components of the array is not specified.
-
-The procedure Replenish loads a Group_Budget with the Time_Span value
-passed as a parameter. Any execution of any member of the group of
-tasks results in the budget counting down. When the budget becomes
-exhausted (goes to Time_Span_Zero), the associated handler is called if
-the Group_Budget is set; the tasks continue to execute. A Group_Budget is
-initially loaded with zero budget.
-
-The function Budget_Remaining returns the remaining budget. If the budget
-is exhausted it returns Time_Span_Zero. This is the minimum value
-for a budget. The function Budget_Has_Expired returns True if the
-budget is exhausted (equal to Time_Span_Zero), otherwise it returns False.
-
-The procedure Add can be used to increase a budget. A negative
-value for the parameter reduces the budget, but never below
-Time_Span_Zero. A zero value for the parameter has no effect.
-
-A call of procedure Replenish with a non-positive Time_Span value causes
-Group_Budget_Error to be raised. A call of procedure Add that results in
-the value of the budget going to Time_Span_Zero causes the associated
-handler to be called if the Group_Budget is set.
-
-The procedure Set_Handler associates a Group_Budget_Handler with a
-Group_Budget and thereby sets the Group_Budget. A call of Set_Handler for a
-Group_Budget that is already set replaces the handler and the Group_Budget
-remains set. A call with a null value of Handler clears the Group_Budget.
-
-The function Current_Handler returns the Group_Budget_Handler associated
-with the Group Budget if it is set, otherwise it returns null.
-
-The procedure Cancel_Handler clears the Group_Budget if it was set.
-Cancelled is assigned True if the Group_Budget was set prior to it being
-cleared, otherwise it is assigned False.
+The procedure Remove_Task removes the task identified by T from the group GB; if
+that task is not a member of the group GB, Group_Budget_Error is raised. After
+successful execution of this procedure, the task is no longer a member of any
+group.
+
+The function Is_Member returns True if the task identified by T is a member of
+the group GB; otherwise it return False.
+
+The function Is_A_Group_Member returns True if the task identified by T is a
+member of some group; otherwise it returns False.
+
+The function Members returns an array of values of type
+Ada.Task_Identification.Task_ID identifying the members of the group GB. The
+order of the components of the array is unspecified.
+
+The procedure Replenish loads the group budget GB with the Time_Span value To.
+Group_Budget_Error is raised if the Time_Span value To is non-positive. Any
+execution of any member of the group of tasks results in the budget counting
+down. When the budget becomes exhausted (goes to Time_Span_Zero), the associated
+handler is executed if the group budget GB is set; the tasks continue to
+execute. An object of type Group_Budget is initially loaded with zero budget.
+
+The procedure Add modifies the budget of the group GB. A positive value for
+Interval increases the budget. A negative value for Interval reduces the budget,
+but never below Time_Span_Zero. A zero value for Interval has no effect. A call
+of procedure Add that results in the value of the budget going to Time_Span_Zero
+causes the associated handler to be executed if the group budget GB is set.
+
+The function Budget_Has_Expired returns True if the budget of group GB is
+exhausted (equal to Time_Span_Zero); otherwise it returns False.
+
+The function Budget_Remaining returns the remaining budget for the group GB. If
+the budget
+is exhausted it returns Time_Span_Zero. This is the minimum value for a budget.
+
+The procedure Set_Handler associates the handler Handler with the Group_Budget
+GB; if Handler is @b<null>, the Group_Budget is cleared, otherwise it is set.
+
+A call of Set_Handler for a Group_Budget that is already set replaces the
+handler; if Handler is not @b<null>, the Group_Budget remains set.
+
+The function Current_Handler returns the handler associated with the group
+budget GB if that group budget is set; otherwise it returns @b<null>.
+
+The procedure Cancel_Handler clears the group budget if it is set. Cancelled is
+assigned True if the group budget was set prior to it being cleared; otherwise
+it is assigned False.
 
-The constant Min_Handler_Ceiling is the priority value that will ensure
-that no ceiling violation will occur when a handler is executed.
+The constant Min_Handler_Ceiling is the priority value that ensures
+that no ceiling violation would occur, were a handler to be executed.
 
 The precision of the accounting of task execution time to a Group_Budget
 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 member
-tasks are removed from the group identified by the object.
+tasks are removed from the group identified by that object.
 
 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 defined in this package, Tasking_Error
+is raised if the task identified by T has terminated, and Program_Error
+is raised if the value of T is Ada.Task_Identification.Null_Task_ID.
+
+An exception propagated from a handler invoked when the budget of a
+group of tasks becomes exhausted has no effect.
+
+@i<@s8<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 T no longer exists, the execution of the program is erroneous.
 
 @i<@s8<Implementation Requirements>>
 
@@ -444,12 +466,12 @@
 operations declared in this package atomically with respect to any
 of these operations on the same Group_Budget object. The replacement of
 a handler, by a call of Set_Handler, shall be performed atomically with
-respect to the execution of the Group_Budget_Handler.
+respect to the execution of the handler.
 
 @xindent<@s9<NOTES@hr
-Clearing or setting of a handler does not change the current value of
+Clearing or setting of a group budget does not change the current value of
 the budget. Exhaustion or loading of a budget does not change whether the
-handler is set or cleared.>>
+group budget is set or cleared.>>
 
 @xindent<@s9<A Group_Budget_Handler can be associated with several
 Group_Budget objects.>>

Questions? Ask the ACAA Technical Agent