Fundamentals

The C++ language includes the concept of templates. A template is a description of a class or function that serves as a model for a family of derived classes or functions. For example, one can write a template for a Stack class, and then use a stack of integers, a stack of floats, or a stack of any user-defined type. These stacks could then be typically written in the source as Stack<int>, Stack<float> and Stack<X>. From a single source description of the template for a stack, the compiler can create instantiations of the template for each of the types required.

The instantiation of a class template is always created as soon as it is required during compilation. The instantiations of template functions and member functions or static data members of a class template (referred to as template entities below), by contrast, need not be created immediately. This is due to the following reasons:

• In the case of template entities with external linkage (functions and static data members), it is important to have only one copy of the instantiated template entity throughout the program.

• The C++ standard allows to write a specialization for a template entity, which means that the programmer can supply a specific version to be used instead of the instantiation generated from the template for a specific data type.
  Since the compiler cannot know, when compiling a reference to a template entity in mode C++ V3, if a specialization for that entity is available in another compilation unit, it cannot create the instantiation immediately.

• The C++ standard dictates that template functions which are not referenced should not be compiled and should be checked for errors. Consequently, a reference to a template class should not automatically instantiate all the member functions of that class.

Note that some template entities such as inline functions are always instantiated when used.

From the requirements listed above, it is evident that if the compiler is responsible for the entire instantiation (i.e. if the instantiation is done “automatically”), these instantiations can only be performed meaningfully on a program-wide basis. In other words, the compiler cannot make decisions about the instantiation of template entities until it has seen the source code of all compilation units in the program.

The C/C++ compiler provides an instantiation mechanism by which automatic instantiation is carried out at link time (with the aid of a “prelinker”). This mechanism is discussed in detail in section “Automatic instantiation”.

More explicit control over the instantiation process is available to the programmer via different instantiation modes that can be selected using options and by means of #pragma directives.

• The options to select instantiation modes are:
  MODIFY-SOURCE-PROP INSTANTIATION=*NONE / *AUTO / *LOCAL / *ALL(see "MODIFY-SOURCE-PROPERTIES").

• The instantiation of individual templates or even a template group can be controlled with the pragmas:
  instantiate, do_not_instantiate and can_instantiate (see "Pragmas to control template instantiation").

Important notes
The default template instantiation method of this compiler (i.e. automatic instantiation by the prelinker and implicit inclusion) is also the recommended method and should generally be used. Deviations from this default method via control options should be restricted to exceptional cases and should only be attempted if the entire application is known in detail, including every template that is defined and used.

Implicit inclusion must not be disabled (with IMPLICIT-INCLUDE=*NO) when using templates from the C++ V3 library (SYSLNK.CRTE.STDCPP). Otherwise, the required definitions will not be found.

Instantiation modes != INSTANTIATION=*AUTO: In this case, there is a high risk that unresolved external references (*NONE), duplicates (*ALL) or runtime errors (*LOCAL) may occur.