7.2 Repository Administration

The CCadmin(1) command administers the template repository (used only with the option -instances=extern). For example, changes in your program can render some instantiations superfluous, thus wasting storage space. The CCadmin– clean command (formerly ptclean) clears out all instantiations and associated data. Instantiations are recreated only when needed.

7.2.1 Generated Instances

The compiler treats inline template functions as inline functions for the purposes of template instance generation. The compiler manages them as it does other inline functions, and the descriptions in this chapter do not apply to template inline functions.

7.2.2 Whole-Class Instantiation

The compiler usually instantiates members of template classes independently of other members, so that the compiler instantiates only members that are used within the program. Methods written solely for use through a debugger will therefore not normally be instantiated.

There are two means to ensure that debugging members are available to the debugger.

• First, write a non-template function that uses the template class instance members that are otherwise unused. This function need not be called.

• Second, use the -template=wholeclass compiler option, which instructs the compiler to instantiate all non-template non-inline members of a template class if any of those same members are instantiated.

The ISO C++ Standard permits developers to write template classes for which all members may not be legal with a given template argument. As long as the illegal members are not instantiated, the program is still well formed. The ISO C++ Standard Library uses this technique. However, the -template=wholeclass option instantiates all members, and hence cannot be used with such template classes when instantiated with the problematic template arguments.

7.2.3 Compile-Time Instantiation

Instantiation is the process by which a C++ compiler creates a usable function or object from a template. The C++ compiler uses compile-time instantiation, which forces instantiations to occur when the reference to the template is being compiled.

The advantages of compile-time instantiation are:

• Debugging is much easier—error messages occur within context, allowing the compiler to give a complete traceback to the point of reference.

• Template instantiations are always up-to-date.

• The overall compilation time, including the link phase, is reduced.

Templates can be instantiated multiple times if source files reside in different directories or if you use libraries with template symbols.

7.2.4 Template Instance Placement and Linkage

By default, instances go into special address sections, and the linker recognizes and discards duplicates. You can instruct the compiler to use one of five instance placement and linkage methods: external, static, global, explicit, and semi-explicit.

• External instances perform best when the following is true:

  • The set of instances in the program is small, but each compilation unit references a large subset of the instances.

  • There are few instances referenced in more than one or two compilation units.

  Static, deprecated . See below.

• Global instances, the default, are suitable for all development, and perform best when objects reference a variety of instances.

• Explicit instances are suitable for some carefully controlled application compilation environments.

• Semi-explicit instances require slightly less controlled compilation environments but produce larger object files and have restricted uses.

This section discusses the five instance placement and linkage methods. Additional information about generating instances can be found in 6.3 Template Instantiation.