A gentle introduction to Template Metaprogramming with C++

A gentle introduction to Template Metaprogramming with C++

moliate, 6
Mar 2003

4.91 (96 votes)

Rate this: vote 1vote 2vote 3vote 4vote 5

Abusing your compiler for extremely early binding

Download demo project - 65 Kb

Background

A while ago I was working on a program that used a large lookup table to do some computations. The contents of the table depended on a large number of parameters that I had to tweak to get optimal performance from my code. And
every time I changed one parameter the whole table had to be recalculated...
I had written a function that dumped the content of the table to standard output. That way I could compile my program with the new parameters set, cut-and-paste the table from screen and into my source code and finally recompile
the whole project. I didn't mind doing that - the first twenty times. After that I figured there had to be a better way. There was. Enter Template Metaprogramming.

What is Template Metaprogramming (TMP)

Template Metaprogramming is a generic programming technique that uses extremely early binding. The compiler acts as an interpreter or a "virtual computer" that emits the instructions that make up the final program. It can be used for static configuration, adaptive
programs, optimization and much more. 


 

In this article I intend to explain how to use C++ template classes to produce compile-time generated code.

Different kind of Metatemplates

I make a difference between two kinds on Metatemplates - ones that calculate a constant value and ones that produce code. The difference is that the first kind should never produce instructions that are executed at runtime.

Templates that calculate a value

Assume you want to calculate the number of bits set in an byte. If you do this at runtime you might have a function looking like this:

Hide   <
14f7a
span id="copycode145530" style="margin:0px;padding:0px;border:0px;">Copy Code

int bits_set(unsigned char byte)
{int count = 0;
for (int i = 0; i < 8; i++)
if ( (0x1L << i) & byte )
count++;

return count;
}

In cases where the byte is known at compile time this can also be done by the compiler, using TMP:

Hide   Copy Code

template< unsigned char byte > class BITS_SET
{
public:
enum {
B0 = (byte & 0x01) ? 1:0,
B1 = (byte & 0x02) ? 1:0,
B2 = (byte & 0x04) ? 1:0,
B3 = (byte & 0x08) ? 1:0,
B4 = (byte & 0x10) ? 1:0,
B5 = (byte & 0x20) ? 1:0,
B6 = (byte & 0x40) ? 1:0,
B7 = (byte & 0x80) ? 1:0
};
public:
enum{RESULT = B0+B1+B2+B3+B4+B5+B6+B7};
};

I have used an 

enum

 for the temporary variables as well as for the
result since they are easier to use and enumerators have the type of 

const int

. Another way would
be to use 

static const int

:s in the class instead.
You can now use 

BITS_SET<15>::RESULT

 and get the constant 

4

 in
your code. In this case the compiler evaluate the line 

enum{RESULT = B0+B1+B2+B3+B4+B5+B6+B7};

 to 

enum{RESULT
= 1+1+1+1+0+0+0+0};

 and finally to 

enum{RESULT = 4};

.
It is also possible to calculate a value using a loop. With TMP we rely on recursion within the template definition. The following code is a compile-time factorial calculator:

Hide   Copy Code

template< int i >
class FACTOR{
public:
enum {RESULT = i * FACTOR<I-1>::RESULT};
};

class FACTOR< 1 >{
public:
enum {RESULT = 1};
};

If we for example write this:

Hide   Copy Code

int j = FACTOR< 5 >::RESULT;

somewhere in our code the compiler will generate something like the following line of assembler code:

Hide   Copy Code

; int j = FACTOR< 5 >::RESULT;
mov    DWORD PTR _j$[ebp], 120            ; 00000078H - a constant value!

How does this work? As we instantiate 

FACTOR<5>

 the definition of
this class depends on 

FACTOR<4>

, which in turn depend on 

FACTOR<3>

 and
so on. The compiler needs to create all these classes until the template specialization 

FACTOR<1>

 is
reached. This means the entire recursion is done by the compiler, while the final program just contain a constant.

Templates that unroll loops/specialize functions

Template metaprograms can generate useful code when interpreted by the compiler, for example a massively inlined algorithm that has its loops unrolled. The result is usually a large speed increase in the application.
For example, look at the following code that calculates the sum of the numbers 1..1000:

Hide   Copy Code

int sum = 0;
for (int i = 1 ; i <= 1000; i++)
sum += i;

We are actually performing 2000 additions, rather than 1000 (as we have to increment 

i

 by
one for each loop). In addition we perform a thousand test operations on the variable 

i

. Another
way would be to write the code the following way:

Hide   Copy Code

int sum = 0;
sum += 1;
sum += 2;
...
sum += 1000;

This is the way a Template Metaprogram would expand a loop. Now we perform exactly a thousand additions, but this method also has a prize. The code size increase, meaning that we theoretically could take a performance hit by increasing
the number of page faults. In practice, though, code is often invoked multiple times and already loaded in cache.

Loop unrolling

Loop unrolling is easily defined using recursive templates, similar to calculating a value:

Hide   Copy Code

template< int i >
class LOOP{
public:
static inline void EXEC(){
cout << "A-" << i << " ";
LOOP< i-1 >::EXEC();
cout << "B-" << i << " ";
}
};

class LOOP< 0 >{
public:
static inline void EXEC(){
cout << "A-" << i;
cout << "\n";
cout << "B-" << i;
}
};

The output of 

LOOP< 8 >::EXEC()

 is shown below:
A-8 A-7 A-6 A-5 A-4 A-3 A-2 A-1 A-0 

B-0 B-1 B-2 B-3 B-4 B-5 B-6 B-7 B-8
Again, the thing to notice is that there is no loop in the resulting binary code. The loop unrolls itself to produce code like:

Hide   Copy Code

cout << "A-" << 8 << " ";
cout << "A-" << 7 << " ";
...
cout << "A-" << 0;
cout << "\n";
cout << "B-" << 0;
...
cout << "B-" << 7 << " ";
cout << "B-" << 8 << " ";

An unrelated, but interesting thing can be found in class 

LOOP< 0 >

.
Look at how 

LOOP< 0 >::EXEC()

 uses 

i

.
This identifier has been declared in the template 

LOOP< int i >

, but is still accessible from
the "special case" 

LOOP< 0 >

. I don't know if this is standard C++ behavior, however.
Beside loops other statements can be constructed:

IF - statement

Hide   Copy Code

template< bool Condition >
class IF {
public:
static inline void EXEC(){
cout << "Statement is true";
}
};

class IF< false > {
public:
static inline void EXEC(){
cout << "Statement is false";
}
};

 

SWITCH - statement

Hide   Copy Code

template< int _case >
class SWITCH {
public:
static inline void EXEC(){
cout << " SWITCH - default ";
}
};

class SWITCH< 1 > {
public:
static inline void EXEC(){
cout << " SWITCH - 1 ";
}
};

class SWITCH< 2 > {
public:
static inline void EXEC(){
cout << " SWITCH - 2 ";
}
};

...

Example of usage of the two classes:

Hide   Copy Code

SWITCH< 2 > myTwoSwitch; // store for delayed execution
myTwoSwitch.EXEC();
IF< false >::EXEC();
myTwoSwitch.EXEC();

The output will be: " SWITCH - 2 Statement is false SWITCH - 2 "

Using Meta-Metatemplates

It is possible to define a generic template for a special kind of operation, like an if- or for-statement. I like to call this a Meta-Metatemplate since the operation is defined in a class outside the template itself.
Even if this might be useful it can make the code very hard to understand in complex cases. Also it will probably take a few years before compilers will be able to take full advantage of these kinds of constructs. For now I prefer to use specialized templates,
but for simple cases Meta-Metatemplates might be useful. Sample code for the simplest of these constructs, the if-statement is given below:

Hide   Copy Code

template< bool Condition, class THEN, class ELSE > struct IF
{
template< bool Condition > struct selector
{typedef THEN SELECT_CLASS;};

struct selector< false >
{typedef ELSE SELECT_CLASS;};

typedef selector< Condition >::SELECT_CLASS RESULT;
};

Example of usage:

Hide   Copy Code

struct THEN
{
static int func()
{cout << "Inside THEN";
return 42;
}
};

struct ELSE
{
static int func()
{cout << "Inside ELSE";
return 0;
}
};

int main(int argc, char* argv[])
{
int result = IF< 4 == sizeof(int), THEN, ELSE >::RESULT::func();
cout << " - returning: " << result;
}

On 32-bit architectures this will print "Inside THEN - returning: 42" to standard output. Note that if 

func()

 was
not defined inside 

ELSE

 this would be a simple compile-time assert breaking compilation on 

4
!= sizeof(int)

.

A real world example

Included as a sample is a small class that does generic CRC (Cyclic Redundancy Codes - a set of simple hash algorithms) calculations. The class uses a set of parameters that are 

#define

:d
at the top of the header. The main reason I chose CRC for this article is that the CRC algorithms usually use a lookup table based on a set of parameters, making the example somewhat similar to my original problem.
The class generate a lookup table with 256 entries at compile time. The implementation is pretty straightforward, and I hope that the comments in the source is enough to explain usage of the class. In some cases I have used macros
where TMP would have been a possible solution. The reason for this is readability, an important factor when choosing which technique to use. 

If you want a further explanation of CRC algorithms, I suggest reading Ross N. Williams "A PAINLESS GUIDE TO CRC ERROR DETECTION ALGORITHMS". I have included a verbatim copy of the text in the sample.
One thing to remember when compiling this is that the source is using a lot of compiler heap memory. I had to increase the memory allocation limit by using the compiler option '/Zm400'. This is one drawback of
TMP - it really pushes the compiler to the limit.

Coding conventions

The compiler doesn't like being abused as described above. Not a bit. And it will put up a struggle. Warnings and errors will range from cryptic to C1001 - INTERNAL COMPILER ERROR. And you can't debug a Metatemplate
program like a runtime program.
For those reasons using well defined coding conventions is more important with TMP than with other programming techniques. Below I give some rules that I've found useful.

General suggestions

As template metaprograms are somewhat similar to macros I prefer to give all TMP classes uppercase names. Also try to make the name as descriptive as possible. The main reason for this is that public variables/functions usually
have non-descriptive names (see below). A TMP class is the one defining the operation, not the member functions/variables.

Also try to limit a TMP class to a single operation. Template Metaprogramming is challenging enough without trying to generalize the class to support multiple operations. Often this will only result in code bloat.

Variable/functions names

I usually prefer to have only one of two possible public operations defined in a TMP class:

RESULT

 for templates that calculate
a value

EXEC()

 for loop unrolling/function
simplification.

Usually one function or one member variable is the only thing the Template Metaprogram needs to expose to the programmer. It makes sense to give the type of operation a single name for all possible classes. Another advantage is that you can
look at a template class and immediately see if it is a Template Metaprogram or an ordinary template class.

Should I use TMP in my program?

Template Metaprogramming is a great technique when used correctly. On the other hand it might result in code bloat and performance decrease. Below are some rules of thumb when to use TMP.

Use TMP when:

A macro is not enough. You need something more complex than a macro, and you need it expanded before compiled.
Using recursive function with a predetermined number of loops. In this case the overhead of function calls and setting up stack variables can be avoided and runtime will significantly
decrease.
Using loops that can be unrolled at compile time. For example hash-algorithms like MD5 and SHA1 contains well-defined block processing loops that can be unrolled with TMP.
When calculating constant values. If you have constants that depend on other constants in your program, they might be a candidate for TMP.
When the program should be portable to other platforms. In this case TMP might be an alternative to macros.

Don't use TMP when:

When a macro will do. In most cases a macro will be enough. And a macro is often easier to understand than TMP.
You want a small executable. Templates in general, and TMP in particular will in often increase the code size.
Your program already takes a long time to compile. TMP might significantly increase compile time.
You are on a strict deadline. As noted above the complier will be very unfriendly when working with Template Metaprograms. Unless the changes you intend to make are very simple,
you might want to save yourself a few hours of banging your head in the wall.

Acknowledgements and references

Thanks to Joaquín M López Muñoz for
introducing me to TMP.
Ross N. Williams has written a great tutorial on CRC algorithms: "A PAINLESS GUIDE TO CRC ERROR DETECTION ALGORITHMS". I have included a verbatim copy in the sample (zip-ball?) above.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.
A list of licenses authors might use can be found here