C.7 Task Information
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
[This subclause describes operations and attributes that can be used to obtain the identity of a task. In addition, a package that associates user-defined information with a task is defined. Finally, a package that associates termination procedures with a task or set of tasks is defined.]
Wording Changes from Ada 95
C.7.1 The Package Task_Identification
Static Semantics
1The following language-defined library package exists:
package Ada.Task_Identification
with Preelaborate, Nonblocking, Global => in out synchronized is
type Task_Id is private
with Preelaborable_Initialization ;
Null_Task_Id : constant Task_Id;
function "=" (Left, Right : Task_Id) return Boolean;
3/5{8652/0070} function Image (T : Task_Id) return String;
function Current_Task return Task_Id;
function Environment_Task return Task_Id;
procedure Abort_Task (T : in Task_Id)
with Nonblocking => False;
4/3function Is_Terminated (T : Task_Id) return Boolean;
function Is_Callable (T : Task_Id) return Boolean;
function Activation_Is_Complete (T : Task_Id) return Boolean;
private
... -- not specified by the language
end Ada.Task_Identification;
Dynamic Semantics
5A value of the type Task_Id identifies an existent task. The constant Null_Task_Id does not identify any task. Each object of the type Task_Id is default initialized to the value of Null_Task_Id.
The function "=" returns True if and only if Left and Right identify the same task or both have the value Null_Task_Id.
The function Image returns an implementation-defined string that identifies T. If T equals Null_Task_Id, Image returns an empty string.
The function Current_Task returns a value that identifies the calling task.
The function Environment_Task returns a value that identifies the environment task.
The effect of Abort_Task is the same as the abort_statement for the task identified by T. [In addition, if T identifies the environment task, the entire partition is aborted, See E.1.]
The functions Is_Terminated and Is_Callable return the value of the corresponding attribute of the task identified by T.
The function Activation_Is_Complete returns True if the task identified by T has completed its activation (whether successfully or not). It returns False otherwise. If T identifies the environment task, Activation_Is_Complete returns True after the elaboration of the library_items of the partition has completed.
For a prefix T that is of a task type [(after any implicit dereference)], the following attribute is defined:
T'Identity
- Yields a value of the type Task_Id that identifies the task denoted by T.
For a prefix E that denotes an entry_declaration, the following attribute is defined:
E'Caller
- Yields a value of the type Task_Id that identifies the task whose call is now being serviced. Use of this attribute is allowed only inside an
accept_statement, orentry_bodyafter theentry_barrier, corresponding to theentry_declarationdenoted by E.
Program_Error is raised if a value of Null_Task_Id is passed as a parameter to Abort_Task, Activation_Is_Complete, Is_Terminated, and Is_Callable.
This paragraph was deleted.
Bounded (Run-Time) Errors
17/3It is a bounded error to call the Current_Task function from an entry_body, interrupt handler, or finalization of a task attribute. Program_Error is raised, or an implementation-defined value of the type Task_Id is returned.
entry_body, so a call to Current_Task from an entry barrier is also covered by this rule. Erroneous Execution
18If a value of Task_Id is passed as a parameter to any of the operations declared in this package (or any language-defined child of this package), and the corresponding task object no longer exists, the execution of the program is erroneous.
Documentation Requirements
19The implementation shall document the effect of calling Current_Task from an entry body or interrupt handler.
Extensions to Ada 95
Wording Changes from Ada 95
Incompatibilities With Ada 2005
use_clause, and an entity E with a defining_identifier of Environment_Task or Activation_Is_Complete is defined in a package that is also referenced in a use_clause, the entity E may no longer be use-visible, resulting in errors. This should be rare and is easily fixed if it does occur. Wording Changes from Ada 2012
C.7.2 The Package Task_Attributes
Static Semantics
1The following language-defined generic library package exists:
with Ada.Task_Identification; use Ada.Task_Identification;
generic
type Attribute is private;
Initial_Value : in Attribute;
package Ada.Task_Attributes
with Nonblocking, Global => in out synchronized is
3type Attribute_Handle is access all Attribute;
4function Value(T : Task_Id := Current_Task)
return Attribute;
5function Reference(T : Task_Id := Current_Task)
return Attribute_Handle;
6procedure Set_Value(Val : in Attribute;
T : in Task_Id := Current_Task);
procedure Reinitialize(T : in Task_Id := Current_Task);
7end Ada.Task_Attributes;
Dynamic Semantics
8When an instance of Task_Attributes is elaborated in a given active partition, an object of the actual type corresponding to the formal type Attribute is implicitly created for each task (of that partition) that exists and is not yet terminated. This object acts as a user-defined attribute of the task. A task created previously in the partition and not yet terminated has this attribute from that point on. Each task subsequently created in the partition will have this attribute when created. In all these cases, the initial value of the given attribute is Initial_Value.
The Value operation returns the value of the corresponding attribute of T.
The Reference operation returns an access value that designates the corresponding attribute of T.
The Set_Value operation performs any finalization on the old value of the attribute of T and assigns Val to that attribute (see 5.2 and 7.6).
The effect of the Reinitialize operation is the same as Set_Value where the Val parameter is replaced with Initial_Value.
For all the operations declared in this package, Tasking_Error is raised if the task identified by T is terminated. Program_Error is raised if the value of T is Null_Task_Id.
After a task has terminated, all of its attributes are finalized, unless they have been finalized earlier. When the master of an instantiation of Ada.Task_Attributes is finalized, the corresponding attribute of each task is finalized, unless it has been finalized earlier.
Bounded (Run-Time) Errors
13.2/1{8652/0071} If the package Ada.Task_Attributes is instantiated with a controlled type and the controlled type has user-defined Adjust or Finalize operations that in turn access task attributes by any of the above operations, then a call of Set_Value of the instantiated package constitutes a bounded error. The call may perform as expected or may result in forever blocking the calling task and subsequently some or all tasks of the partition.
Erroneous Execution
14It is erroneous to dereference the access value returned by a given call on Reference after a subsequent call on Reinitialize for the same task attribute, or after the associated task terminates.
If a value of Task_Id is passed as a parameter to any of the operations declared in this package and the corresponding task object no longer exists, the execution of the program is erroneous.
{8652/0071} An access to a task attribute via a value of type Attribute_Handle is erroneous if executed concurrently with another such access or a call of any of the operations declared in package Task_Attributes. An access to a task attribute is erroneous if executed concurrently with or after the finalization of the task attribute.
Implementation Requirements
16/1{8652/0071} For a given attribute of a given task, the implementation shall perform the operations declared in this package atomically with respect to any of these operations of the same attribute of the same task. The granularity of any locking mechanism necessary to achieve such atomicity is implementation defined.
After task attributes are finalized, the implementation shall reclaim any storage associated with the attributes.
Documentation Requirements
18The implementation shall document the limit on the number of attributes per task, if any, and the limit on the total storage for attribute values per task, if such a limit exists.
In addition, if these limits can be configured, the implementation shall document how to configure them.
Metrics
20/2The implementation shall document the following metrics: A task calling the following subprograms shall execute at a sufficiently high priority as to not be preempted during the measurement period. This period shall start just before issuing the call and end just after the call completes. If the attributes of task T are accessed by the measurement tests, no other task shall access attributes of that task during the measurement period. For all measurements described here, the Attribute type shall be a scalar type whose size is equal to the size of the predefined type Integer. For each measurement, two cases shall be documented: one where the accessed attributes are of the calling task [(that is, the default value for the T parameter is used)], and the other, where T identifies another, nonterminated, task.
The following calls (to subprograms in the Task_Attributes package) shall be measured:
- a call to Value, where the return value is Initial_Value;
- a call to Value, where the return value is not equal to Initial_Value;
- a call to Reference, where the return value designates a value equal to Initial_Value;
- a call to Reference, where the return value designates a value not equal to Initial_Value;
- a call to Set_Value where the Val parameter is not equal to Initial_Value and the old attribute value is equal to Initial_Value;
- a call to Set_Value where the Val parameter is not equal to Initial_Value and the old attribute value is not equal to Initial_Value.
Implementation Permissions
28/5An implementation can avoid actually creating the object corresponding to a task attribute until its value is set to something other than that of Initial_Value, or until Reference is called for the task attribute. Similarly, when the value of the attribute is to be reinitialized to that of Initial_Value, the object may instead be finalized and its storage reclaimed, to be recreated when needed later. While the object does not exist, the function Value may simply return Initial_Value, rather than implicitly creating the object.
An implementation is allowed to place restrictions on the maximum number of attributes a task may have, the maximum size of each attribute, and the total storage size allocated for all the attributes of a task.
Implementation Advice
30/5Some implementations are targeted to domains in which memory use at run time has to be completely deterministic. For such implementations, it is recommended that the storage for task attributes will be pre-allocated statically and not from the heap. This can be accomplished by either placing restrictions on the number and the size of the attributes of a task, or by using the pre-allocated storage for the first N attribute objects, and the heap for the others. In the latter case, N should be documented.
Finalization of task attributes and reclamation of associated storage should be performed as soon as possible after task termination.
Wording Changes from Ada 95
C.7.3 The Package Task_Termination
Static Semantics
1/2The following language-defined library package exists:
with Ada.Task_Identification;
with Ada.Exceptions;
package Ada.Task_Termination
with Preelaborate, Nonblocking, Global => in out synchronized is
3/2type Cause_Of_Termination is (Normal, Abnormal, Unhandled_Exception);
4/2type Termination_Handler is access protected procedure
(Cause : in Cause_Of_Termination;
T : in Ada.Task_Identification.Task_Id;
X : in Ada.Exceptions.Exception_Occurrence);
5/2procedure Set_Dependents_Fallback_Handler
(Handler: in Termination_Handler);
function Current_Task_Fallback_Handler return Termination_Handler;
6/2procedure Set_Specific_Handler
(T : in Ada.Task_Identification.Task_Id;
Handler : in Termination_Handler);
function Specific_Handler (T : Ada.Task_Identification.Task_Id)
return Termination_Handler;
7/2end Ada.Task_Termination;
Dynamic Semantics
8/3The type Termination_Handler identifies a protected procedure to be executed by the implementation when a task terminates. Such a protected procedure is called a handler. In all cases T identifies the task that is terminating. If the task terminates due to completing the last statement of its body, or as a result of waiting on a terminate alternative, and the finalization of the task completes normally, then Cause is set to Normal and X is set to Null_Occurrence. If the task terminates because it is being aborted, then Cause is set to Abnormal; X is set to Null_Occurrence if the finalization of the task completes normally. If the task terminates because of an exception raised by the execution of its task_body, then Cause is set to Unhandled_Exception; X is set to the associated exception occurrence if the finalization of the task completes normally. Independent of how the task completes, if finalization of the task propagates an exception, then Cause is either Unhandled_Exception or Abnormal, and X is an exception occurrence that identifies the Program_Error exception.
Each task has two termination handlers, a fall-back handler and a specific handler. The specific handler applies only to the task itself, while the fall-back handler applies only to the dependent tasks of the task. A handler is said to be set if it is associated with a nonnull value of type Termination_Handler, and cleared otherwise. When a task is created, its specific handler and fall-back handler are cleared.
The procedure Set_Dependents_Fallback_Handler changes the fall-back handler for the calling task: if Handler is null, that fall-back handler is cleared; otherwise, it is set to be Handler.all. If a fall-back handler had previously been set it is replaced.
The function Current_Task_Fallback_Handler returns the fall-back handler that is currently set for the calling task, if one is set; otherwise, it returns null.
The procedure Set_Specific_Handler changes the specific handler for the task identified by T: if Handler is null, that specific handler is cleared; otherwise, it is set to be Handler.all. If a specific handler had previously been set it is replaced.
The function Specific_Handler returns the specific handler that is currently set for the task identified by T, if one is set; otherwise, it returns null.
As part of the finalization of a task_body, after performing the actions specified in 7.6 for finalization of a master, the specific handler for the task, if one is set, is executed. If the specific handler is cleared, a search for a fall-back handler proceeds by recursively following the master relationship for the task. If a task is found whose fall-back handler is set, that handler is executed; otherwise, no handler is executed.
For Set_Specific_Handler or Specific_Handler, Tasking_Error is raised if the task identified by T has already terminated. Program_Error is raised if the value of T is Ada.Task_Identification.Null_Task_Id.
An exception propagated from a handler that is invoked as part of the termination of a task has no effect.
Erroneous Execution
17/2For a call of Set_Specific_Handler or Specific_Handler, if the task identified by T no longer exists, the execution of the program is erroneous.