Template Instantiation

Template instantiation is the creation of a concrete function or a concrete class out of a function template or class template. The creation of template instantiation can be implicit (compiler-generated) or explicit (user-provided).

When you need a template for a specific template argument, the compiler auto-generates it for you. Sometimes, you want to remove template definitions from header files or you want to avoid compute-power-consuming template instantiation. In this case, explicit instantiation is your friend.

Implicit Instantiation

Implicit instantiation should be your default choice. Implicit instantiation means that the compiler automatically generates the concrete function or class for the provided template arguments. In general, the compiler also deduces the template arguments from the function's arguments. In C++17, the compiler can also deduce the template arguments for class templates.

// implicitTemplateInstantiation.cpp

#include <iostream>
#include <string>
#include <vector>

template <typename T>
class MyClass{
 public:
    MyClass(T t) { }
    std::string getType() const {
        return typeid(T).name();
    }
};

template<typename T>
bool isSmaller(T fir, T sec){
    return fir < sec;
}

int main(){

    std::cout << '\n';

    std::cout << std::boolalpha;
  
    std::vector vec{1, 2, 3, 4, 5};          // (1)
    std::cout << "vec.size(): " << vec.size() << '\n';
  
    MyClass myClass(5);                      // (2)
    std::cout << "myClass.getType(): " << myClass.getType() << '\n';
  
    std::cout << '\n';
  
    std::cout << "isSmaller(5, 10): " 
              << isSmaller(5, 10) << '\n';   // (3)
    std::cout << "isSmaller<double>(5.5f, 6.5): " 
              << isSmaller<double>(5.5f, 6.5) << '\n';    // (4)
  
    std::cout << '\n';
  
}

Line (1) and (2) use class template argument deduction (CTAG). std::vector or MyClass can deduce its type from their constructor arguments. Line (3) deduces also its template argument. In line (4) on the contrary, the template argument double is explicitly specified: isSmaller<double>(5.5f, 6.5).

The compiler creates for each implicit template instantiation a concrete function or class. C++Insights visualizes this process.

This automatic process is very comfortable but has a few drawbacks.

1. When you implicit instantiate a template, the definition of the template is typically visible in a header file. Maybe, you don't want to disclose the definition.
2. When you need a template for specific template arguments, the compiler instantiates if it is not available in the concrete translation unit. A translation unit is the source file after processing of the C preprocessor. Typically, the linker removes all redundant template instantiations and keeps one. This is a waste of time and space.

Both issues can be solved with explicit template instantiation.

Explicit Instantiation

Explicit instantiation has two flavors. Explicit instantiation definition and explicit instantiation declaration.

• Explicit instantiation definition syntax: template <template declaration>
• Explicit instantiation declaration syntax: extern template <template declaration>

When you study the syntax, the keyword extern makes the difference.

Explicit template instantiation means that you generate the definition of a template. Here is a simple example.

// explicitTemplateInstantiation.cpp

#include <iostream>
#include <string>
#include <vector>

template <typename T>
class MyClass{
 public:
    MyClass(T t) { }
    std::string getType() const {
        return typeid(T).name();
    }
};

template<typename T>
bool isSmaller(T fir, T sec){
  return fir < sec;
}
 
template class std::vector<int>;                       // (1)
template bool std::vector<double>::empty() const;      // (2)

template class MyClass<int>;                           // (3)
template std::string MyClass<double>::getType() const; // (4)

template bool isSmaller(int, int);                     // (5)
template bool isSmaller<double>(double, double);       // (6)

int main(){

  std::cout << '\n';
  
  std::cout << std::boolalpha;
  
  std::vector vec{1, 2, 3, 4, 5};
  std::cout << "vec.size(): " << vec.size() << '\n';
  
  MyClass myClass(5);
  std::cout << "myClass.getType(): " << myClass.getType() << '\n';
  
  std::cout << '\n';
  
  std::cout << "isSmaller(5, 10): " 
            << isSmaller(5,10) << '\n';
  std::cout << "isSmaller<double>(5.5f, 6.5): " 
            << isSmaller<double>(5.5f, 6.5) << '\n';
  
  std::cout << '\n';
  
}

The lines (1) to (6) are the interesting ones. Thanks to the keyword template, explicit template instantiation happens.

• Line (1) explicitly instantiated std::vector for int and line (2) its member function empty for double.
• Line (3) explicitly instantiates MyClass for int and line (4) its member function getType for double.
• Line (5) explicitly instantiated isSmaller for (int, int), and line (6) does the same for (double, double) providing the explicit template argument double.

Hide the Template Implementation

How can explicit template instantiation help you hide the definition of the templates?

• Put the template declaration in the header file.
• Put the template definition in the source file. Explicitly instantiate the template at the end of the source file.
• Use the template by including the header file.

Here are three files exemplifying this process.

• Template declaration

// MyClass.h

#include <typeinfo>
#include <string>

template <typename T>
class MyClass{
 public:
    MyClass(T t) { }
    std::string getType() const;
};

• Template definition and explicit instantiation for int

// MyClass.cpp

#include "MyClass.h"

template <typename T>
std::string MyClass<T>::getType() const {
    return typeid(T).name();
}

template class MyClass<int>; 

• Template use

// mainMyClass.cpp

#include "MyClass.h"
#include <iostream>

int main() {

    std::cout << '\n'; 

    MyClass myClass(5);
    std::cout << "myClass.getType(): " << myClass.getType() << '\n';

    /*
    MyClass myClass2(5.5);
    std::cout << "myClass2.getType(): " << myClass2.getType() << '\n';
    */

    std::cout << '\n';

}

Compiling and running the program gives the expected result.

But when I try to use MyClass for another type than int, I get a linker error. This is the linker error message I get when I use the commented-out lines.

There is no template instantiation for double available.

Suppress the Template Instantiation

Assume you use MyClass<int> in various translation units which the linker puts together. Essentially, the linker throws away all template instantiations but one. This is a waste of computing time. Thanks to the use of the extern keyword in C++11, you can make out of an explicit template instantiation definition an explicit template instantiation declaration. What?

template class MyClass<int>;        // explicit instantiation definition
extern template class MyClass<int>; // explicit instantiation declaration 

The key observation is that the second line does not cause a template instantiation. This means that the compiler generates not something the linker throws away. You have only to ensure that one instantiation of MyClass<int> is for the linker available. If not, you will get a linker error. 

What's next?

After this more technical post, I write in my next post about variadic templates ... .