Basic aspects

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>. The compiler can create instantiations of the template for each of the types required from a single source description of the template for a stack.

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 mainly 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++ language allows one to write a specialization for a template entity, which means that the user can supply a specific version to be used instead of the instantiation generated from the template for a specific data type. In the language mode C++V3 such a specialization need not be declared when it is used. Since the compiler cannot know, when compiling a reference to a template entity, 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 (“automatic” instantiation), 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”). Refer to section “Automatic instantiation” for further details.

Explicit control over the instantiation process is available to the programmer via selectable instantiation modes and #pragma directives:

• The instantiation mode selection options are -T auto, -T none, -T local and -T all.They are described in detail in section “"Template options".

• The following #pragma directives can be used to control instantiation of single templates or a group of templates:

  • The instantiate pragma creates the template instance specified as the argument. This pragma can be used in place of the C++ language feature template declaration for explicit instantiation requests. See also the example on "Libraries and templates".

  • The do_not_instantiate pragma suppresses instantiation of the template instance specified as the argument. Typical candidates for this pragma are template entities for which specific definitions have been provided (specializations).

  • The can_instantiate pragma informs the compiler that the template instance specified as the argument can be, but does not have to be created in the compilation unit. This pragma is required in conjunction with libraries and is only evaluated in automatic instantiation mode. See also the example on "Libraries and templates".

  The exact syntax and general rules regarding these pragmas can be found in theC/C++ User Guide [4], in the section “Pragmas for controlling template Instantiation”.

• It is possible to implement explicit control using the “explicit instantiation statements” specified (in the source). These “explicit instantiation statements” can be generated using -T etr_file_all or -T etr_file_assigned (see section “Generatingexplicit template instantiation statements (ETR files)”) and can then be incorporated into the sources by the user.

Important information

The method of template instantiation preset for this compiler (automatic instantiation by the prelinker and implicit inclusion) is also the method we recommend. There are options allowing you to change the settings for this method, but you should do this only in exceptional cases and only when you are very familiar with the entire application, including all the templates which are defined and used.

Implicit inclusion: implicit inclusion must not be disabled (with -K no_implicit_include) when templates from the C++ V3 library (SYSLNK.CRTE.STDCPP) are used, since otherwise no definitions are found.

Instantiation modes other than -T auto : there is a danger here that unsatisfied external references (-T none), duplicates (-T all) or runtime errors (-T local) may occur.