Intel's Thread Building Blocks: HowTo

This document gives a quick example of how to use Intel's Thread Building Blocks, by means of a simple example. The example is available as a tarball here. The files are also available as syntax-highlighted HTML here (fatals.* and hrtime.h are elided). The latter portion of this document assumes the reader is following along using the syntax-highlighted Makefile and main.C.

Installing Thread Building Blocks

Log into the machine on which you would like to use TBB (this example uses an eight-processor x86-based machine called clover-01), and create a directory in which your TBB install will reside (you do NOT need root permissions on your machine).

Get the open-source TBB tarball from http://osstbb.intel.com/download.php (select the Commercial Aligned Release). Copy or move the tarball to whatever directory you made above. The name of the tarball in this example is tbb20_20070815oss_src.tar.gz, but your name may vary depending on the version of TBB.

Use tar to unpack the files:

CD to the new directory, and run gmake to build the TBB libraries (and run the TBB tests). The compile doesn't seem to be parallel-friendly, so don't specify any -j options. You might want to go get yourself some coffee, because this is a rather lengthy step. Note: You'll want to have X-window Forwarding ON for this step.

TBB's Programming Model

TBB provides a host of tools for the C++ programmer to leverage when writing parallel code. Chiefly these include:

• Loop Parallelization Constructs (ala OpenMP)
• Concurrent Data Structures
• Locks of Various Flavors
• Access to Low-Level Hardware Primitives
• Task Based Programming

Loop parallelization is one of the easiest ways to achieve parallelism from a single-threaded code. It is generally most useful for embarassingly data parallel applications, but can be used elsewhere with some programmer effort. The idea is simple:

1. Write a serial loop with no inter-iteration dependence
2. Apply TBB's magic to the loop
3. Voila! the loop is parallel

Summing two Arrays with TBB

The age-old problem: given two arrays, each element of the first array with its countepart in the second. Admittedly, the problem is not horribly interesting, but can still benefit from parallelism, provided the arrays are reasonably large. Follow along with main.C.

Strategy: Write some serial code to sum the arrays into a third result array. Then let TBB autoparallelize the process.

Writing Serial Code

To start off, after we initialize all the memory, parse arguments, etc., we're first going to sum the array using a single thread. We're going to use x86's high-resolution timers to find out how long the summing task runs single-threaded, so we'll know how much speedup we've gained by processing in parallel. The single-thread summing occurs at Lines 92-102 of main.C.

There is nothing special going on here -- this code is 100% straightforward.

Applying TBB's parallel_for Template

Next, we're going to implement the same loop in parallel using TBB's parallel_for template. In order to do this, we have to write some slightly arcane C++, which you can see at Lines 12-46 of main.C and at Lines 104-113 of main.C.

TBB implements parallel loops by encapsulating them inside operator functions of specialized classes. This allows the TBB library headers to handle the parallelism without making any modifications to the compiler. However, it makes the syntax a little cumbersome (moreso than, say, OpenMP's #pragma omp parallel_for).

In the example, class ArraySummer is actually an elaborate function definition. The empty constructor just initializes the "function parameters" (aka the class data members), and the operator() function actually runs the loop. Notice that the loop's bounds are encapsulated into a blocked_range. This is how TBB divides iterations among threads -- each thread's blocked_range includes a different, non-overlapping range of iterations.

Setting up the Runtime

Unpacke the Example Tarball wherever you like. To actually compile with TBB, we have to set some environment variables. A handy shell script for setting up the environment is sitting in your TBB install directory. You must source this script before building the example or any TBB-enabled application!

Use the debug version of the build if you like -- Intel's documentation details the differences in the libraries. You should source the tbbvars.csh file for C-shells and tbbvars.sh for SH-based shells.

Building with TBB

After sourcing the environment variables, the only thing to keep in mind is that you must link with the -ltbb flag. Note Line 13 of Makefile.

Running the Example Binary

Just invoke the binary with a single numeric argument (the length of the array).

Notice that TBB's parallel_for only becomes useful for larger-sized arrays...