Skip to main content

12.6 Formal Subprograms

danger

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

1

[ Formal subprograms can be used to pass callable entities to a generic unit.]

Language Design Principles​

1.a
note
Generic formal subprograms are like renames of the explicit_generic_actual_parameter.

Syntax​

2/2
formal_subprogram_declaration ::= formal_concrete_subprogram_declaration
    | formal_abstract_subprogram_declaration
2.1/3
formal_concrete_subprogram_declaration ::= 
     with subprogram_specification [is subprogram_default]
        [aspect_specification];
2.2/3
formal_abstract_subprogram_declaration ::= 
     with subprogram_specification is abstract [subprogram_default]
        [aspect_specification];
3/2
subprogram_default ::= default_name | <> | null
4
default_name ::= name
4.1/2

A subprogram_default of null shall not be specified for a formal function or for a formal_abstract_subprogram_declaration.

4.a/2
reason
There are no null functions because the return value has to be constructed somehow. We don't allow null for abstract formal procedures, as the operation is dispatching. It doesn't seem appropriate (or useful) to say that the implementation of something is null in the formal type and all possible descendants of that type. This also would define a dispatching operation that doesn't correspond to a slot in the tag of the controlling type, which would be a new concept. Finally, additional rules would be needed to define the meaning of a dispatching null procedure (for instance, the convention of such a subprogram should be intrinsic, but that's not what the language says). It doesn't seem worth the effort.

Name Resolution Rules​

5

The expected profile for the default_name, if any, is that of the formal subprogram.

5.a/3
ramification
This rule, unlike others in this subclause, is observed at compile time of the generic_declaration.
5.b
note
The evaluation of the default_name takes place during the elaboration of each instantiation that uses the default, as defined in 12.3, “Generic Instantiation”.
6

For a generic formal subprogram, the expected profile for the actual is that of the formal subprogram.

Legality Rules​

7/3

The profiles of the formal and any named default shall be mode conformant.

7.a/3
ramification
This rule, unlike others in this subclause, is checked at compile time of the generic_declaration.
8/3

The profiles of the formal and actual shall be mode conformant.

8.1/2

For a parameter or result subtype of a formal_subprogram_declaration that has an explicit null_exclusion:

8.2/5
  • if the actual matching the formal_subprogram_declaration statically denotes a generic formal subprogram of another generic unit G, and the instantiation containing the actual occurs within the body of a generic unit G or within the body of a generic unit declared within the declarative region of the generic unit G, then the corresponding parameter or result type of the formal subprogram of G shall have a null_exclusion;
    • 8.3/2
  • otherwise, the subtype of the corresponding parameter or result type of the actual matching the formal_subprogram_declaration shall exclude null. In addition to the places where Legality Rules normally apply (see 12.3), this rule applies also in the private part of an instance of a generic unit.
8.a/2
reason
This rule prevents “lying”. Null must never be the value of a parameter or result with an explicit null_exclusion. The first bullet is an assume-the-worst rule which prevents trouble in generic bodies (including bodies of child generics) when the formal subtype excludes null implicitly.
8.4/5

If the named default, if any, is a prefixed view, the prefix of that view shall denote an object for which renaming is allowed (see 8.5.1). Similarly, if the actual subprogram in an instantiation is a prefixed view, the prefix of that view shall denote an object for which renaming is allowed.

8.b/5
reason
The prefix in such a case is essentially renamed at the point of the instantiation and passed to any calls of the formal subprogram in the generic. If the prefix isn't legal to rename, that doesn't make sense (and allowing it might end up passing a nonexistent object to some calls).
8.5/5

If a formal parameter of a formal_abstract_subprogram_declaration is of a specific tagged type T or of an anonymous access type designating a specific tagged type T, T is called a controlling type of the formal_abstract_subprogram_declaration. Similarly, if the result of a formal_abstract_subprogram_declaration for a function is of a specific tagged type T or of an anonymous access type designating a specific tagged type T, T is called a controlling type of the formal_abstract_subprogram_declaration. A formal_abstract_subprogram_declaration shall have exactly one controlling type, and that type shall not be incomplete.

8.c/2
ramification
The specific tagged type could be any of a formal tagged private type, a formal derived type, a formal interface type, or a normal tagged type. While the last case doesn't seem to be very useful, there isn't any good reason for disallowing it. This rule ensures that the operation is a dispatching operation of some type, and that we unambiguously know what that type is.
8.d/2
note
We informally call a subprogram declared by a formal_abstract_subprogram_declaration an abstract formal subprogram, but we do not use this term in normative wording. (We do use it often in these notes.)
8.6/5

The actual subprogram for a formal_abstract_subprogram_declaration shall be:

8.7/5
  • a dispatching operation of the controlling type; or
    • 8.8/5
  • if the controlling type is a formal type, and the actual type corresponding to that formal type is a specific type T, a dispatching operation of type T; or
    • 8.9/5
  • if the controlling type is a formal type, and the actual type is a class-wide type T'Class, an implicitly declared subprogram corresponding to a primitive operation of type T (see Static Semantics below).
8.e/2
note
To be honest: We mean the controlling type of the formal_abstract_subprogram_declaration, of course. Saying that gets unwieldy and redundant (so says at least one reviewer, anyway).
8.e.1/5
ramification
This means that the actual is a primitive operation of the controlling type, an abstract formal subprogram, or the implicitly available primitive operation for a class-wide type.
8.e.2/5
note
An explicit class-wide operation cannot be used for the actual of a formal abstract subprogram. Such an operation is never primitive (only specific types have primitive subprograms).
8.f/5
note
This could happen in a case like:
8.g/2
generic
   type T(<>) is tagged private;
   with procedure Foo (Obj : in T) is abstract;
package P ...
8.h/2package New_P is new P (Something'Class, Some_Proc);
8.i/5
note
If Some_Proc is an explicit class-wide operation, the instantiation here is illegal, because Some_Proc is not a primitive operation of Something'Class (there are no such operations).
8.i.1/5
note
However, if Some_Proc is a primitive operation of type Something, then the instantiation is legal; the actual is the implicitly generated subprogram described in Static Semantics below. This is not a problem, since the rules given in 12.5.1 explain how this routine dispatches even though its parameter is class-wide.
8.i.2/5
note
We allow this special case because it is possible for a class-wide operation to be primitive inside of an instance, and the contract model does not allow us to make such cases illegal. As such, it seems inconsistent to not allow the same in explicit instantiations.
8.j/5
note
Specifically, since it is possible for a formal tagged type to be instantiated with a class-wide type, it is possible for the (real) controlling type to be class-wide as in the following unusual case:
8.k/5
generic
   type NT(<>) is new T with private;
   -- Presume that T has the following primitive operation:
   --  procedure Bar (Obj : in T);
package Gr ...
8.l/2package body Gr is
   package New_P2 is new P (NT, Foo => Bar);
end Gr;
8.m/2package New_Gr is new Gr (Something'Class);
8.n/5
note
The instantiation of New_P2 is legal, since Bar is a dispatching operation of the actual type of the controlling type of the abstract formal subprogram Foo. Again, the rules given in 12.5.1 explain how this routine dispatches .
8.o/2
note
Note that this legality rule never needs to be rechecked in an instance (that contains a nested instantiation). The rule only talks about the actual type of the instantiation; it does not require looking further; if the actual type is in fact a formal type, we do not intend looking at the actual for that formal.

Static Semantics​

9

A formal_subprogram_declaration declares a generic formal subprogram. The types of the formal parameters and result, if any, of the formal subprogram are those determined by the subtype_marks given in the formal_subprogram_declaration; however, independent of the particular subtypes that are denoted by the subtype_marks, the nominal subtypes of the formal parameters and result, if any, are defined to be nonstatic, and unconstrained if of an array type [(no applicable index constraint is provided in a call on a formal subprogram)]. In an instance, a formal_subprogram_declaration declares a view of the actual. The profile of this view takes its subtypes and calling convention from the original profile of the actual entity, while taking the formal parameter names and default_expressions from the profile given in the formal_subprogram_declaration. The view is a function or procedure, never an entry.

9.a
discussion
This rule is intended to be the same as the one for renamings-as-declarations, where the formal_subprogram_declaration is analogous to a renaming-as-declaration, and the actual is analogous to the renamed view.
9.1/3

If a subtype_mark in the profile of the formal_subprogram_declaration denotes a formal private or formal derived type and the actual type for this formal type is a class-wide type T'Class, then for the purposes of resolving the corresponding actual subprogram at the point of the instantiation, certain implicit declarations may be available as possible resolutions as follows:

9.2/3

For each primitive subprogram of T that is directly visible at the point of the instantiation, and that has at least one controlling formal parameter, a corresponding implicitly declared subprogram with the same defining name, and having the same profile as the primitive subprogram except that T is systematically replaced by T'Class in the types of its profile, is potentially use-visible. The body of such a subprogram is as defined in 12.5.1 for primitive subprograms of a formal type when the actual type is class-wide.

9.b/3
reason
This gives the same capabilities to formal subprograms as those that primitive operations of the formal type have when the actual type is class-wide. We do not want to discourage the use of explicit declarations for (formal) subprograms!
9.c/3
implementation note
Although the above wording seems to require constructing implicit versions of all of the primitive subprograms of type T, it should be clear that a compiler only needs to consider those that could possibly resolve to the corresponding actual subprogram. For instance, if the formal subprogram is a procedure with two parameters, and the actual subprogram name is Bar (either given explicitly or by default), the compiler need not consider primitives that are functions, that have the wrong number of parameters, that have defining names other than Bar, and so on; thus it does not need to construct implicit declarations for those primitives.
9.d/3
ramification
Functions that only have a controlling result and do not have a controlling parameter of T are not covered by this rule, as any call would be required to raise Program_Error by 12.5.1. It is better to detect the error earlier than at run time.
10

If a generic unit has a subprogram_default specified by a box, and the corresponding actual parameter is omitted, then it is equivalent to an explicit actual parameter that is a usage name identical to the defining name of the formal.

10.1/2

If a generic unit has a subprogram_default specified by the reserved word null, and the corresponding actual parameter is omitted, then it is equivalent to an explicit actual parameter that is a null procedure having the profile given in the formal_subprogram_declaration.

10.2/2

The subprogram declared by a formal_abstract_subprogram_declaration with a controlling type T is a dispatching operation of type T.

10.a/2
reason
This is necessary to trigger all of the dispatching operation rules. It otherwise would not be considered a dispatching operation, as formal subprograms are never primitive operations.
11/5
note
NOTE 1 The matching rules for formal subprograms state requirements that are similar to those applying to subprogram_renaming_declarations (see 8.5.4). In particular, the name of a parameter of the formal subprogram can be different from that of the corresponding parameter of the actual subprogram; similarly, for these parameters, default_expressions can be different .
12
note
NOTE 2 The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding subtype_mark in the _specification of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.
13
note
NOTE 3 The subtype specified for a formal parameter of a generic formal subprogram can be any visible subtype, including a generic formal subtype of the same generic_formal_part.
14
note
NOTE 4 A formal subprogram is matched by an attribute of a type if the attribute is a function with a matching specification. An enumeration literal of a given type matches a parameterless formal function whose result type is the given type.
15/5
note
NOTE 5 A default_name denotes an entity that is visible or directly visible at the place of the generic_declaration; a box used as a default is equivalent to a name that denotes an entity that is directly visible at the place of the generic_instantiation .
15.a
proof
Visibility and name resolution are applied to the equivalent explicit actual parameter.
16/2
note
NOTE 6 The actual subprogram cannot be abstract unless the formal subprogram is a formal_abstract_subprogram_declaration (see 3.9.3).
16.1/5
note
NOTE 7 The subprogram declared by a formal_abstract_subprogram_declaration is an abstract subprogram. All calls on a subprogram declared by a formal_abstract_subprogram_declaration are limited to dispatching calls. See 3.9.3.
16.2/2
note
NOTE 8 A null procedure as a subprogram default has convention Intrinsic (see 6.3.1).
16.a.1/2
proof
This is an implicitly declared subprogram, so it has convention Intrinsic as defined in 6.3.1.

Examples​

17

Examples of generic formal subprograms:

18/2
with function "+"(X, Y : Item) return Item is <>;
with function Image(X : Enum) return String is Enum'Image;
with procedure Update is Default_Update;
with procedure Pre_Action(X : in Item) is null;  -- defaults to no action
with procedure Write(S    : not null access Root_Stream_Type'Class;
                     Desc : Descriptor)
                     is abstract Descriptor'Write;  -- see 13.13.2
-- Dispatching operation on Descriptor with default
19--  given the generic procedure declaration 
20generic
   with procedure Action (X : in Item);
procedure Iterate(Seq : in Item_Sequence);
21--  and the procedure 
22procedure Put_Item(X : in Item);
23--  the following instantiation is possible 
24procedure Put_List is new Iterate(Action => Put_Item);

Extensions to Ada 95​

24.a/2
note
The formal_abstract_subprogram_declaration is new. It allows the passing of dispatching operations to generic units.
24.b/2
note
The formal subprogram default of null is new. It allows the default of a generic procedure to do nothing, such as for passing a debugging routine.

Wording Changes from Ada 95​

24.c/2
note
Added matching rules for null_exclusions.

Incompatibilities With Ada 2005​

24.d/3
note
It is now illegal to declare a formal abstract subprogram whose controlling type is incomplete. It was never intended to allow that, and such a type would have to come from outside of the generic unit in Ada 2005, so it is unlikely to be useful. Moreover, a dispatching call on the subprogram is likely to fail in many implementations. So it is very unlikely that any code will need to be changed because of this new rule.

Extensions to Ada 2005​

24.e/3
correction
Added construction of implicit subprograms for primitives of class-wide actual types, to make it possible to import subprograms via formal subprograms as well as by implicit primitive operations of a formal type. (This is a Correction as it is very important for the usability of indefinite containers when instantiated with class-wide types; thus we want Ada 2005 implementations to support it.)
24.f/3
note
An optional aspect_specification can be used in a formal_concrete_subprogram_declaration and a formal_abstract_subprogram_declaration. This is described in 13.1.1.

Incompatibilities With Ada 2012​

24.g/5
correction
Added a rule to ensure that for an actual subprogram that is a prefixed view, the prefix continues to exist during the life of the instantiation. If the prefix is a subcomponent that depends on discriminants, Ada 2005 and 2012 would have allowed the prefix while Ada 2022 would not. Without this change, explicit forms (renaming the object and then using that in instantiations) would be safer than directly using the prefixed view; that's inconsistent with other kinds of actual subprograms.

Extensions to Ada 2012​

24.h/5
correction
We now allow the actual for a formal_abstract_subprogram_declaration to be an implicitly declared subprogram for a class-wide type. The rules already required a compiler to be able to construct this subprogram for use in an instantiation that occurs inside of a generic unit, so it made no sense to prevent it from being used explicitly as well (in the same way that the previous extension allows them to be used for other kinds of formal subprograms).

Wording Changes from Ada 2012​

24.i/5
correction
Added wording to ensure that the object subject to a Legality Rule can be determined at compile-time. The alternative being nonsense, we treat this as a wording change.