Template Instance Placement and Linkage

You can instruct the compiler to use one of five instance placement and linkage methods: external, static, global, explicit, and semi-explicit.

• External instances are suitable for all development and provide the best overall template compilation.

• Static instances are suitable for very small programs or debugging and have restricted uses.

• Global instances are suitable for some library construction.

• 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.

You should use the external instances method, which is the default, unless there is a very good reason to do otherwise. See the C++ Programming Guide for further information.

External Instances

With the external instances method, all instances are placed within the template repository. The compiler ensures that exactly one consistent template instance exists; instances are neither undefined nor multiply defined. Templates are reinstantiated only when necessary.

Template instances receive global linkage in the repository. Instances are referenced from the current compilation unit with external linkage.

Specify external linkage with the -instances=extern option (the default option).

Because instances are stored within the template repository, you must use the CC command to link C++ objects that use external instances into programs.

If you wish to create a library that contains all template instances that it uses, use the CC command with the -xar option. Do not use the ar command. For example:

%demo CC -xar -o libmain.a a.o b.o c.o

See Chapter 6, Building Libraries for more information.

Static Instances

With the static instances method, all instances are placed within the current compilation unit. As a consequence, templates are reinstantiated during each recompilation; instances are not saved to the template repository.

Instances receive static linkage. These instances will not be visible or usable outside the current compilation unit. As a result, templates might have identical instantiations in several object files. This has the following undesirable consequences:

• Multiple instances produce unnecessarily large programs. (Static instance linkage is therefore suitable only for small programs, where templates are unlikely to be multiply instantiated.)

• Templates that contain static variables have many copies of the variable, and this is an unavoidable violation of the C++ standard. Therefore, use of static instances is not supported with static variables within templates.

Compilation is potentially faster with static instances, so this method might also be suitable during Fix-and-Continue debugging. (See Debugging a Program With dbx.)

Specify static instance linkage with the -instances=static compiler option. You can use static instance linkage only with the definitions-included template organization. The compiler does not search for definitions. (See C++ Programming Guide.)

Global Instances

With the global instances method, all instances are placed within the current compilation unit. As a consequence, templates are reinstantiated during each recompilation; they are not saved to the template repository.

Template instances receive global linkage. These instances are visible and usable outside the current compilation unit. As a consequence, instantiation in more than one compilation unit results in multiple symbol definition errors during linking. The global instances method is therefore suitable only when you know that instances will not be repeated.

Specify global instances with the -instances=global option.

Global instances can be used only with the definitions-included template organization. The compiler does not search for definitions.

Explicit Instances

In the explicit instances method, instances are generated only for templates that are explicitly instantiated. Implicit instantiations are not satisfied. Instances are placed within the current compilation unit. As a consequence, templates are reinstantiated during each recompilation; they are not saved to the template repository.

Template instances receive global linkage. These instances are visible and usable outside the current compilation unit. Multiple explicit instantiations within a program result in multiple symbol definition errors during linking. The explicit instances method is therefore suitable only when you know that instances are not repeated, such as when you construct libraries with explicit instantiation.

Specify explicit instances with the -instances=explicit option.

You can use explicit instance linkage only with the definitions-included template organization. The compiler does not search for definitions.

Semi-Explicit Instances

When you use the semi-explicit instances method, instances are generated only for templates that are explicitly instantiated or implicitly instantiated within the body of a template. Implicit instantiations in the mainline code are not satisfied. Instances are placed within the current compilation unit. As a consequence, templates are reinstantiated during each recompilation; they are not saved to the template repository.

Explicit instances receive global linkage. These instances are visible and usable outside the current compilation unit. Multiple explicit instantiations within a program result in multiple symbol definition errors during linking.The semi-explicit instances method is therefore suitable only when you know that explicit instances will not be repeated, such as when you construct libraries with explicit instantiation.

Implicit instances used from within the bodies of explicit instances receive static linkage. These instances are not visible outside the current compilation unit. As a result, templates can have identical instantiations in several object files. This has two undesirable consequences.

• Multiple instances produce unnecessarily large programs. (Semi-explicit instance linkage is therefore suitable only for programs where template bodies do not cause multiple instantiations.)

• Templates that contain static variables have many copies of the variable; this is an unavoidable violation of the C++ standard. Therefore, use of the semi-explicit instances method is not supported with static variables within templates.

Specify semi-explicit instances with the -instances=semiexplicit option.

You can use semi-explicit instance linkage only with the definitions-included template organization. The compiler does not search for definitions.