Chapter 3. C++ Instantiation #pragma Directives

Instantiation #pragma directives control the instantiation of specific template entities or sets of template entities.

Table 3-1 lists the C++ instantiation #pragma directives discussed in this chapter, along with a brief description of each and the compiler versions in which the directive is supported.

Table 3-1. C++ Template Instantiation #pragma Directives

#pragma

Short Description

Compiler Versions

#pragma instantiate

Causes a specified instance of a template declaration to be immediately instantiated at that spot.

7.1 and later

#pragma can_instantiate

Indicates that the specified declaration can be instantiated in the current compilation, but need not be.

7.0 and later

#pragma do_not_instantiate

Prevents instantiation of the specific declaration in this compilation unit, even if that instance is used in the code.

7.0 and later


#pragma instantiate

The #pragma instantiate directive causes a specific instance of a template declaration to be immediately instantiated.

The syntax of the #pragma instantiate directive is as follows:

#pragma instantiate   entity   

The entity argument can be any of the following:

A template class name

A<int>

A member function name

A<int>::foo

A member function declaration

void A<int>::foo(int, char)

A static data member name

A<int>::name

A template function declaration

char* foo(int, float)

The template definition of entity must be present in the compilation for an instantiation to occur. If you use #pragma instantiate to explicitly request the instantiation of a class or function for which no template definition is available, the compiler issues a warning.

The declaration needs to be a complete declaration of a function or a static data member, exactly as if you had specified it for a specialization of the template.

The argument to an instantiation #pragma directive cannot be a compiler-generated function, an inline function, or a pure virtual function.

A member function name (for example, A<int>::foo) can be used as an argument for a #pragma instantiate directive only if it refers to a single, user-defined member function that is not an overloaded function. Compiler-generated functions are not considered, so a name can refer to a user-defined constructor even if a compiler-generated copy constructor of the same name exists. Overloaded member functions can be instantiated by providing the complete member function declaration, as the following example shows:

char * A<int>::foo(int)) 


Note: Using the #pragma instantiate directive to instantiate a template class is equivalent to repeating the directive for each member function and static data member declared in the class. When instantiating an entire class, you can exclude a given member function or static data member by using the #pragma do_not_instantiate directive.


#pragma can_instantiate

The #pragma can_instantiate directive indicates that the specified entity can be instantiated in the current compilation, but need not be. It is used in conjunction with automatic instantiation to indicate potential sites for instantiation if the template entity is deemed to be required by the compiler.

The syntax of the #pragma can_instantiate directive is as follows:

#pragma can_instantiate entity   

The argument, entity, can be any of the following:

A template class name

A<int>

A member function name

A<int>::foo

A member function declaration

void A<int>::foo(int, char)

A static data member name

A<int>::name

A template function declaration

char* foo(int, float)

The template definition of entity must be present in the compilation for an instantiation to occur. If you use #pragma can_instantiate to explicitly request the instantiation of a class or function for which no template definition is available, the compiler issues a warning.

The argument to a #pragma can_instantiate directive cannot be a compiler-generated function, an inline function, or a pure virtual function.

A member function name (for example, A<int>::foo) can be used as an argument for a #pragma can_instantiate directive only if it refers to a single, user-defined member function that is not an overloaded function. Compiler-generated functions are not considered, so a name can refer to a user-defined constructor even if a compiler-generated copy constructor of the same name exists. Overloaded member functions can be instantiated by providing the complete member function declaration, as shown in the following example:

char * A<int>::foo(int) 

#pragma do_not_instantiate

The #pragma do_not_instantiate directive suppresses the instantiation of a specified entity. It is typically used to suppress the instantiation of an entity for which a specific definition is supplied.

The syntax of the #pragma do_not_instantiate directive is as follows:

#pragma do_not_instantiate entity   

The argument, entity, can be any of the following:

A template class name

A<int>

A member function name

A<int>::foo

A member function declaration

void A<int>::foo(int, char)

A static data member name

A<int>::name

A template function declaration

char* foo(int, float)

The argument to a #pragma do_not_instantiate directive cannot be a compiler-generated function, an inline function, or a pure virtual function.

A member function name (for example, A<int>::foo) can be used as an argument for the #pragma do_not_instantiate directive only if it refers to a single, user-defined member function that is not overloaded. Compiler-generated functions are not considered, so a name can refer to a user-defined constructor even if a compiler-generated copy constructor of the same name exists. Overloaded member functions can be specified by providing the complete member function declaration, as the following example shows:

char * A<int>::foo(int)