Automatic instantiation

Automatic instantiation (-T auto option) is supported by the compiler by default in the language modes C++ V3, C++ 2017 and C++ 2020. This allows you to compile your source code and link the generated objects without having to worry about how the necessary instantiations are done.

Note that the discussion which follows refers to the automatic instantiation of template entities for which there is no explicit instantiation request (template declaration) and no instantiate pragma.

Requirements

For each instantiation, the compiler expects a source file that contains both a reference to the required instantiation and the definition of the template entity as well as all types required for the instantiation of that template entity. The last two requirements can be satisfied by the following methods:

• Each .h file that declares a template entity also contains either the definition of the entity or includes another file containing the definition.

• Implicit inclusion
  When the compiler sees a template declaration in a .h file and discovers a need to instantiate that entity, it looks for a source file with the same base name as the .h file and a suffix that satisfies the conventions for C++ source file names (see the rules for input file names on "Calling syntax and general rules"). This file is then implicitly included by the compiler on instantiation at the end of each compilation unit without a message being issued. See also section “Implicit inclusion” for details.

• The programmer makes sure that the files that define template entities also contain the definitions of all required types and adds C++ code or instantiation pragmas in those files to request the instantiation of the template entities therein.

First instantiation without a definition list

The definition list method can also be used as an alternative to the following procedure (see First instantiation using the definition list (temporary repository)).

The following steps are performed internally during automatic instantiation:

1. Create instantiation information files
   No template entities are instantiated the first time that one or more source files are compiled. For each source file that makes use of a template, an associated instantiation information file is created if no such file already exists. An instantiation information file has the suffix .o.ii. For example, the compilation of abc.C would result in the creation of the file abc.o.ii. The instantiation information file must not be modified by the user.

2. Create object files
   The created objects contain information on which instantiations could have been and were created when compiling a source file.

3. Assign template instantiations
   When the object files are linked, the prelinker is called before the actual linking takes place. The prelinker examines the object files, looking for references and definitions of template entities and for added information about entities that could be instantiated. If it does not find a definition for a required template entity, it searches for an object file which can instantiate the template entity.When it finds such a file, it assigns the instantiation to it.

4. Update the instantiation information file
   All instantiations that were assigned to a given file are recorded by name in the associated instantiation information file.

5. Recompile
   The compiler is internally called again to recompile each file for which the instantiation information file was changed.

6. Create new object file
   When the compiler compiles a file, it reads the instantiation information file for that compilation unit and creates a new object file with the required instantiations.

7. Repetition
   Steps 3 to 6 are repeated until all instantiations that are required and can be generated have been created.

8. Linkage
   The object files are linked together.

First instantiation using the definition list (temporary repository)

Since the procedure above (see "First instantiation without a definition list") recompiles some files more than once, an option was added that is intended to accelerate the overall process.

Generally the files are only recompiled once. The majority of instantiations are associated with the first files to be recompiled in the method. This has disadvantages in some cases since their object sizes increase due to this (although the sizes of other objects decrease to compensate for this).

Increasing the size of individual modules can be a disadvantage in user applications when, for example, precisely this module needs to be loaded often. The user must therefore decide if the method that more evenly distributes the instances (default) is desired or if this method is desired (due to improved response during prelinking).

This schema can be enabled by specifying the -T definition_list option.

Steps 3-5 above are modified. The resulting algorithm appears as follows then:

1. Create instantiation information files
   When one or more source files are compiled for the first time, no template entities are instantiated. One instantiation information file is created (if not already present) for every source file that uses a template. An instantiation information file has the file suffix .o.ii . When compiling abc.C, for example, the file abc.o.ii would be created. The instantiation information file may not be modified by the user.

2. Create object files
   The objects created contain information on which instances could be created and may be needed when compiling a source file.

3. Assign template instances to a source file
   If there are references for template entities for which there are no definitions in the set of object files, then a file is selected that could instantiate one of the template entities. All template entities that can be instantiated in this file are assigned to it.

4. Update instantiation information
   The set of instances that this file is assigned to is recorded in the associated instantiation file.

5. Save the definition list
   A definition list is maintained internally in memory. It contains a list of all definitions relating to templates that were found in all object files. This list can be read in and changed during recompilation.

   Note

   This list is not stored in a file.

6. Recompilation
   The compiler is called again internally to recompile the corresponding source file.

7. Create new object file
   When the compiler recompiles a file, it reads the instantiation information file for this compilation unit and creates a new object file with the required instances.If the compiler gets the chance during compilation to instantiate additional referenced template entities that are not mentioned in the definition list or were not found in the libraries resolved, then it also instantiates these template entities (e.g. for templates that are contained in templates). It passes a list of instantiations received to the prelinker so that the prelinker can assign them to the file.

   This process permits faster instantiation. It also reduces the necessity of recompiling and existing file more than once during the prelink process.

8. Repeat
   Steps 3 - 7 are repeated until all necessary and generatable instances have been created.

9. Link
   The object files are linked.

Further development

Once a program has been linked correctly, the associated instantiation information files contain all the names of the required instantiations. From then on, whenever source files are compiled, the compiler will consult the instantiation information file and do the instantiations therein as in a normal compilation run. In other words, except in cases where the set of required instantiations changes, the prelinker will find all required instantiations stored in the object files, so no further instantiation adjustments are needed. This applies even if the entire program is recompiled.

If a specialization of a template entity has been provided somewhere in the program, the prelinker will treat it as a definition. Since this definition will satisfy any references to the template entity, the prelinker will see no need to request an instantiation for that template entity. If a specialization is added to a program that has already been compiled, the prelinker will remove the assignment of the instantiation from the corresponding instantiation information file.

The instantiation information file must not be modified (e.g. renamed or deleted) by the user, except in the following case: if a source file in which a definition was changed and another source file in which a specialization was added are being compiled in sequence in the same compiler run, and the compilation of the first file (with the changed definition) has aborted with an error, the associated instantiation information file must be deleted manually to allow the prelinker to regenerate it.

Automatic instantiation, libraries and prelinked object files

When an executable file is generated with the CC command in automatic instantiation mode, the prelinker will do the automatic instantiation only in individual object files (.o files), but not in objects that are part of a library (.a library) or an object file that was prelinked with the -r option.

When generating the executable file, libraries or prelinked object files that require instances of template entities must either

• already contain these instances (which may be achieved by explicit instantiation and/or the preinstantiation of objects using the -y option; see "Options for selecting compilation phases")

• or provide appropriate header files with can_instantiate pragmas.

More details can be found in section “Libraries and templates”.

The option -T add_prelink_files provides a further method of controlling automatic instantiation in connection with libraries (see "Template options").

Controlling instantiation assignments

The assignment of instantiations to local object files can be enabled and disabled with the -K assign_local_only and -K no_assign_local_only options (see "Template options").