10.2.1 Elaboration Control

The rules governing preelaboration are designed to allow it to be done largely by bulk initialization of statically allocated storage from information in a “load module” created by a linker. Some implementations may require run-time code to be executed in some cases, but we consider these cases rare enough that we need not further complicate the rules.

It is important that programs be able to declare data structures that are link-time initialized with aggregates, string_literals, and concatenations thereof. It is important to be able to write link-time evaluated expressions involving the First, Last, and Length attributes of such data structures (including variables), because they might be initialized with positional aggregates or string_literals, and we don't want the user to have to count the elements. There is no corresponding need for accessing discriminants, since they can be initialized with a static constant, and then the constant can be referred to elsewhere. It is important to allow link-time initialized data structures involving discriminant-dependent components. It is important to be able to write link-time evaluated expressions involving pointers (both access values and addresses) to the above-mentioned data structures.

The rules also ensure that no Elaboration_Check need be performed for calls on library-level subprograms declared within a preelaborated package. This is true also of the Elaboration_Check on task activation for library level task types declared in a preelaborated package. However, it is not true of the Elaboration_Check on instantiations.

A static expression should never prevent a library unit from being preelaborable.

Ramification: A preelaborable construct can be elaborated without using any information that is available only at run time. Note that we don't try to prevent exceptions in preelaborable constructs; if the implementation wishes to generate code to raise an exception, that's OK.

Because there is no flow of control and there are no calls (other than to predefined subprograms), these run-time properties can actually be detected at compile time. This is necessary in order to require compile-time enforcement of the rules. 

Ramification: A preelaborable construct can contain labels and null_statements.

Ramification: {AI12-0175-1} The parameters of any such function have to pass the preelaborability rules, so they typically have to be static expressions. The extra allowed functions are all forms of conversion that the compiler understands, so there should be little implementation burden. Note that such a call might raise an exception; preelaborable is not the same as elaborable with no code. 

Ramification: One can evaluate such a name, but not as a primary. For example, one can evaluate an attribute of the object. One can evaluate an attribute_reference, so long as it does not denote an object, and its prefix does not disobey any of these rules. For example, Obj'Access, Obj'Unchecked_Access, and Obj'Address are generally legal in preelaborated library units. 

Ramification: One can declare these kinds of types, but one cannot create objects of those types.

It is also nonpreelaborable to create an object if that will cause the evaluation of a default expression that will call a user-defined function. This follows from the rule above forbidding nonnull statements. 

This paragraph was deleted.{AI95-00161-01}

Ramification: {AI12-0232-1} {AI12-0417-1} A generic declaration is preelaborable unless there is no instance that could be declared preelaborated. For instance, a generic package declaration that directly contains a variable initialized by a non-static function that is not a formal function is not preelaborable (and thus would be illegal if the Preelaborate aspect were applied to it). 

Discussion: {AI95-00403-01} This is an “assume-the-worst” rule. The elaboration of a generic unit doesn't perform any of the actions listed above, because its sole effect is to establish that the generic can from now on be instantiated. So the elaboration of the generic itself is not the interesting part when it comes to preelaboration rules. The interesting part is what happens when you elaborate “any instantiation” of the generic. For instance, declaring an object of a limited formal private type might well start tasks, call functions, and do all sorts of nonpreelaborable things. We prevent these situations by assuming that the actual parameters are as badly behaved as possible. 

Reason: Without this rule about generics, we would have to forbid instantiations in preelaborated library units, which would significantly reduce their usefulness. 

Ramification: In a generic body, we assume the worst about formal private types and extensions.

{8652/0035} {AI95-00002-01} Subunits of a preelaborated subprogram unit do not need to be preelaborable. This is needed in order to be consistent with units nested in a subprogram body, which do not need to be preelaborable even if the subprogram is preelaborated. However, such subunits cannot depend semantically on nonpreelaborated units, which is also consistent with nested units.

{AI12-0417-1} If a unit is not preelaborated, the value of the Preelaborate aspect for that unit is False. 

Aspect Description for Preelaborate: Code execution during elaboration is avoided for a given package.

Discussion: {AI12-0417-1} Rules for specifying a library unit aspect (like Preelaborate) are found in 13.1.1.

Ramification: {AI12-0409-1} “Formal types visible at the point of the declaration” includes all visible formal types, including those that might have been declared in formal packages or in child packages.

Reason: {AI05-0028-1} {AI12-0409-1} The reason why we need to be allowed to specify the aspect the pragma for private types, private extensions, and protected types is fairly clear: the properties of the full view determine whether the type has preelaborable initialization or not; in order to preserve privacy we need a way to express on the partial view that the full view is well-behaved. The reason why we need to be allowed to specify the aspect the pragma for other composite types is more subtle: a nonnull override for Initialize might occur in the private part, even for a nonprivate type; in order to preserve privacy, we need a way to express on a type declared in a visible part that the private part does not contain any nasty override of Initialize. 

Ramification: {AI12-0409-1} Not only do protected types with entry_declarations and task types not have preelaborable initialization, but they cannot have pragma Preelaborable_Initialization aspect specified True for applied to them. 

Implementation Advice: A type declared in a preelaborated package should have the same representation in every elaboration of a given version of the package.

Reason: {AI05-0004-1} Such an allocator would provide a backdoor way to get a global variable into a pure unit, so it is prohibited. Most such allocators are illegal anyway, as their type is required to have Storage_Size = 0 (see the next two rules). But access parameters and access discriminants don't necessarily disallow allocators. However, a call is also illegal here (by the preelaboration rules), so access parameters cannot cause trouble. So this rule is really about prohibiting allocators in discriminant constraints:

{AI05-0004-1} {AI12-0417-1} The second half of the rule is needed because aggregates can specify the default initialization of a private type or extension using <> or the ancestor subtype of an extension aggregate. The subtype of a component could use an allocator to initialize an access discriminant; the type still could have the a pragma Preelaborable_Initialization aspect specified given. Ada 95 did not allow such private types to have preelaborable initialization, so such a default initialization could not have occurred. Thus this rule is not incompatible with Ada 95. 

Discussion: A remote access-to-class-wide type (see E.2.2) has its Storage_Size defined to be zero. 

Reason: {AI95-00366-01} We disallow most named access-to-object types because an allocator has a side effect; the pool constitutes variable data. We allow access-to-subprogram types because they don't have allocators. We even allow named access-to-object types if they have an empty predefined pool (they can't have a user-defined pool as System.Storage_Pools is not pure). In this case, most attempts to use an allocator are illegal, and any others (in a generic body) will raise Storage_Error.

Discussion: We allow access-to-constant types so long as there is no user-specified nonzero Storage_Size; if there were a user-specified nonzero Storage_Size restricting the size of the storage pool, allocators would be problematic since the package is supposedly ‘stateless’, and the allocated size count for the storage pool would represent state. 

Ramification: {AI12-0232-1} {AI12-0417-1} A generic declaration is pure unless there is no instance that could be declared pure. For instance, a generic package declaration that directly contains a variable declaration is not pure (and thus would be illegal if aspect Pure is specified for it).

Ramification: This makes allocators illegal for such types (see 4.8), making a storage pool unnecessary for these types. A storage pool would represent state.

Note that access discriminants and access parameters are never library-level, even when they are declared in a type or subprogram declared at library-level. That's because they have their own special accessibility rules (see 3.10.2). 

This paragraph was deleted.{AI05-0243-1}

Discussion: A declared-pure package is useful for defining types to be shared between partitions with no common address space. 

Reason: Note that generic packages are not mentioned in the list of things that can contain variable declarations. Note that the Ada 95 rules for deferred constants make them allowable in library units that are declared pure; that isn't true of Ada 83's deferred constants. 

Ramification: {AI95-00366-01} Anonymous access types are allowed.

{AI05-0243-1} A limited view is not a library unit, so any rule that starts “declared pure library unit” does not apply to a limited view. In particular, the 3rd and last sentences never apply to limited views. However, a limited view is a library_item, so rules that discuss “declared pure library_items” do include limited views.

{AI12-0417-1} If a unit is not declared pure, the value of the Pure aspect for that unit is False. 

Reason: {AI95-00366-01} Ada 95 didn't allow any access types as these (including access-to-subprogram types) cause trouble for Annex E, “Distributed Systems”, because such types allow access values in a shared passive partition to designate objects in an active partition, thus allowing inter-address space references. We decided to disallow such uses in the relatively rare cases where they cause problems, rather than making life harder for the majority of users. Types declared in a pure package can be used in remote operations only if they are externally streamable. That simply means that there is a means to transport values of the type; that's automatically true for nonlimited types that don't have an access part. The only tricky part about this is to avoid privacy leakage; that was handled by ensuring that any private types (and private extensions) declared in a pure package that have available stream attributes (which include all nonlimited types by definition) have to be externally streamable.

Aspect Description for Pure: Side effects are avoided in the subprograms of a given package.

Discussion: This could be accomplished via a self-referencing pointer or via squirrelling a writable pointer to a controlled object. 

Discussion: {AI95-00366-01} {AI05-0005-1} {AI05-0299-1} A declared-pure library_item has no variable state. Hence, a call on one of its (nonnested) subprograms cannot normally have side effects. Side effects are still possible via dispatching calls and via indirect calls through access-to-subprogram values. Other mechanisms that might be used to modify variable state include machine code insertions, imported subprograms, and unchecked conversion to an access type declared within the subprogram; this list is not exhaustive. Thus, the permissions described in this subclause may apply to a subprogram whose execution has side effects. The compiler may omit a call to such a subprogram even if side effects exist, so the writer of such a subprogram has to keep this in mind. 

Ramification: “Within a context_clause” allows it to be the last item in the context_clause. It can't be first, because the name has to denote something mentioned earlier. 

Discussion: Hence, a pragma Elaborate or Elaborate_All is not elaborated, not that it makes any practical difference.

Note that a pragma Elaborate or Elaborate_All is neither a program unit pragma, nor a library unit pragma.

Proof: {AI05-0229-1} {AI12-0417-1} Pragma Elaborate_Body sets the aspect (see below). 

Reason: These pragmas are intended to prevent elaboration check failures. But a limited view does not make anything visible that has an elaboration check, so the pragmas cannot do anything useful. Moreover, the pragmas would probably reintroduce the circularity that the limited_with_clause was intended to break. So we make such uses illegal. 

Proof: The official statement of the semantics of these pragmas is given in 10.2. 

Proof: The official statement of the semantics of this aspect is given in 10.2.

Implementation Note: {AI12-0417-1} The specification presence of the a pragma Elaborate_Body aspect simplifies the removal of unnecessary Elaboration_Checks. For a subprogram declared immediately within a library unit for to which the a pragma Elaborate_Body  aspect is specified as True applies, the only calls that can fail the Elaboration_Check are those that occur in the library unit itself, between the declaration and body of the called subprogram; if there are no such calls (which can easily be detected at compile time if there are no stubs), then no Elaboration_Checks are needed for that subprogram. The same is true for Elaboration_Checks on task activations and instantiations, and for library subprograms and generic units. 

Ramification: The fact that the unit of elaboration is the library_item means that if a subprogram_body is not a completion, it is impossible for any library_item to be elaborated between the declaration and the body of such a subprogram. Therefore, it is impossible for a call to such a subprogram to fail its Elaboration_Check. 

Discussion: The visibility rules imply that each library_unit_name of a pragma Elaborate or Elaborate_All has to denote a library unit mentioned by a previous with_clause of the same context_clause.

Aspect Description for Elaborate_Body: A given package will must have a body, and that body is elaborated immediately after the declaration.

Ramification: {8652/0035} {AI95-00002-01} But generally not nonpreelaborated subunits. (Nonpreelaborated subunits of subprograms are allowed as discussed above.) 

Ramification: {8652/0035} {AI95-00002-01} But generally not impure subunits. (Impure subunits of subprograms are allowed as discussed above.) 

Ramification: Pragma Elaborate is mainly for closely related library units, such as when two package bodies 'with' each other's declarations. In such cases, Elaborate_All sometimes won't work. 

The concepts of preelaborability and purity are new to Ada 95. The Elaborate_All, Elaborate_Body, Preelaborate, and Pure pragmas are new to Ada 95.

Pragmas Elaborate are allowed to be mixed in with the other things in the context_clause — in Ada 83, they were required to appear last. 

{AI95-00366-01} The requirement that a partial view with available stream attributes be externally streamable can cause an incompatibility in rare cases. If there is a limited tagged type declared in a pure package with available attributes, and that type is used to declare a private extension in another pure package, and the full type for the private extension has a component of an explicitly limited record type, a protected type, or a type with access discriminants, then the stream attributes will have to be user-specified in the visible part of the package. That is not a requirement for Ada 95, but this combination seems very unlikely in pure packages. Note that this cannot be an incompatibility for a nonlimited type, as all of the types that are allowed in Ada 95 that would require explicitly defined stream attributes are limited (and thus cannot be used as components in a nonlimited type).

{AI95-00403-01} Amendment Correction: Added wording to cover missing cases for preelaborated generic units. This is incompatible as a preelaborated unit could have used a formal object to initialize a library-level object; that isn't allowed in Ada 2005. But such a unit wouldn't really be preelaborable, and Ada 95 compilers can reject such units (as this is a Binding Interpretation), so such units should be very rare. 

{AI95-00161-01} Amendment Correction: The concept of preelaborable initialization and pragma Preelaborable_Initialization are new. These allow more types of objects to be created in preelaborable units, and fix holes in the old rules.

{AI95-00366-01} Access-to-subprogram types and access-to-object types with a Storage_Size of 0 are allowed in pure units. The permission to omit calls was adjusted accordingly (which also fixes a hole in Ada 95, as access parameters are allowed, and changes in the values accessed by them must be taken into account). 

{AI95-00002-01} Corrigendum: The wording was changed so that subunits of a preelaborated subprogram are also preelaborated.

{AI95-00217-06} Disallowed pragma Elaborate and Elaborate_All for packages that are mentioned in a limited_with_clause.

{AI05-0028-1} Correction: Corrected a serious unintended incompatibility with Ada 95 in the new preelaboration wording — explicit initialization of objects of types that don't have preelaborable initialization was not allowed. Ada 2012 switches back to the Ada 95 rule in these cases. This is unlikely to occur in practice, as it is unlikely that a compiler would have implemented the more restrictive rule (it would fail many ACATS tests if it did).

{AI05-0035-1} Correction: Added an assume-the-worst rule for generic bodies (else they would never be checked for purity) and added the boilerplate so that the entire generic specification is rechecked. Also fixed wording to have consistent handling for subunits for Pure and Preelaborate. An Ada 95 program could have depended on marking a generic pure that was not really pure, although this would defeat the purpose of the categorization and likely cause problems with distributed programs. 

{AI05-0035-1} Correction: Adjusted wording so that a subunit can be pure (it is not a library_item, but it is a compilation unit).

{AI05-0035-1} Correction: Adjusted wording so that the rules for access types only apply to nonderived types (derived types share their storage pool with their parent, so if the parent access type is legal, so is any derived type.)

{AI05-0229-1} {AI12-0417-1} Elaborate_Body is now an aspect, so it can be specified by an aspect_specification — although the pragma is still preferred by the Reference Manual.

{AI05-0243-1} {AI12-0417-1} Pure and Preelaborate are now aspects, so they can be specified by an aspect_specification — although the pragma is still preferred by the Reference Manual.

{AI05-0034-1} Correction: Added wording so that a limited view is always treated as pure, no matter what categorization is used for the originating unit. This was undefined in Ada 2005.

{AI05-0028-1} {AI05-0221-1} Correction: Fixed minor issues with preelaborable initialization (PI): null Initialize procedures do not make a type non-PI; formal types with pragma PI can be assumed to have PI; formal extensions are assumed to not have PI; all composite types can have pragma PI (so that the possibility of hidden Initialize routines can be handled); added discriminants of a derived type are not considered in calculating PI.

{AI05-0219-1} Correction: Clarified that the implementation permission to omit pure subprogram calls does not apply if any part of the parameters or any designated object has a part that is immutably limited. The old wording just said "limited type", which can change via visibility and thus isn't appropriate for dynamic semantics permissions. 

{AI12-0232-1} Correction: Added a rule that a generic declaration is not pure if no instance could be pure (for instance, because the generic declaration would elaborates a variable.) This was legal in Ada 2012, but of course no instance could have been declared pure. A similar rule (with a similar effect) was added for preelaborable generic declarations. 

{AI12-0175-1} Added some intrinsic conversion functions to those allowed to be called during the elaboration of a preelaborated unit. This is necessary to allow a portable Address aspect in a preelaborated unit, important on small embedded systems.

{AI12-0409-1} Aspect Preelaborable_Initialization is new; pragma Preelaborable_Initialization is now obsolescent. 

{AI12-0076-1} Corrigendum: Explicitly stated that modifying a library-level constant in a pure package is erroneous. We don't document this as inconsistent as implementations certainly can still do whatever they were previously doing (no change is required); moreover, this case (and many more) were erroneous in Ada 2005 and before, so we're just restoring the previous semantics.

{AI12-0232-1} Correction: Explicitly stated that the pure and preelaborate rules are recursive; that is, they apply to the contents of nested packages and generic packages.

{AI12-0417-1} The pragmas that set aspects (Pure, Preelaborate, Elaborate_Body) are now obsolescent.