Automatic instantiation

Automatic instantiation is enabled via the -Tauto option to CC, which is on by default. (It is turned off by the -Tno_auto option.) As stated above, the goal of this approach is to provide painless, transparent instantiaion. For the most part, it is not necessary to know how automatic instantiation works in order to use it.

If you have an application that uses templates, one way of taking care of instantiation is via the manual approaches described above. These work fine but can be tedious to manage. However, automatic instantiation can be tricky, because it's not clear just when instantiation should be done. If it's done for each compilation unit, then there will be duplication, resulting in link errors about multiply-defined symbols, or at the least much duplication of effort and bigger disk size for object files. Also, it's not always possible to know at the time a given compilation unit is encountered which members of a template will be used. It's desirable to instantiate only those members actually used, to keep the object file small.

Instead of instantiating at compile time, link-directed instantiation is used. The automatic instantiation method works as follows.

1. The first time the source files of a program are compiled, no template entities are instantiated. However, an associated generated file with the suffix abc.ti (if the source file is abc.C) contains information about things that could have been instantiated in each compilation.

2. When the object files are linked together, a program called the prelinker is run. It examines the object files, looking for references and definitions of template entities, and for the added information about entities that could be instantiated.

3. If the prelinker finds a reference to a template entity for which there is no definition anywhere in the set of object files, it looks for a file that indicates that it could instantiate that template entity. When it finds such a file, it assigns the instantiation to it. The set of instantiations assigned to a given file, say abc.C, is recorded in an associated .ii file, for example abc.ii.
   

4. The prelinker then executes the compiler again to recompile each file for which the .ii file was changed. The original compilation command-line options (saved in the abc.ti file) are used for the recompilation.

5. When the compiler compiles a file, it reads the .ii file for that file and obeys the instantiation requests therein. It produces a new object file containing the requested template entities (and all the other things that were already in the object file).
   

6. The prelinker repeats steps 3-5 until there are no more instantiations to be adjusted.

7. The object files are linked together.

Once the program has been linked correctly, the .ii files contain a complete set of instantiation assignments. >From then on, whenever source files are recompiled, the compiler will consult the .ii files and do the indicated instantiations as it does the normal compilations. That means that, except in cases where the set of required instantiations changes, the prelink step from then on will find that all the necessary instantiations are present in the object files and no instantiation assignment adjustments need be done. That's true even if the entire program is recompiled.

If the programmer provides a specialization of a template entity somewhere in the program, the specialization will be seen as a definition by the prelinker. Since that definition satisfies whatever references there might be to that entity, the prelinker will see no need to request an instantiation of the entity. If the programmer adds a specialization to a program that has previously been compiled, the prelinker will notice that too and remove the assignment of the instantiation from the proper .ii file.

The .ii files should not, in general, require any manual intervention. One exception: if a definition is changed in such a way that some instantiation no longer compiles (it gets errors), and at the same time a specialization is added in another file, and the first file is being recompiled before the specialization file and is getting errors, the .ii file for the file getting the errors must be deleted manually to allow the prelinker to regenerate it.

Using the -v option to CC will let you see what the prelinker is doing. For example, if the prelinker changes an instantiation assignment, it will issue a message like:

   C++ prelinker: A<:int>::f(void) assigned to file test.o
   C++ prelinker: executing: CC -c test.c

The automatic instantiation scheme can coexist with partial explicit control of instantiation by the programmer through the use of pragmas or command-line specification of the instantiation mode.