Get Started with oneTBB

oneAPI Threading Building Blocks (oneTBB) is a runtime-based parallel programming model for C++ code that uses threads. It consists of a template-based runtime library to help you harness the latent performance of multi-core processors.

oneTBB enables you to simplify parallel programming by breaking computation into parallel running tasks. Within a single process, parallelism is carried out through threads, an operating system mechanism that allows the same or different sets of instructions to be executed simultaneously.

Here you can see one of the possible executions of tasks by threads.

Use oneTBB to write scalable applications that:

• Specify logical parallel structure instead of threads

• Emphasize data-parallel programming

• Take advantage of concurrent collections and parallel algorithms

oneTBB supports nested parallelism and load balancing. It means that you can use the library without being worried about oversubscribing a system.

System Requirements

Refer to the oneTBB System Requirements.

Before You Begin

After installing oneTBB, you need to set the environment variables:

1. Go to the oneTBB installation directory (<install_dir>). By default, <install_dir> is the following:

   • On Linux* OS:

     • For superusers (root): /opt/intel/oneapi

     • For ordinary users (non-root): $HOME/intel/oneapi

   • On Windows* OS:

     • <Program Files>\Intel\oneAPI

2. Set the environment variables, using the script in <install_dir>, by running

   • On Linux* OS:

     vars.{sh|csh} in <install_dir>/tbb/latest/env

   • On Windows* OS:

     vars.bat in <install_dir>/tbb/latest/env

Example

Below you can find a typical example for a oneTBB algorithm. The sample calculates a sum of all integer numbers from 1 to 100.

int sum = oneapi::tbb::parallel_reduce(oneapi::tbb::blocked_range<int>(1,101), 0,
   [](oneapi::tbb::blocked_range<int> const& r, int init) -> int {
      for (int v = r.begin(); v != r.end(); v++  ) {
         init += v;
      }
      return init;
   },
   [](int lhs, int rhs) -> int {
      return lhs + rhs;
   }
);

Hybrid CPU and NUMA Support

If you need NUMA/Hybrid CPU support in oneTBB, you need to make sure that HWLOC* is installed on your system.

HWLOC* (Hardware Locality) is a library that provides a portable abstraction of the hierarchical topology of modern architectures (NUMA, hybrid CPU systems, etc). oneTBB relies on HWLOC* to identify the underlying topology of the system to optimize thread scheduling and memory allocation.

Without HWLOC*, oneTBB may not take advantage of NUMA/Hybrid CPU support. Therefore, it’s important to make sure that HWLOC* is installed before using oneTBB on such systems.

Check HWLOC* on the System

To check if HWLOC* is already installed on your system, run hwloc-ls:

• For Linux* OS, in the command line.

• For Windows* OS, in the command prompt.

If HWLOC* is installed, the command displays information about the hardware topology of your system. If it is not installed, you receive an error message saying that the command hwloc-ls could not be found.

Note

For Hybrid CPU support, make sure that HWLOC* is version 2.5 or higher. For NUMA support, install HWLOC* version 1.11 or higher.

Install HWLOC*

To install HWLOC*, visit the official Portable Hardware Locality website (https://www-lb.open-mpi.org/projects/hwloc/).

• For Windows* OS, binaries are available for download.

• For Linux* OS, only the source code is provided and binaries should be built.

On Linux* OS, HWLOC* can be also installed with package managers, such as APT*, YUM*, etc. To do so, run: sudo apt install hwloc.

Note

For Hybrid CPU support, make sure that HWLOC* is version 2.5 or higher. For NUMA support, install HWLOC* version 1.11 or higher.

Find more

See our documentation to learn more about oneTBB.