Scenario when using Explicit Template Instantiation

(Compliments of Kian-Tat Lim)

If explicit instantiation can be used (i.e. if all template parameters that will be used by the application are known ahead of time), then the following is the best method:

1) Put only the interface (template definition) in a .h file in a public include directory.

2) Put only the implementation in a .cc file in a private implementation or source directory. This does not actually need to be compiled as such (although doing so does no harm, as it generates no code).

3) Add an additional .cc file that includes the .h file, the implementation .cc file from #2, and then explicitly instantiates the templates with the known parameters using "template class C<T>;" statements.

4) Compile everything, including application code, with -fno-implicit-templates.

5) Make sure the explicit instantiations resulting from compiling the .cc file in #3 are included in the appropriate library for application code to link against.

This method isolates the application from changes to the template implementation, requiring only a relink against the new library rather than a recompile against the new template implementation code.

User Friendly Templates: A Scenario

Create scenario allowing framework developers to use templates but hiding template complexity from application developers.

Constraints

* no use of 'export';

* no multiple copies of classes/methods in executable.

Desirable but NOT implemented

* no template definition parsing during user application compile.

Implementation

Original method described was updated 21 May 2007 compliments of Kian-Tat Lim who stated that now "changes to the [application] implementation only require a relink by the application, not a recompile -- a huge win".

Implementation is primarily effected using smoke, mirrors and typedefs in user include file:  userBuffer.h

// File: userBuffer.h
//
//    Declare template instantiations to be used.
//
//    By declaring explictly the template instantiations to be used  and
//    loading with the 'ld' flag '-no-implicit-templates', the object file
//    built will include single copies of templated methods.

#include "buffer.h"               //this inserts template source code

// Instantiations of Buffer template
//    followed by typedef for simpler naming by users
typedef Buffer<float> buffer_float;

typedef Buffer<double> buffer_double;

typedef Buffer<int> buffer_int;

Template definition:  buffer.h.

The framework developer's .cc file to build the library file containing the explicitly instantiated template methods:  templates.cc

The application developer's code accessing the developer-provided instantiation of the template methods:  userProg.cc

Build object library of instantiated template classes/methods using:  developerBuild

Build user application using instantiated template classes/methods from library using:  userBuild

Undesirable aspect of method

The template definition is still accessed and parsed by the application code.

However, no new instantiated method is included in the executable.

Untested

Ease of creating a typedef for a template which invokes another template in its parameter list, etc.