Templates

Template Instantiation

Beginning with Release 6.50, SAS/C C++ supports both explicit instantiation and automatic instantiation of templates. The following two sections describe their features.

Explicit Instantiation

An explicit instantiation is a declaration with global scope of the form:

template declaration

where declaration specifies a template class member, a template function, or a template class name, for example,

class C<int>

An explicit instantiation must be a global declaration.

The template specialization declared is generated from its template definition in the current translation unit, even if the specialization is not used. If the autoinst option is not used, a nonstatic noninline template function or static data member of a template class may only be explicitly instantiated in one translation unit.

When declaring a specialization of a function template, a template argument list optionally may follow the function template name in order to disambiguate the declaration.

template <class X>
class C
{
   static X* sp;
};

template <class T>
T* C<T>::sp = 0;

template C<int>::sp;  // declare C<int>::sp here

The declaration may not be a definition. The template definition must be available at the point of the explict instantiation declaration.

Automatic Instantiation

The bodies of template classes and inline (or static) template functions are always instantiated implicitly when their definitions are needed. Member functions of template classes are not instantiated until they are used. Other template items can be instantiated by using explicit instantiation. However, explicit instantiation becomes unwieldy with more complex uses of templates. When the autoinst option is used, nonstatic noninline template functions and static data members of template classes are automatically implicitly instantiated. The restrictions on automatic instantiation are described below.

Implicit instantiation of a template item with autoinst requires that the option be enabled on a compilation unit, which contains both a use of the item and its corresponding template. Often, this can be arranged by including the definition of any needed templates in the header file which declares the templates.

With the autoinst option, the compiler organizes the output object module so that COOL can arrange for only one copy of each template item to be included in the final program. The original compilation unit from which the final copy is generated and the section name created for the template item are unpredictable, although the section name can be determined from the COOL listing.

Each nonstatic noninline template function or static data member of a template class that is used must be either implicitly instantiated by autoinst , explicitly instantiated in exactly one compilation unit, or else explicitly specialized and defined. Otherwise, COOL will diagnose a missing definition for the template item.

The draft C++ standard requires that nonstatic templates and inline functions that are defined in more that one compilation unit refer to the same set of objects and functions with each definition. Implicit instantiation with the autoinst option depends on this requirement being satisfied. Nonstatic template definitions of functions and static data members may not refer to global static objects and functions if the definition appears in more than one compilation unit. Uses of global statics inside a template item instantiated from such definitions will be diagnosed with WARNING 683: Implicit template instantiation uses static object . For more information on this warning message, see SAS/C Software Diagnostic Messages. An example follows:

static int i;

template <class T>
void collect( const T& t )
{
   i += t;   // use of static 'i' gets warning 683
}

void testit()
{
   collect( 1 );  // cause instantiation of
                  //collect( const int& )
}

Because global static objects and functions are available only in their original compilation units, use of statics in items implicitly instantiated from templates force the item to be inserted in the current compilation unit as if the template item were explicitly specialized. This insertion is diagnosed with WARNING 684: Static use forces automatic template instantiation in primary module . For more information on this warning message, see SAS/C Software Diagnostic Messages. This insertion may cause a multiple definition error for the template item at link time if the template was defined in more than one compilation unit.

Calls from template definitions to inline functions that use global static objects or functions cause similar problems in the direct use of those statics. Therefore, WARNING 685: Inline function uses static object will be generated for use in nonstatic inline functions. The function will be treated as static for the purposes of warning messages 683, 684, and 685. Warnings 683 and 684 are only output for items automatically instantiated by autoinst from template definitions. The definitions of explicitly specialized template items may reference global statics without generating warnings 683 or 684. For more information on these warning messages, see SAS/C Software Diagnostic Messages.

Chapter Contents
Previous
Next
Top of Page