D.14.2 Group Execution Time Budgets
This clause describes a language-defined package
to assign execution time budgets to groups of tasks.
The following language-defined library package
package Ada.Execution_Time.Group_Budgets is
type Group_Budget(CPU : System.Multiprocessors.CPU :=
is tagged limited private;
type Group_Budget_Handler is access
protected procedure (GB : in out Group_Budget);
type Task_Array is array (Positive range <>) of
Min_Handler_Ceiling : constant System.Any_Priority :=
The value of Min_Handler_Ceiling in
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;
(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)
procedure Cancel_Handler (GB : in out Group_Budget;
Cancelled : out Boolean);
Group_Budget_Error : exception;
-- not specified by the language
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 has an associated
nonnegative value of type Time_Span known as its budget, which
is initially Time_Span_Zero. The type Group_Budget_Handler identifies
a protected procedure to be executed by the implementation when the budget
is exhausted, that is, reaches zero. Such a protected procedure
is called a handler.
An object of type Group_Budget also includes a
handler, which is a value of type Group_Budget_Handler. The handler of
the object is said to be set if it is not null and cleared
otherwise. The handler of all Group_Budget objects is initially cleared.
Group_Budget is tagged. This makes it possible to share a handler between
several events. In simple cases, 'Access can be used to compare the parameter
with a specific group budget object (this works because a tagged type
is a by-reference type). In more complex cases, a type extension of type
Group_Budget can be declared; a double type conversion can be used to
access the extension data. An example of how this can be done can be
found for the similar type Timing_Event, see D.15.
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 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 returns 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 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 To as the Time_Span value. The exception Group_Budget_Error is
raised if the Time_Span value To is non-positive. Any execution on
CPU of any member of the group of tasks
results in the budget counting down, unless exhausted. When the budget
becomes exhausted (reaches Time_Span_Zero), the associated handler is
executed if the handler of group budget GB is set. Nevertheless, the
tasks continue to execute.
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 handler of 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 handler of Group_Budget is cleared;, otherwise, it is set.
A call of Set_Handler for a Group_Budget that already
has a handler set replaces the handler; if Handler is not null,
the handler for Group_Budget remains set.
The function Current_Handler returns the handler
associated with the group budget GB if the handler for that group budget
is set; otherwise, it returns null.
The procedure Cancel_Handler clears the handler
for the group budget if it is set. Cancelled is assigned True if the
handler for the group budget was set prior to it being cleared; otherwise, it is assigned False.
The constant Min_Handler_Ceiling is the minimum
ceiling priority required for a protected object with a handler to ensure
that no ceiling violation will occur when that handler is invoked.
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
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 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 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.
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 handler.
Reason: This prevents
various race conditions. In particular it ensures that if the budget
is exhausted when Set_Handler is changing the handler then either the
new or old handler is executed and the exhausting event is not lost.
Clearing or setting of the handler 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 of the group budget is
set or cleared.
A Group_Budget_Handler can be associated with several
Extensions to Ada 95
Inconsistencies With Ada 2005
A Group_Budget is now defined
to work on a single processor. If an implementation managed to make this
package work on for programs running on a multiprocessor system, and
a program depends on that fact, it could fail when ported to Ada 2012.
We believe it is unlikely that such an implementation exists because
of the difficulty of signalling other processors when the time reaches
zero; in any case, depending on such an implementation is not portable.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe