Skip to main content

7.6 Assignment and Finalization

danger

This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue

1

[ Three kinds of actions are fundamental to the manipulation of objects: initialization, finalization, and assignment. Every object is initialized, either explicitly or by default, after being created (for example, by an object_declaration or allocator). Every object is finalized before being destroyed (for example, by leaving a subprogram_body containing an object_declaration, or by a call to an instance of Unchecked_Deallocation). An assignment operation is used as part of assignment_statements, explicit initialization, parameter passing, and other operations.

2

Default definitions for these three fundamental operations are provided by the language, but a controlled type gives the user additional control over parts of these operations. In particular, the user can define, for a controlled type, an Initialize procedure which is invoked immediately after the normal default initialization of a controlled object, a Finalize procedure which is invoked immediately before finalization of any of the components of a controlled object, and an Adjust procedure which is invoked as the last step of an assignment to a (nonlimited) controlled object.]

2.a
glossary entry
A controlled type supports user-defined assignment and finalization. Objects are always finalized before being destroyed.
3
3.a/2
ramification
Here's the basic idea of initialization, value adjustment, and finalization, whether or not user defined: When an object is created, if it is explicitly assigned an initial value, the object is either built-in-place from an aggregate or function call (in which case neither Adjust nor Initialize is applied), or the assignment copies and adjusts the initial value. Otherwise, Initialize is applied to it (except in the case of an aggregate as a whole). An assignment_statement finalizes the target before copying in and adjusting the new value. Whenever an object goes away, it is finalized. Calls on Initialize and Adjust happen bottom-up; that is, components first, followed by the containing object. Calls on Finalize happen top-down; that is, first the containing object, and then its components. These ordering rules ensure that any components will be in a well-defined state when Initialize, Adjust, or Finalize is applied to the containing object.

Static Semantics​

4

The following language-defined library package exists:

5/5
{8652/0020} package Ada.Finalization 
    with Pure, Nonblocking => False is 
6/5
type Controlled is abstract tagged private 
       with  Preelaborable_Initialization ;
7/2
procedure Initialize (Object : in out Controlled) is null;
    procedure Adjust     (Object : in out Controlled) is null;
    procedure Finalize   (Object : in out Controlled) is null;
8/5
type Limited_Controlled is abstract tagged limited private 
       with  Preelaborable_Initialization ;
9/2
procedure Initialize (Object : in out Limited_Controlled) is null;
    procedure Finalize   (Object : in out Limited_Controlled) is null;
private
    ... -- not specified by the language
end Ada.Finalization;
9.a/5
reason
This package must allow blocking (Nonblocking => False) for compatibility. The purpose of this package is to provide a template for overriding user-defined routines; and such routines can only allow blocking if the root type does so. Users can still declare their overridding routines nonblocking if they wish.
10/2

A controlled type is a descendant of Controlled or Limited_Controlled. The predefined "=" operator of type Controlled always returns True, [since this operator is incorporated into the implementation of the predefined equality operator of types derived from Controlled, as explained in 4.5.2.] The type Limited_Controlled is like Controlled, except that it is limited and it lacks the primitive subprogram Adjust.

10.a
discussion
We say “nonlimited controlled type” (rather than just “controlled type”;) when we want to talk about descendants of Controlled only.
10.b
reason
We considered making Adjust and Finalize abstract. However, a reasonable coding convention is e.g. for Finalize to always call the parent's Finalize after doing whatever work is needed for the extension part. (Unlike CLOS, we have no way to do that automatically in Ada 95.) For this to work, Finalize cannot be abstract. In a generic unit, for a generic formal abstract derived type whose ancestor is Controlled or Limited_Controlled, calling the ancestor's Finalize would be illegal if it were abstract, even though the actual type might have a concrete version.
10.c
note
Types Controlled and Limited_Controlled are abstract, even though they have no abstract primitive subprograms. It is not clear that they need to be abstract, but there seems to be no harm in it, and it might make an implementation's life easier to know that there are no objects of these types — in case the implementation wishes to make them “magic” in some way.
10.d/2
note
For Ada 2005, we considered making these types interfaces. That would have the advantage of allowing them to be added to existing trees. But that was rejected both because it would cause massive disruptions to existing implementations, and because it would be very incompatible due to the "no hidden interfaces" rule. The latter rule would prevent a tagged private type from being completed with a derivation from Controlled or Limited_Controlled — a very common idiom.
10.1/2

A type is said to need finalization if:

10.2/2
  • it is a controlled type, a task type or a protected type; or
    • 10.3/3
  • it has a component whose type needs finalization; or
    • 10.4/3
  • it is a class-wide type; or
    • 10.5/3
  • it is a partial view whose full view needs finalization; or
    • 10.6/2
  • it is one of a number of language-defined types that are explicitly defined to need finalization.
10.e/2
ramification
The fact that a type needs finalization does not require it to be implemented with a controlled type. It just has to be recognized by the No_Nested_Finalization restriction.
10.f/2
note
This property is defined for the type, not for a particular view. That's necessary as restrictions look in private parts to enforce their restrictions; the point is to eliminate all controlled parts, not just ones that are visible.

Dynamic Semantics​

11/2

During the elaboration or evaluation of a construct that causes an object to be initialized by default, for every controlled subcomponent of the object that is not assigned an initial value (as defined in 3.3.1), Initialize is called on that subcomponent. Similarly, if the object that is initialized by default as a whole is controlled, Initialize is called on the object.

12/2

{8652/0021} For an extension_aggregate whose ancestor_part is a subtype_mark denoting a controlled subtype, the Initialize procedure of the ancestor type is called, unless that Initialize procedure is abstract.

12.a
discussion
Example:
12.b
type T1 is new Controlled with
    record
        ... -- some components might have defaults
    end record;
12.ctype T2 is new Controlled with
    record
        X : T1; -- no default
        Y : T1 := ...; -- default
    end record;
12.dA : T2;
B : T2 := ...;
12.e
note
As part of the elaboration of A's declaration, A.Y is assigned a value; therefore Initialize is not applied to A.Y. Instead, Adjust is applied to A.Y as part of the assignment operation. Initialize is applied to A.X and to A, since those objects are not assigned an initial value. The assignment to A.Y is not considered an assignment to A.
12.f
note
For the elaboration of B's declaration, Initialize is not called at all. Instead the assignment adjusts B's value; that is, it applies Adjust to B.X, B.Y, and B.
12.f.1/2
note
{8652/0021} The ancestor_part of an extension_aggregate, <> in aggregates, and the return object of an extended_return_statement are handled similarly.
13

Initialize and other initialization operations are done in an arbitrary order, except as follows. Initialize is applied to an object after initialization of its subcomponents, if any [(including both implicit initialization and Initialize calls)]. If an object has a component with an access discriminant constrained by a per-object expression, Initialize is applied to this component after any components that do not have such discriminants. For an object with several components with such a discriminant, Initialize is applied to them in order of their component_declarations. For an allocator, any task activations follow all calls on Initialize.

13.a
reason
The fact that Initialize is done for subcomponents first allows Initialize for a composite object to refer to its subcomponents knowing they have been properly initialized.
13.b
note
The fact that Initialize is done for components with access discriminants after other components allows the Initialize operation for a component with a self-referential access discriminant to assume that other components of the enclosing object have already been properly initialized. For multiple such components, it allows some predictability.
14

When a target object with any controlled parts is assigned a value, [either when created or in a subsequent assignment_statement,] the assignment operation proceeds as follows:

15
  • The value of the target becomes the assigned value.
    • 16
  • The value of the target is adjusted.
16.a
ramification
If any parts of the object are controlled, abort is deferred during the assignment operation.
17/3

To adjust the value of a composite object, the values of the components of the object are first adjusted in an arbitrary order, and then, if the object is nonlimited controlled, Adjust is called. Adjusting the value of an elementary object has no effect[, nor does adjusting the value of a composite object with no controlled parts.]

17.a/3
ramification
Adjustment is never actually performed for values of an immutably limited type, since all assignment operations for such types are required to be built-in-place. Even so, we still define adjustment for all types in order that the canonical semantics is well-defined.
17.b/3
reason
The verbiage in the Initialize rule about access discriminants constrained by per-object expressions is not necessary here, since such types are either limited or do not have defaults, so the discriminant can only be changed by an assignment to an outer object. Such an assignment could happen only before any adjustments or (if part of an outer Adjust) only after any inner (component) adjustments have completed.
18

For an assignment_statement, [ after the name and expression have been evaluated, and any conversion (including constraint checking) has been done,] an anonymous object is created, and the value is assigned into it; [that is, the assignment operation is applied]. [(Assignment includes value adjustment.)] The target of the assignment_statement is then finalized. The value of the anonymous object is then assigned into the target of the assignment_statement. Finally, the anonymous object is finalized. [As explained below, the implementation may eliminate the intermediate anonymous object, so this description subsumes the one given in 5.2, “Assignment Statements”.]

18.a
reason
An alternative design for user-defined assignment might involve an Assign operation instead of Adjust:
18.b
procedure Assign(Target : in out Controlled; Source : in out Controlled);
18.c
note
Or perhaps even a syntax like this:
18.d
procedure ":="(Target : in out Controlled; Source : in out Controlled);
18.e
note
Assign (or ":=") would have the responsibility of doing the copy, as well as whatever else is necessary. This would have the advantage that the Assign operation knows about both the target and the source at the same time — it would be possible to do things like reuse storage belonging to the target, for example, which Adjust cannot do. However, this sort of design would not work in the case of unconstrained discriminated variables, because there is no way to change the discriminants individually. For example:
18.f
type Mutable(D : Integer := 0) is
    record
        X : Array_Of_Controlled_Things(1..D);
        case D is
            when 17 => Y : Controlled_Thing;
            when others => null;
        end D;
    end record;
18.g
note
An assignment to an unconstrained variable of type Mutable can cause some of the components of X, and the component Y, to appear and/or disappear. There is no way to write the Assign operation to handle this sort of case.
18.h
note
Forbidding such cases is not an option — it would cause generic contract model violations.
18.1/5

When a function call or aggregate is used to initialize an object, the result of the function call or aggregate is an anonymous object, which is assigned into the newly-created object. For such an assignment, the anonymous object may be built in place, in which case the assignment does not involve any copying. Under certain circumstances, the anonymous object is required to be built in place. In particular:

18.i/3
discussion
We say assignment to built-in-place objects does not involve copying, which matches the intended implementation (see below). Of course, the implementation can do any copying it likes, if it can make such copying semantically invisible (by patching up access values to point to the copy, and so forth).
18.2/3
  • If the full type of any part of the object is immutably limited, the anonymous object is built in place.
18.j/3
reason
We talk about the full types being immutably limited, as this is independent of the view of a type (in the same way that it is for determining the technique of parameter passing). That is, privacy is ignored for this purpose.
18.k/3
note
For function calls, we only require building in place for immutably limited types. These are the types that would have been return-by-reference types in Ada 95. We limited the requirement because we want to minimize disruption to Ada 95 implementations and users.
18.l/5
note
To be honest: This is a dynamic property and is determined by the specific type of the parts of the actual object. In particular, if a part has a class-wide type, the tag of the object might need to be examined in order to determine if build-in-place is required. However, we expect that most Ada implementations will determine this property at compile-time using some assume-the-worst algorithm in order to choose the appropriate method to implement a given call or aggregate. In addition, there is no attribute or other method for a program to determine if a particular object has this property (or not), so there is no value to a more careful description of this rule.
18.3/3
  • In the case of an aggregate, if the full type of any part of the newly-created object is controlled, the anonymous object is built in place.
18.m/3
reason
This is necessary to prevent elaboration problems with deferred constants of controlled types. Consider:
18.m.1/3
package P is
   type Dyn_String is private;
   Null_String : constant Dyn_String;
   ...
private
   type Dyn_String is new Ada.Finalization.Controlled with ...
   procedure Finalize(X : in out Dyn_String);
   procedure Adjust(X : in out Dyn_String);

   Null_String : constant Dyn_String :=
      (Ada.Finalization.Controlled with ...);
   ...
end P;
18.m.2/3
note
When Null_String is elaborated, the bodies of Finalize and Adjust clearly have not been elaborated. Without this rule, this declaration would necessarily raise Program_Error (unless the permissions given below are used by the implementation).
18.n/3
ramification
An aggregate with a controlled part used in the return expression of a simple_return_statement has to be built in place in the anonymous return object, as this is similar to an object declaration. (This is a change from Ada 95, but it is not an inconsistency as it only serves to restrict implementation choices.) But this only covers the aggregate; a separate anonymous return object can still be used unless it too is required to be built in place.
18.o/3
note
Similarly, an aggregate that has a controlled part but is not itself controlled and that is used to initialize an object also has to be built in place. This is also a change from Ada 95, but it is not an inconsistency as it only serves to restrict implementation choices. This avoids problems if a type like Dyn_String (in the example above) is used as a component in a type used as a deferred constant in package P.
18.4/3
  • In other cases, it is unspecified whether the anonymous object is built in place.
18.p/3
reason
This is left unspecified so the implementation can use any appropriate criteria for determining when to build in place. That includes making the decision on a call-by-call basis. Reasonable programs will not care what decision is made here anyway.
18.5/3

Notwithstanding what this document says elsewhere, if an object is built in place:

18.6/3
  • Upon successful completion of the return statement or aggregate, the anonymous object mutates into the newly-created object; that is, the anonymous object ceases to exist, and the newly-created object appears in its place.
    • 18.7/3
  • Finalization is not performed on the anonymous object.
    • 18.8/3
  • Adjustment is not performed on the newly-created object.
    • 18.9/3
  • All access values that designate parts of the anonymous object now designate the corresponding parts of the newly-created object.
    • 18.10/3
  • All renamings of parts of the anonymous object now denote views of the corresponding parts of the newly-created object.
    • 18.11/3
  • Coextensions of the anonymous object become coextensions of the newly-created object.
18.q/5
note
To be honest: This “mutating” does not necessarily happen atomically with respect to abort and other tasks. For example, if a function call is used as the ancestor part of an extension_aggregate, then the tag of the anonymous object (the function result) will be different from the tag of the newly-created object (the ancestor part of the extension_aggregate). In implementation terms, this involves modifying the tag field. If the current task is aborted during this modification, the object might become abnormal. Likewise, if some other task accesses the tag field during this modification, it constitutes improper use of shared variables, and is erroneous.
18.r/3
implementation note
The intended implementation is that the anonymous object is allocated at the same address as the newly-created object. Thus, no run-time action is required to cause all the access values and renamings to point to the right place. They just point to the newly-created object, which is what the return object has magically “mutated into”.
18.s/3
note
There is no requirement that 'Address of the return object is equal to 'Address of the newly-created object, but that will be true in the intended implementation.
18.t/3
note
For a function call, if the size of the newly-created object is known at the call site, the object is allocated there, and the address is implicitly passed to the function; the return object is created at that address. Otherwise, a storage pool is implicitly passed to the function; the size is determined at the point of the return statement, and passed to the Allocate procedure. The address returned by the storage pool is returned from the function, and the newly-created object uses that same address. If the return statement is left without returning (via an exception or a goto, for example), then Deallocate is called. The storage pool might be a dummy pool that represents “allocate on the stack”.
18.u/3
note
The Tag of the newly-created object may be different from that of the result object. Likewise, the master and accessibility level may be different.
18.v/3
note
An alternative implementation model might allow objects to move around to different addresses. In this case, access values and renamings would need to be modified at run time. It seems that this model requires the full power of tracing garbage collection.

Implementation Permissions​

19/3

An implementation is allowed to relax the above rules for assignment_statements in the following ways:

19.a/3
note
This paragraph was deleted.
19.b/5
ramification
The relaxations apply only to nonlimited types, as assignment_statements are not allowed for limited types. This is important so that the programmer can count on stricter semantics for limited controlled types.
20/5
  • If an object is assigned the value of that same object, the implementation may omit the entire assignment .
20.a
ramification
In other words, even if an object is controlled and a combination of Finalize and Adjust on the object might have a net side effect, they need not be performed.
21/3
  • For assignment of a noncontrolled type, the implementation may finalize and assign each component of the variable separately (rather than finalizing the entire variable and assigning the entire new value) unless a discriminant of the variable is changed by the assignment.
21.a
reason
For example, in a slice assignment, an anonymous object is not necessary if the slice is copied component-by-component in the right direction, since array types are not controlled (although their components may be). Note that the direction, and even the fact that it's a slice assignment, can in general be determined only at run time.
21.b/3
ramification
This potentially breaks a single assignment operation into many, and thus abort deferral (see 9.8) needs to last only across an individual component assignment when the component has a controlled part. It is only important that the copy step is not separated (by an abort) from the adjust step, so aborts between component assignments is not harmful.
22/5
  • The implementation may avoid creating an anonymous object if the value being assigned is the result of evaluating a name denoting an object (the source object) whose storage cannot overlap with the target. If the source object can overlap with the target object, then the implementation can avoid the need for an intermediary anonymous object by exercising one of the above permissions and perform the assignment one component at a time (for an overlapping array assignment), or not at all (for an assignment where the target and the source of the assignment are the same object).
22.a/3
ramification
If the anonymous object is eliminated by this permission, there is no anonymous object to be finalized and thus the Finalize call on it is eliminated.
22.b/3
note
Note that if the anonymous object is eliminated but the new value is not built in place in the target object, that Adjust must be called directly on the target object as the last step of the assignment, since some of the subcomponents may be self-referential or otherwise position-dependent. This Adjust can be eliminated only by using one of the following permissions.
23/2

Furthermore, an implementation is permitted to omit implicit Initialize, Adjust, and Finalize calls and associated assignment operations on an object of a nonlimited controlled type provided that:

24/2
  • any omitted Initialize call is not a call on a user-defined Initialize procedure, and
24.a/2
note
To be honest: This does not apply to any calls to a user-defined Initialize routine that happen to occur in an Adjust or Finalize routine. It is intended that it is never necessary to look inside of an Adjust or Finalize routine to determine if the call can be omitted.
24.b/2
reason
We don't want to eliminate objects for which the Initialize might have side effects (such as locking a resource).
25/2
  • any usage of the value of the object after the implicit Initialize or Adjust call and before any subsequent Finalize call on the object does not change the external effect of the program, and
    • 26/2
  • after the omission of such calls and operations, any execution of the program that executes an Initialize or Adjust call on an object or initializes an object by an aggregate will also later execute a Finalize call on the object and will always do so prior to assigning a new value to the object, and
    • 27/2
  • the assignment operations associated with omitted Adjust calls are also omitted.
28/2

This permission applies to Adjust and Finalize calls even if the implicit calls have additional external effects.

28.a/2
reason
The goal of the above permissions is to allow typical dead assignment and dead variable removal algorithms to work for nonlimited controlled types. We require that “pairs” of Initialize/Adjust/Finalize operations are removed. (These aren't always pairs, which is why we talk about “any execution of the program”.)

Extensions to Ada 83​

28.b
note
Controlled types and user-defined finalization are new to Ada 95. (Ada 83 had finalization semantics only for masters of tasks.)

Extensions to Ada 95​

28.c/2
correction
Amendment Types Controlled and Limited_Controlled now have Preelaborable_Initialization, so that objects of types derived from these types can be used in preelaborated packages.

Wording Changes from Ada 95​

28.d/2
note
{8652/0020} Corrigendum: Clarified that Ada.Finalization is a remote types package.
28.e/2
note
{8652/0021} Corrigendum: Added wording to clarify that the default initialization (whatever it is) of an ancestor part is used.
28.f/2
note
{8652/0022} Corrigendum: Clarified that Adjust is never called on an aggregate used for the initialization of an object or subaggregate, or passed as a parameter.
28.g/2
note
Additional optimizations are allowed for nonlimited controlled types. These allow traditional dead variable elimination to be applied to such types.
28.h/2
note
Corrected the build-in-place requirement for controlled aggregates to be consistent with the requirements for limited types.
28.i/2
note
The operations of types Controlled and Limited_Controlled are now declared as null procedures (see 6.7) to make the semantics clear (and to provide a good example of what null procedures can be used for).
28.j/2
note
Types that need finalization are defined; this is used by the No_Nested_Finalization restriction (see D.7, “Tasking Restrictions”).
28.k/2
note
Generalized the description of objects that have Initialize called for them to say that it is done for all objects that are initialized by default. This is needed so that all of the new cases are covered.

Extensions to Ada 2005​

28.l/3
note
Package Ada.Finalization now has Pure categorization, so it can be mentioned for any package. Note that this does not change the preelaborability of objects descended from Controlled and Limited_Controlled.

Wording Changes from Ada 2005​

28.m/3
correction
Eliminated coextensions from the “needs finalization” rules, as this cannot be determined in general in the compilation unit that declares the type. (The designated type of the coextension may have been imported as a limited view.) Uses of “needs finalization” need to ensure that coextensions are handled by other means (such as in No_Nested_Finalization – see D.7) or that coextensions cannot happen.
28.n/3
correction
Corrected the “needs finalization” rules to include class-wide types, as a future extension can include a part that needs finalization.
28.o/3
correction
Corrected the “needs finalization” rules to clearly say that they ignore privacy.
28.p/3
correction
Changed “built in place” to Dynamic Semantics and centralized the rules here. This eliminates the fiction that built in place is just a combination of a permission and a requirement; it clearly has noticeable semantic effects. This wording change is not intended to change the semantics of any correct Ada program.

7.6.1 Completion and Finalization​

1

[This subclause defines completion and leaving of the execution of constructs and entities. A master is the execution of a construct that includes finalization of local objects after it is complete (and after waiting for any local tasks — see 9.3), but before leaving. Other constructs and entities are left immediately upon completion. ]

Dynamic Semantics​

2/2

The execution of a construct or entity is complete when the end of that execution has been reached, or when a transfer of control (see 5.1) causes it to be abandoned. Completion due to reaching the end of execution, or due to the transfer of control of an exit_statement, return statement, goto_statement, or requeue_statement or of the selection of a terminate_alternative is normal completion. Completion is abnormal otherwise [— when control is transferred out of a construct due to abort or the raising of an exception].

2.a
discussion
Don't confuse the run-time concept of completion with the compile-time concept of completion defined in 3.11.1.
3/5

After execution of a construct or entity is complete, it is left, meaning that execution continues with the next action, as defined for the execution that is taking place. Leaving an execution happens immediately after its completion, except in the case of the execution of a master construct : a body other than a package_body; a statement; or an expression, function_call, or range that is not part of an enclosing expression, function_call, range, or simple_statement other than a simple_return_statement. The term master by itself refers to the execution of a master construct. A master is finalized after it is complete, and before it is left.

3.a/2
reason
Expressions and statements are masters so that objects created by subprogram calls (in aggregates, allocators for anonymous access-to-object types, and so on) are finalized and have their tasks awaited before the expressions or statements are left. Note that expressions like the condition of an if_statement are masters, because they are not enclosed by a simple_statement. Similarly, a function_call which is renamed is a master, as it is not in a simple_statement.
3.b/2
note
We have to include function_calls in the contexts that do not cause masters to occur so that expressions contained in a function_call (that is not part of an expression or simple_statement) do not individually become masters. We certainly do not want the parameter expressions of a function_call to be separate masters, as they would then be finalized before the function is called.
3.c/2
ramification
The fact that a function_call is a master does not change the accessibility of the return object denoted by the function_call; that depends on the use of the function_call. The function_call is the master of any short-lived entities (such as aggregates used as parameters of types with task or controlled parts).
3.c.1/5
glossary entry
A master is the execution of a master construct. Each object and task is associated with a master. When a master is left, associated tasks are awaited and associated objects are finalized.
4
4.a.1/5
glossary entry
A master construct is one of certain executable constructs listed in 7.6.1. Execution of a master construct is a master, with which objects and tasks are associated for the purposes of waiting and finalization.
5
5.a
ramification
As explained in 3.10.2, the set of objects with the same accessibility level as that of the master includes objects declared immediately within the master, objects declared in nested packages, objects created by allocators (if the ultimate ancestor access type is declared in one of those places) and subcomponents of all of these things. If an object was already finalized by Unchecked_Deallocation, then it is not finalized again when the master is left.
5.b
note
Note that any object whose accessibility level is deeper than that of the master would no longer exist; those objects would have been finalized by some inner master. Thus, after leaving a master, the only objects yet to be finalized are those whose accessibility level is less deep than that of the master.
5.c
note
To be honest: Subcomponents of objects due to be finalized are not finalized by the finalization of the master; they are finalized by the finalization of the containing object.
5.d
reason
We need to finalize subcomponents of objects even if the containing object is not going to get finalized because it was not fully initialized. But if the containing object is finalized, we don't want to require repeated finalization of the subcomponents, as might normally be implied by the recursion in finalization of a master and the recursion in finalization of an object.
5.e
note
To be honest: Formally, completion and leaving refer to executions of constructs or entities. However, the standard sometimes (informally) refers to the constructs or entities whose executions are being completed. Thus, for example, “the subprogram call or task is complete” really means “the execution of the subprogram call or task is complete”.
6

For the finalization of an object:

7/3
  • If the full type of the object is an elementary type, finalization has no effect;
7.a/3
reason
We say “full type” in this and the following bullets as privacy is ignored for the purpose of determining the finalization actions of an object; that is as expected for Dynamic Semantics rules.
8/3
  • If the full type of the object is a tagged type, and the tag of the object identifies a controlled type, the Finalize procedure of that controlled type is called;
    • 9/3
  • If the full type of the object is a protected type, or if the full type of the object is a tagged type and the tag of the object identifies a protected type, the actions defined in 9.4 are performed;
    • 10/3
  • If the full type of the object is a composite type, then after performing the above actions, if any, every component of the object is finalized in an arbitrary order, except as follows: if the object has a component with an access discriminant constrained by a per-object expression, this component is finalized before any components that do not have such discriminants; for an object with several components with such a discriminant, they are finalized in the reverse of the order of their component_declarations;
10.a
reason
This allows the finalization of a component with an access discriminant to refer to other components of the enclosing object prior to their being finalized.
10.b/4
note
To be honest: The components discussed here are all of the components that the object actually has, not just those components that are statically identified by the type of the object. These can be different if the object has a class-wide type.
10.1/2
  • If the object has coextensions (see 3.10.2), each coextension is finalized after the object whose access discriminant designates it.
10.c/3
ramification
In the case of an aggregate or function call that is used (in its entirety) to directly initialize a part of an object, the coextensions of the result of evaluating the aggregate or function call are transfered to become coextensions of the object being initialized and are not finalized until the object being initialized is ultimately finalized, even if an anonymous object is created as part of the operation.
11

Immediately before an instance of Unchecked_Deallocation reclaims the storage of an object, the object is finalized. [If an instance of Unchecked_Deallocation is never applied to an object created by an allocator, the object will still exist when the corresponding master completes, and it will be finalized then.]

12/3

The finalization of a master performs finalization of objects created by declarations in the master in the reverse order of their creation. After the finalization of a master is complete, the objects finalized as part of its finalization cease to exist, as do any types and subtypes defined and created within the master.

12.a/3
note
This paragraph was deleted.
12.b/3
note
This paragraph was deleted.
12.c/3
note
This paragraph was deleted.
12.d/3
note
This paragraph was deleted.
12.e
ramification
Note that a deferred constant declaration does not create the constant; the full constant declaration creates it. Therefore, the order of finalization depends on where the full constant declaration occurs, not the deferred constant declaration.
12.f
note
An imported object is not created by its declaration. It is neither initialized nor finalized.
12.g
implementation note
An implementation has to ensure that the storage for an object is not reclaimed when references to the object are still possible (unless, of course, the user explicitly requests reclamation via an instance of Unchecked_Deallocation). This implies, in general, that objects cannot be deallocated one by one as they are finalized; a subsequent finalization might reference an object that has been finalized, and that object had better be in its (well-defined) finalized state.
12.1/3

Each nonderived access type T has an associated collection, which is the set of objects created by allocators of T, or of types derived from T. Unchecked_Deallocation removes an object from its collection. Finalization of a collection consists of finalization of each object in the collection, in an arbitrary order. The collection of an access type is an object implicitly declared at the following place:

12.h/3
ramification
The place of the implicit declaration determines when allocated objects are finalized. For multiple collections declared at the same place, we do not define the order of their implicit declarations.
12.i/3
note
Finalization of allocated objects is done according to the (ultimate ancestor) allocator type, not according to the storage pool in which they are allocated. Pool finalization might reclaim storage (see 13.11, “Storage Management”), but has nothing (directly) to do with finalization of the pool elements.
12.j/3
note
Note that finalization is done only for objects that still exist; if an instance of Unchecked_Deallocation has already gotten rid of a given pool element, that pool element will not be finalized when the master is left.
12.k/3
reason
Note that we talk about the type of the allocator here. There may be access values of a (general) access type pointing at objects created by allocators for some other type; these are not (necessarily) finalized at this point.
12.2/3
  • For a named access type, the first freezing point (see 13.14) of the type.
12.l/3
reason
The freezing point of the ultimate ancestor access type is chosen because before that point, pool elements cannot be created, and after that point, access values designating (parts of) the pool elements can be created. This is also the point after which the pool object cannot have been declared. We don't want to finalize the pool elements until after anything finalizing objects that contain access values designating them. Nor do we want to finalize pool elements after finalizing the pool object itself.
12.3/3
  • For the type of an access parameter, the call that contains the allocator.
    • 12.4/3
  • For the type of an access result, within the master of the call (see 3.10.2).
12.m/3
note
To be honest: We mean at a place within the master consistent with the execution of the call within the master. We don't say that normatively, as it is difficult to explain that when the master of the call need not be the master that immediately includes the call (such as when an anonymous result is converted to a named access type).
12.5/3
  • For any other anonymous access type, the first freezing point of the innermost enclosing declaration.
13/2

The target of an assignment_statement is finalized before copying in the new value, as explained in 7.6.

14/3

{8652/0021} The master of an object is the master enclosing its creation whose accessibility level (see 3.10.2) is equal to that of the object, except in the case of an anonymous object representing the result of an aggregate or function call. If such an anonymous object is part of the result of evaluating the actual parameter expression for an explicitly aliased parameter of a function call, the master of the object is the innermost master enclosing the evaluation of the aggregate or function call, excluding the aggregate or function call itself. Otherwise, the master of such an anonymous object is the innermost master enclosing the evaluation of the aggregate or function call, which may be the aggregate or function call itself.

14.a/2
note
This paragraph was deleted.
14.b/2
This paragraph was deleted.
14.c/2
note
This paragraph was deleted.
14.d/2
reason
This effectively imports all of the special rules for the accessibility level of renames, allocators, and so on, and applies them to determine where objects created in them are finalized. For instance, the master of a rename of a subprogram is that of the renamed subprogram.
14.e/3
note
In 3.10.2 we assign an accessibility level to the result of an aggregate or function call that is used to directly initialize a part of an object based on the object being initialized. This is important to ensure that any access discriminants denote objects that live at least as long as the object being initialized. However, if the result of the aggregate or function call is not built directly in the target object, but instead is built in an anonymous object that is then assigned to the target, the anonymous object needs to be finalized after the assignment rather than persisting until the target object is finalized (but not its coextensions). (Note than an implementation is never required to create such an anonymous object, and in some cases is required to not have such a separate object, but rather to build the result directly in the target.)
14.f/3
note
The special case for explicitly aliased parameters of functions is needed for the same reason, as access discriminants of the returned object may designate one of these parameters. In that case, we want to lengthen the lifetime of the anonymous objects as long as the possible lifetime of the result.
14.g/3
note
We don't do a similar change for other kinds of calls, because the extended lifetime of the parameters adds no value, but could constitute a storage leak. For instance, such an anonymous object created by a procedure call in the elaboration part of a package body would have to live until the end of the program, even though it could not be used after the procedure returns (other than via Unchecked_Access).
14.h/3
ramification
Note that the lifetime of the master given to anonymous objects in explicitly aliased parameters of functions is not necessarily as long as the lifetime of the master of the object being initialized (if the function call is used to initialize an allocator, for instance). In that case, the accessibility check on explicitly aliased parameters will necessarily fail if any such anonymous objects exist. This is necessary to avoid requiring the objects to live as long as the access type or having the implementation complexity of an implicit coextension.
14.1/3

{8652/0023} In the case of an expression that is a master, finalization of any (anonymous) objects occurs after completing evaluation of the expression and all use of the objects, prior to starting the execution of any subsequent construct.

Bounded (Run-Time) Errors​

15/1

{8652/0023} It is a bounded error for a call on Finalize or Adjust that occurs as part of object finalization or assignment to propagate an exception. The possible consequences depend on what action invoked the Finalize or Adjust operation:

15.a
ramification
It is not a bounded error for Initialize to propagate an exception. If Initialize propagates an exception, then no further calls on Initialize are performed, and those components that have already been initialized (either explicitly or by default) are finalized in the usual way.
15.a.1/1
note
{8652/0023} It also is not a bounded error for an explicit call to Finalize or Adjust to propagate an exception. We do not want implementations to have to treat explicit calls to these routines specially.
16
  • For a Finalize invoked as part of an assignment_statement, Program_Error is raised at that point.
    • 17/5
  • {8652/0024} For an Adjust invoked as part of assignment operations other than those invoked as part of an assignment_statement, some of the adjustments due to be performed can be performed, and then Program_Error is raised. During its propagation, finalization may be applied to objects whose Adjust failed. For an Adjust invoked as part of an assignment_statement, any other adjustments due to be performed are performed, and then Program_Error is raised.
17.a/2
reason
{8652/0024} In the case of assignments that are part of initialization, there is no need to complete all adjustments if one propagates an exception, as the object will immediately be finalized. So long as a subcomponent is not going to be finalized, it need not be adjusted, even if it is initialized as part of an enclosing composite assignment operation for which some adjustments are performed. However, there is no harm in an implementation making additional Adjust calls (as long as any additional components that are adjusted are also finalized), so we allow the implementation flexibility here. On the other hand, for an assignment_statement, it is important that all adjustments be performed, even if one fails, because all controlled subcomponents are going to be finalized. Other kinds of assignment are more like initialization than assignment_statements, so we include them as well in the permission.
17.a.1/1
ramification
{8652/0024} Even if an Adjust invoked as part of the initialization of a controlled object propagates an exception, objects whose initialization (including any Adjust or Initialize calls) successfully completed will be finalized. The permission above only applies to objects whose Adjust failed. Objects for which Adjust was never even invoked must not be finalized.
18
  • For a Finalize invoked as part of a call on an instance of Unchecked_Deallocation, any other finalizations due to be performed are performed, and then Program_Error is raised.
18.a.1/1
discussion
{8652/0104} The standard does not specify if storage is recovered in this case. If storage is not recovered (and the object continues to exist), Finalize may be called on the object again (when the allocator's master is finalized).
18.1/3
  • This paragraph was deleted.{8652/0023}
    • 18.2/1
  • {8652/0023} For a Finalize invoked due to reaching the end of the execution of a master, any other finalizations associated with the master are performed, and Program_Error is raised immediately after leaving the master.
18.a/3
discussion
This rule covers both ordinary objects created by a declaration, and anonymous objects created as part of evaluating an expression. All contexts that create objects that need finalization are defined to be masters.
19/2
  • For a Finalize invoked by the transfer of control of an exit_statement, return statement, goto_statement, or requeue_statement, Program_Error is raised no earlier than after the finalization of the master being finalized when the exception occurred, and no later than the point where normal execution would have continued. Any other finalizations due to be performed up to that point are performed before raising Program_Error.
19.a
ramification
For example, upon leaving a block_statement due to a goto_statement, the Program_Error would be raised at the point of the target statement denoted by the label, or else in some more dynamically nested place, but not so nested as to allow an exception_handler that has visibility upon the finalized object to handle it. For example,
19.b
procedure Main is
begin
    <<The_Label>>
    Outer_Block_Statement : declare
        X : Some_Controlled_Type;
    begin
        Inner_Block_Statement : declare
            Y : Some_Controlled_Type;
            Z : Some_Controlled_Type;
        begin
            goto The_Label;
        exception
            when Program_Error => ... -- Handler number 1.
        end;
    exception
        when Program_Error => ... -- Handler number 2.
    end;
exception
    when Program_Error => ... -- Handler number 3.
end Main;
19.c/5
note
The goto_statement will first cause Finalize(Z ) to be called. Suppose that Finalize(Z ) propagates an exception. Program_Error will be raised after leaving Inner_Block_Statement, but before leaving Main. Thus, handler number 1 cannot handle this Program_Error; it will be handled either by handler number 2 or handler number 3. If it is handled by handler number 2, then Finalize(Y ) will be done before executing the handler. If it is handled by handler number 3, then Finalize(Y ) and Finalize(X) will both be done before executing the handler.
20
  • For a Finalize invoked by a transfer of control that is due to raising an exception, any other finalizations due to be performed for the same master are performed; Program_Error is raised immediately after leaving the master.
20.a/5
ramification
If, in the above example, the goto_statement were replaced by a raise_statement, then the Program_Error would be handled by handler number 2, and Finalize(Y ) would be done before executing the handler.
20.b
reason
We considered treating this case in the same way as the others, but that would render certain exception_handlers useless. For example, suppose the only exception_handler is one for others in the main subprogram. If some deeply nested call raises an exception, causing some Finalize operation to be called, which then raises an exception, then normal execution “would have continued” at the beginning of the exception_handler. Raising Program_Error at that point would cause that handler's code to be skipped. One would need two nested exception_handlers to be sure of catching such cases!
20.c
note
On the other hand, the exception_handler for a given master should not be allowed to handle exceptions raised during finalization of that master.
21
  • For a Finalize invoked by a transfer of control due to an abort or selection of a terminate alternative, the exception is ignored; any other finalizations due to be performed are performed.
21.a
ramification
This case includes an asynchronous transfer of control.
21.b
note
To be honest: This violates the general principle that it is always possible for a bounded error to raise Program_Error (see 1.1.5, “Classification of Errors”).

Implementation Permissions​

21.1/3

If the execution of an allocator propagates an exception, any parts of the allocated object that were successfully initialized may be finalized as part of the finalization of the innermost master enclosing the allocator.

21.c/3
reason
This allows deallocating the memory for the allocated object at the innermost master, preventing a storage leak. Otherwise, the object would have to stay around until the finalization of the collection that it belongs to, which could be the entire life of the program if the associated access type is library level.
21.2/3

The implementation may finalize objects created by allocators for an access type whose storage pool supports subpools (see 13.11.4) as if the objects were created (in an arbitrary order) at the point where the storage pool was elaborated instead of at the first freezing point of the access type.

21.d/3
ramification
This allows the finalization of such objects to occur later than they otherwise would, but still as part of the finalization of the same master. Accessibility rules in 13.11.4 ensure that it is the same master (usually that of the environment task).
21.e/5
implementation note
This permission is intended to allow the allocated objects to "belong" to the subpool objects and to allow those objects to be finalized at the time that the storage pool is finalized (if they are not finalized earlier). This is expected to ease implementation, as the remaining yet-to-be deallocated objects will only need to be accessible at run time from the subpool header and not also from the overall access type collection header. That is, they only need to belong to a single list, rather than two .
22/3
note
NOTE 1 The rules of Clause 10 imply that immediately prior to partition termination, Finalize operations are applied to library-level controlled objects (including those created by allocators of library-level access types, except those already finalized). This occurs after waiting for library-level tasks to terminate.
22.a
discussion
We considered defining a pragma that would apply to a controlled type that would suppress Finalize operations for library-level objects of the type upon partition termination. This would be useful for types whose finalization actions consist of simply reclaiming global heap storage, when this is already provided automatically by the environment upon program termination.
23
note
NOTE 2 A constant is only constant between its initialization and finalization. Both initialization and finalization are allowed to change the value of a constant.
24
note
NOTE 3 Abort is deferred during certain operations related to controlled types, as explained in 9.8. Those rules prevent an abort from causing a controlled object to be left in an ill-defined state.
25
note
NOTE 4 The Finalize procedure is called upon finalization of a controlled object, even if Finalize was called earlier, either explicitly or as part of an assignment; hence, if a controlled type is visibly controlled (implying that its Finalize primitive is directly callable), or is nonlimited (implying that assignment is allowed), its Finalize procedure is ideally designed to have no ill effect if it is applied a second time to the same object.
25.a
discussion
Or equivalently, a Finalize procedure should be “idempotent”; applying it twice to the same object should be equivalent to applying it once.
25.b
reason
A user-written Finalize procedure should be idempotent since it can be called explicitly by a client (at least if the type is "visibly" controlled). Also, Finalize is used implicitly as part of the assignment_statement if the type is nonlimited, and an abort is permitted to disrupt an assignment_statement between finalizing the left-hand side and assigning the new value to it (an abort is not permitted to disrupt an assignment operation between copying in the new value and adjusting it).
25.c/2
discussion
Either Initialize or Adjust, but not both, is applied to (almost) every controlled object when it is created: Initialize is done when no initial value is assigned to the object, whereas Adjust is done as part of assigning the initial value. The one exception is the object initialized by an aggregate (both the anonymous object created for an aggregate, or an object initialized by an aggregate that is built-in-place); Initialize is not applied to the aggregate as a whole, nor is the value of the aggregate or object adjusted.
25.d
note
All of the following use the assignment operation, and thus perform value adjustment:
25.e
  • the assignment_statement (see 5.2);
    • 25.f
  • explicit initialization of a stand-alone object (see 3.3.1) or of a pool element (see 4.8);
    • 25.g
  • default initialization of a component of a stand-alone object or pool element (in this case, the value of each component is assigned, and therefore adjusted, but the value of the object as a whole is not adjusted);
    • 25.h/2
  • function return, when the result is not built-in-place (adjustment of the result happens before finalization of the function);
    • 25.i
  • predefined operators (although the only one that matters is concatenation; see 4.5.3);
    • 25.j
  • generic formal objects of mode in (see 12.4); these are defined in terms of constant declarations; and
    • 25.k/5
  • aggregates (see 4.3), when the result is not built-in-place (in this case, the value of each component, and the ancestor part, for an extension_aggregate, is assigned, and therefore adjusted, but the value of the aggregate as a whole is not adjusted; neither is Initialize called);
25.l
note
The following also use the assignment operation, but adjustment never does anything interesting in these cases:
25.m
  • By-copy parameter passing uses the assignment operation (see 6.4.1), but controlled objects are always passed by reference, so the assignment operation never does anything interesting in this case. If we were to allow by-copy parameter passing for controlled objects, we would need to make sure that the actual is finalized before doing the copy back for [in] out parameters. The finalization of the parameter itself needs to happen after the copy back (if any), similar to the finalization of an anonymous function return object or aggregate object.
    • 25.n
  • For loops use the assignment operation (see 5.5), but since the type of the loop parameter is never controlled, nothing interesting happens there, either.
    • 25.n.1/2
  • Objects initialized by function results and aggregates that are built-in-place. In this case, the assignment operation is never executed, and no adjustment takes place. While built-in-place is always allowed, it is required for some types — see 7.5 and 7.6 — and that's important since limited types have no Adjust to call.
25.o/2
note
This paragraph was deleted.
25.p
note
Finalization of the parts of a protected object are not done as protected actions. It is possible (in pathological cases) to create tasks during finalization that access these parts in parallel with the finalization itself. This is an erroneous use of shared variables.
25.q
implementation note
One implementation technique for finalization is to chain the controlled objects together on a per-task list. When leaving a master, the list can be walked up to a marked place. The links needed to implement the list can be declared (privately) in types Controlled and Limited_Controlled, so they will be inherited by all controlled types.
25.r
note
Another implementation technique, which we refer to as the “PC-map” approach essentially implies inserting exception handlers at various places, and finalizing objects based on where the exception was raised.
25.s
note
The PC-map approach is for the compiler/linker to create a map of code addresses; when an exception is raised, or abort occurs, the map can be consulted to see where the task was executing, and what finalization needs to be performed. This approach was given in the Ada 83 Rationale as a possible implementation strategy for exception handling — the map is consulted to determine which exception handler applies.
25.t
note
If the PC-map approach is used, the implementation must take care in the case of arrays. The generated code will generally contain a loop to initialize an array. If an exception is raised part way through the array, the components that have been initialized must be finalized, and the others must not be finalized.
25.u
note
It is our intention that both of these implementation methods should be possible.

Wording Changes from Ada 83​

25.v/3
note
Finalization depends on the concepts of completion and leaving, and on the concept of a master. Therefore, we have moved the definitions of these concepts here, from where they used to be in Clause 9. These concepts also needed to be generalized somewhat. Task waiting is closely related to user-defined finalization; the rules here refer to the task-waiting rules of Clause 9.

Inconsistencies With Ada 95​

25.v.1/3
correction
Ada 2012 Changed the definition of the master of an anonymous object used to directly initialize an object, so it can be finalized immediately rather than having to hang around as long as the object. In this case, the Ada 2005 definition was inconsistent with Ada 95, and Ada 2012 changes it back. It is unlikely that many compilers implemented the rule as written in Amendment 1, so an inconsistency is unlikely to arise in practice.

Wording Changes from Ada 95​

25.w/2
note
{8652/0021} Corrigendum: Fixed the wording to say that anonymous objects aren't finalized until the object can't be used anymore.
25.x/2
note
{8652/0023} Corrigendum: Added wording to clarify what happens when Adjust or Finalize raises an exception; some cases had been omitted.
25.y/2
note
{8652/0024} Corrigendum: Stated that if Adjust raises an exception during initialization, nothing further is required. This is corrected in Ada 2005 to include all kinds of assignment other than assignment_statements.
25.z/2
note
Revised the definition of master to include expressions and statements, in order to cleanly define what happens for tasks and controlled objects created as part of a subprogram call. Having done that, all of the special wording to cover those cases is eliminated (at least until the Ada comments start rolling in).
25.aa/2
note
We define finalization of the collection here, so as to be able to conveniently refer to it in other rules (especially in 4.8, “Allocators”).
25.bb/2
note
Clarified that a coextension is finalized at the same time as the outer object. (This was intended for Ada 95, but since the concept did not have a name, it was overlooked.)

Inconsistencies With Ada 2005​

25.cc/3
correction
Better defined when objects allocated from anonymous access types are finalized. This could be inconsistent if objects are finalized in a different order than in an Ada 2005 implementation and that order caused different program behavior; however programs that depend on the order of finalization within a single master are already fragile and hopefully are rare.

Wording Changes from Ada 2005​

25.dd/3
correction
Removed a redundant rule, which is now covered by the additional places where masters are defined.
25.ee/4
correction
Clarified the finalization rules so that there is no doubt that privacy is ignored, and to ensure that objects of class-wide interface types are finalized based on their specific concrete type.
25.ff/3
correction
Allowed premature finalization of parts of failed allocators. This could be an inconsistency, but the previous behavior is still allowed and there is no requirement that implementations take advantage of the permission.
25.gg/3
note
Added a permission to finalize an object allocated from a subpool later than usual.
25.hh/3
note
Added text to specially define the master of anonymous objects which are passed as explicitly aliased parameters (see 6.1) of functions. The model for these parameters is explained in detail in 6.4.1.

Wording Changes from Ada 2012​

25.ii/5
correction
Defined the term “master construct”, so as to put static accessibility rules on a firmer basis, including ensuring that those rules apply inside of generic bodies.