TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Templates


Compile-time Instantiation

The two most common methods of template instantiation are link-time instantiation and compile-time instantiation. Cfront uses link-time instantiation. It tries to link the executable before instantiating any templates. If the attempted link results in any undefined symbols which correspond to possible template instantiations, Cfront then attempts to instantiate those template and then relinks. This process is repeated until there are no templates left to instantiate. There are two significant problems with this method. First, because the entire executable must be linked during each pass of the algorithm, link times can become incredibly long. Second, the printing of error messages is delayed as long as possible. Rather than printing error messages when compiling code that uses the instantiations, error messages are delayed until link time and there is no indication given as to what code caused that instantiation to be necessary.

Apex C++, on the other hand, uses compile-time instantiation. Templates are instantiated when the compiler first detects that they are needed. Before linking, a pre linker program is called. It makes sure that all necessary templates are instantiated and up to date (re-instantiating them if necessary), and then calls the linker exactly once. This method solves both significant problems with link-time instantiation. The linker is called just once, and error messages are printed when the templates are first used rather than at link time. Unlike some other compilers that use compile-time instantiation, Apex C++ does not require the use of any pragmas or other techniques to help the compiler with instantiation.


Finding Template Sources

When a template needs to be instantiated, the compiler must be able to find the definition for that template. Either the definition must be visible in the compilation unit that causes the instantiation, or it must be in a separate file that the compiler can find. It doesn't really matter which method is chosen; both work equally well.

The easiest way to make the definition for a template visible in the current compilation unit is to put the source code in the header file along with the template declaration. Or, the header file could include the file with the definitions.

If the compiler cannot find the definition in the current compilation unit, it looks for it in a separate file. It only looks for it in files that have the same base name as the file in which the template was originally declared. Only files with the extensions .tcc, .cc, .C, .cpp, and .cxx are considered. For example, if the template class Array< T> were declared in the file array.h, the compiler would look for files with the names array.tcc, array.cc, array.C, array.cpp, and array.cxx. It would then parse those files to see if they had the definitions of the members of class Array <T>. Extensions entries in the options file can be used to add new extensions to the list of extensions the compiler looks for. If the definition for a template is in a file with a different base name than the header file that contains the declaration, a definition entry in the options file must be used to tell the compiler the name of that file.


Template Database

The template database is managed automatically by Apex. Each view contains a ./Rational/compilation/.templates file which contains information about template instantiations. By default, the compiler will use the database in the current view. If a template database cannot be found, one will be created if necessary. The only file in the database that should be modified by the user is the options file, Template.opt, which is explained below.

Options File

The file Template.opt in the template database contains options for the database manager. Its primary purpose is to indicate to the database manager template specializations required by the program. If no options file is present, the compiler will create a default one. Each entry in the options file may span multiple lines and is terminated by a semicolon (;). Comments are started by a pound sign (#) and continue to the end of the line. Each entry in the file must be in one of the following formats:

Definition Entry

A definition entry is used to tell the compiler where the source code for a template is located. One of these entries is necessary if the source for a template is not in a location that the compiler would normally find.

name is the simple name of the template. It may not include any prototypes or return types, or the class name if the template is a member function. Only one definition entry per name is allowed. If there are several overloaded template functions with the same name, or several member functions with the same name in different template classes, they must share a single definition entry, which may have several source files listed. The names of the source files must be enclosed in quotes.

For example, assume that the source files for a program are organized as follows:

For this program to compile correctly, the options file must contain the following entries:

The locations of A <T> ::foo() and foo(T, T) are both handled by the single definition entry for foo. No entry is necessary for baz because in both cases, the compiler will be able to find the source for the templates on its own.

Specialization Entry

The compiler needs to know exactly which templates have been specialized, so it will not attempt to instantiate those particular templates. Each specialization of a template function, template class, or template class member must have its own specialization entry. The entry should not include the return type, but should include the full prototype of any functions. If a class member is static, the word static must appear in the entry. For example:

Multiple Options Files

The specified options file is textually included into the current options file. Include entries may appear anywhere in an options file, and they may be nested.

Source File Extensions

When looking for source files for templates, the compiler normally only considers files with extensions of .cc, .C, .cpp, or .cxx. An extensions entry can be used to add other extensions to the list. For example, the entry

will add .CC and .temp_src to the list of extensions that are searched.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS